@opengeni/react 0.1.0

package/src/hooks/internal.ts

@@ -0,0 +1,236 @@
+import type { SessionEvent } from "@opengeni/sdk";
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { SessionClientLike } from "../client";
+
+export type AsyncListState<T> = {
+  data: T | null;
+  loading: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+};
+
+/**
+ * Shared fetch + optional polling loop for the list/read hooks. Stale
+ * responses (superseded by a newer load or an unmount) are dropped.
+ */
+export function usePolledValue<T>(load: () => Promise<T>, options: { pollIntervalMs?: number | undefined; enabled?: boolean | undefined } = {}): AsyncListState<T> {
+  const enabled = options.enabled ?? true;
+  const pollIntervalMs = options.pollIntervalMs;
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(enabled);
+  const [error, setError] = useState<Error | null>(null);
+  const generation = useRef(0);
+  const loadRef = useRef(load);
+
+  // A new loader identity means a new query (different session/workspace/...):
+  // drop the previous result instead of showing it as the new query's data.
+  useEffect(() => {
+    if (loadRef.current !== load) {
+      loadRef.current = load;
+      setData(null);
+      setError(null);
+    }
+  }, [load]);
+
+  const run = useCallback(async () => {
+    const ticket = ++generation.current;
+    try {
+      const result = await load();
+      if (ticket === generation.current) {
+        setData(result);
+        setError(null);
+        setLoading(false);
+      }
+    } catch (cause) {
+      if (ticket === generation.current) {
+        setError(cause instanceof Error ? cause : new Error(String(cause)));
+        setLoading(false);
+      }
+    }
+  }, [load]);
+
+  useEffect(() => {
+    if (!enabled) {
+      setLoading(false);
+      return;
+    }
+    setLoading(true);
+    void run();
+    if (pollIntervalMs === undefined || pollIntervalMs <= 0) {
+      return () => {
+        generation.current += 1;
+      };
+    }
+    const timer = setInterval(() => void run(), pollIntervalMs);
+    return () => {
+      clearInterval(timer);
+      generation.current += 1;
+    };
+  }, [run, enabled, pollIntervalMs]);
+
+  return { data, loading, error, refresh: run };
+}
+
+export type MutationState = {
+  mutating: boolean;
+  mutationError: Error | null;
+  clearMutationError: () => void;
+};
+
+/**
+ * Shared async mutation runner for the write hooks. `run` resolves with the
+ * operation's value, or `null` after capturing the error in `mutationError`
+ * (callers then roll back optimistic state).
+ */
+export function useMutationRunner(): MutationState & {
+  run: <T>(operation: () => Promise<T>) => Promise<T | null>;
+} {
+  const [mutating, setMutating] = useState(false);
+  const [mutationError, setMutationError] = useState<Error | null>(null);
+  const inFlight = useRef(0);
+  const mounted = useRef(true);
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+  const run = useCallback(async <T,>(operation: () => Promise<T>): Promise<T | null> => {
+    inFlight.current += 1;
+    if (mounted.current) {
+      setMutating(true);
+      setMutationError(null);
+    }
+    try {
+      return await operation();
+    } catch (cause) {
+      if (mounted.current) {
+        setMutationError(cause instanceof Error ? cause : new Error(String(cause)));
+      }
+      return null;
+    } finally {
+      inFlight.current -= 1;
+      if (mounted.current && inFlight.current === 0) {
+        setMutating(false);
+      }
+    }
+  }, []);
+  return {
+    mutating,
+    mutationError,
+    clearMutationError: useCallback(() => setMutationError(null), []),
+    run,
+  };
+}
+
+export type SessionEventFeedOptions = {
+  /**
+   * Share an existing event log (from `useSessionEvents`) instead of opening
+   * a second stream. When omitted the hook tails the session's event stream
+   * itself, starting at the current `lastSequence`.
+   */
+  events?: SessionEvent[] | undefined;
+  enabled?: boolean | undefined;
+};
+
+/**
+ * Invoke `onEvent` for every session event matching `match` — the live-update
+ * primitive behind `useTurnQueue` and `useGoal`. Either watches a shared
+ * `events` log or tails the stream directly (reconnect handled by the SDK).
+ */
+export function useSessionEventTrigger(
+  client: SessionClientLike,
+  workspaceId: string,
+  sessionId: string | null | undefined,
+  match: (event: SessionEvent) => boolean,
+  onEvent: (event: SessionEvent) => void,
+  options: SessionEventFeedOptions = {},
+): void {
+  const enabled = options.enabled ?? true;
+  const events = options.events;
+  const sharedFeed = events !== undefined;
+  const matchRef = useRef(match);
+  matchRef.current = match;
+  const onEventRef = useRef(onEvent);
+  onEventRef.current = onEvent;
+  const consumedRef = useRef(0);
+  const feedKeyRef = useRef<string | null>(null);
+
+  // Shared-log mode: scan only the unseen tail on every append.
+  useEffect(() => {
+    if (!sharedFeed || !enabled || !sessionId) {
+      return;
+    }
+    const feedKey = `${workspaceId}\u0000${sessionId}`;
+    const firstSequence = events[0]?.sequence ?? 0;
+    // A new session target or a log reset (sequence restarted below the
+    // cursor) restarts consumption from the top of the shared log.
+    if (feedKeyRef.current !== feedKey || firstSequence > consumedRef.current + 1) {
+      feedKeyRef.current = feedKey;
+      consumedRef.current = 0;
+    }
+    for (const event of events) {
+      if (event.sequence <= consumedRef.current) {
+        continue;
+      }
+      consumedRef.current = event.sequence;
+      if (matchRef.current(event)) {
+        onEventRef.current(event);
+      }
+    }
+  }, [sharedFeed, enabled, events, workspaceId, sessionId]);
+
+  // Self-stream mode: tail from the session's current lastSequence.
+  useEffect(() => {
+    if (sharedFeed || !enabled || !sessionId) {
+      return;
+    }
+    const controller = new AbortController();
+    void (async () => {
+      try {
+        const session = await client.getSession(workspaceId, sessionId);
+        if (controller.signal.aborted) {
+          return;
+        }
+        const stream = client.streamEvents(workspaceId, sessionId, {
+          after: session.lastSequence,
+          signal: controller.signal,
+        });
+        for await (const event of stream) {
+          if (matchRef.current(event)) {
+            onEventRef.current(event);
+          }
+        }
+      } catch {
+        // Live updates are best-effort: the read hooks still expose refresh()
+        // and the initial load already populated state.
+      }
+    })();
+    return () => {
+      controller.abort();
+    };
+  }, [sharedFeed, enabled, client, workspaceId, sessionId]);
+}
+
+/** Debounce rapid event bursts into one trailing call (default 150ms). */
+export function useDebouncedCallback(callback: () => void, delayMs = 150): () => void {
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(() => {
+    return () => {
+      if (timerRef.current !== null) {
+        clearTimeout(timerRef.current);
+      }
+    };
+  }, []);
+  return useCallback(() => {
+    if (timerRef.current !== null) {
+      clearTimeout(timerRef.current);
+    }
+    timerRef.current = setTimeout(() => {
+      timerRef.current = null;
+      callbackRef.current();
+    }, delayMs);
+  }, [delayMs]);
+}

package/src/hooks/use-billing-usage.ts

@@ -0,0 +1,51 @@
+import type { BillingBalance, UsageEvent } from "@opengeni/sdk";
+import { useCallback } from "react";
+import { useOpenGeniClient, type ClientOverride } from "../provider";
+import { usePolledValue } from "./internal";
+
+export type UseBillingUsageOptions = Pick<ClientOverride, "client"> & {
+  /** Account to read. Defaults to the caller's default account server-side. */
+  accountId?: string | undefined;
+  /** Filter usage to one workspace. */
+  workspaceId?: string | undefined;
+  /** Refresh interval (ms) for live billing meters. Off by default. */
+  pollIntervalMs?: number | undefined;
+  enabled?: boolean | undefined;
+};
+
+export type UseBillingUsageResult = {
+  /** Prepaid credit balance (micro-USD), null until loaded. */
+  balance: BillingBalance | null;
+  /** Recent usage events (runs, tokens, cost, uploads, ...). */
+  usage: UsageEvent[];
+  loading: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+};
+
+/**
+ * Account billing usage: credit balance + recent usage events — the data
+ * behind per-call billing meters. Account-scoped, so it only needs the
+ * client; pass `workspaceId` to narrow usage to one workspace.
+ */
+export function useBillingUsage(options: UseBillingUsageOptions = {}): UseBillingUsageResult {
+  const client = useOpenGeniClient(options);
+  const accountId = options.accountId;
+  const workspaceId = options.workspaceId;
+  const load = useCallback(
+    async () =>
+      await client.getBillingUsage({
+        ...(accountId !== undefined ? { accountId } : {}),
+        ...(workspaceId !== undefined ? { workspaceId } : {}),
+      }),
+    [client, accountId, workspaceId],
+  );
+  const state = usePolledValue(load, { pollIntervalMs: options.pollIntervalMs, enabled: options.enabled });
+  return {
+    balance: state.data?.balance ?? null,
+    usage: state.data?.usage ?? [],
+    loading: state.loading,
+    error: state.error,
+    refresh: state.refresh,
+  };
+}

package/src/hooks/use-composer.ts

@@ -0,0 +1,213 @@
+import type { SendMessageInput } from "@opengeni/sdk";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useOpenGeni, type ClientOverride } from "../provider";
+
+export type ComposerSendExtras = Omit<SendMessageInput, "text" | "clientEventId">;
+
+/**
+ * Compose-time delivery choice. `queue` (the default) stacks the message
+ * behind the running turn — visible, editable, reorderable until claimed.
+ * `steer` interrupts the running turn and injects the message now.
+ */
+export type ComposerMode = "queue" | "steer";
+
+export type UseComposerOptions = ClientOverride & {
+  /** Called with the accepted text after a successful send. */
+  onSent?: ((text: string) => void) | undefined;
+  /**
+   * Extra message fields (resources, tools, model, reasoningEffort) merged
+   * into every send. A function is evaluated at send time so it can read the
+   * surrounding UI state (attachment pickers, model selectors, ...).
+   */
+  sendExtras?: ComposerSendExtras | (() => ComposerSendExtras) | undefined;
+  /** Initial delivery mode. Defaults to `"queue"`. */
+  defaultMode?: ComposerMode | undefined;
+};
+
+export type ComposerState = {
+  value: string;
+  setValue: (value: string) => void;
+  /** Send the draft (or an explicit text) using the current mode. */
+  send: (text?: string) => Promise<boolean>;
+  sending: boolean;
+  canSend: boolean;
+  /** Queue (default) vs steer — the compose-time delivery choice. */
+  mode: ComposerMode;
+  setMode: (mode: ComposerMode) => void;
+  /** Ask the agent to stop the current turn. */
+  interrupt: (reason?: string) => Promise<void>;
+  interrupting: boolean;
+  error: Error | null;
+  clearError: () => void;
+};
+
+/**
+ * Draft + send + interrupt state for the chat composer — the only
+ * human-to-agent input surface. The draft survives a failed send (nothing is
+ * more hostile than losing a typed message); each send carries a generated
+ * `clientEventId` so retries stay idempotent server-side.
+ */
+export function useComposer(sessionId: string | null | undefined, options: UseComposerOptions = {}): ComposerState {
+  const { client, workspaceId } = useOpenGeni(options);
+  const defaultMode = options.defaultMode ?? "queue";
+  const [value, setValue] = useState("");
+  const [mode, setMode] = useState<ComposerMode>(defaultMode);
+  const [sending, setSending] = useState(false);
+  const [interrupting, setInterrupting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const pendingClientEventId = useRef<string | null>(null);
+  const onSent = options.onSent;
+  // Read at send time so an in-flight send uses the mode chosen at submit.
+  const modeRef = useRef(mode);
+  modeRef.current = mode;
+  // Read through a ref so a new extras closure (created every render by
+  // callers passing inline functions) does not invalidate `send`.
+  const sendExtrasRef = useRef(options.sendExtras);
+  sendExtrasRef.current = options.sendExtras;
+
+  // A composer is bound to one session: switching targets must not leak the
+  // previous session's draft, error, or retry idempotency key.
+  const targetKey = `${workspaceId}\u0000${sessionId ?? ""}`;
+  const targetKeyRef = useRef(targetKey);
+  useEffect(() => {
+    if (targetKeyRef.current !== targetKey) {
+      targetKeyRef.current = targetKey;
+      pendingClientEventId.current = null;
+      setValue("");
+      setError(null);
+      setMode(defaultMode);
+    }
+  }, [targetKey, defaultMode]);
+
+  const send = useCallback(
+    async (explicit?: string): Promise<boolean> => {
+      const draftAtSend = value;
+      const text = (explicit ?? draftAtSend).trim();
+      // Resolve the extras once: a file-only message (empty text + ≥1 ready
+      // resource) is legitimate, so we must not bail on empty text alone.
+      const extras = resolveSendExtras(sendExtrasRef.current);
+      const hasResources = (extras.resources?.length ?? 0) > 0;
+      if ((!text && !hasResources) || !sessionId || sending) {
+        return false;
+      }
+      // Reuse the clientEventId across retries of the same draft so a
+      // timeout + resend cannot double-deliver the message.
+      pendingClientEventId.current ??= generateClientEventId();
+      setSending(true);
+      setError(null);
+      try {
+        // The wire contract requires non-empty text (z.string().min(1)) and the
+        // worker rejects whitespace-only text; a file-only message therefore
+        // carries a minimal default so the attachments still get delivered.
+        const sendText = text || FILE_ONLY_MESSAGE_TEXT;
+        const input = composeSendInput(sendText, pendingClientEventId.current, extras);
+        if (modeRef.current === "steer") {
+          await client.steerMessage(workspaceId, sessionId, input);
+        } else {
+          await client.sendMessage(workspaceId, sessionId, input);
+        }
+        pendingClientEventId.current = null;
+        if (explicit === undefined) {
+          // Clear only the draft that was sent: edits made while the request
+          // was in flight were never delivered and must survive.
+          setValue((current) => (current === draftAtSend ? "" : current));
+        }
+        onSent?.(sendText);
+        return true;
+      } catch (cause) {
+        setError(cause instanceof Error ? cause : new Error(String(cause)));
+        return false;
+      } finally {
+        setSending(false);
+      }
+    },
+    [client, workspaceId, sessionId, value, sending, onSent],
+  );
+
+  // A send is possible with non-empty text OR with ≥1 attached resource (a
+  // file-only message). Resources ride in `sendExtras`, so we resolve them here
+  // — keeping useComposer attachment-agnostic while still lighting up the send
+  // affordance the moment a file is ready. ChatComposer additionally gates this
+  // on its `attachments.uploading` flag so a message never departs mid-upload.
+  const hasReadyResources = (resolveSendExtras(sendExtrasRef.current).resources?.length ?? 0) > 0;
+
+  const interrupt = useCallback(
+    async (reason?: string): Promise<void> => {
+      if (!sessionId || interrupting) {
+        return;
+      }
+      setInterrupting(true);
+      setError(null);
+      try {
+        await client.interrupt(workspaceId, sessionId, reason !== undefined ? { reason } : {});
+      } catch (cause) {
+        setError(cause instanceof Error ? cause : new Error(String(cause)));
+      } finally {
+        setInterrupting(false);
+      }
+    },
+    [client, workspaceId, sessionId, interrupting],
+  );
+
+  const updateValue = useCallback((next: string) => {
+    pendingClientEventId.current = null;
+    setValue(next);
+  }, []);
+
+  return {
+    value,
+    setValue: updateValue,
+    send,
+    sending,
+    canSend: Boolean(sessionId) && !sending && (value.trim().length > 0 || hasReadyResources),
+    mode,
+    setMode,
+    interrupt,
+    interrupting,
+    error,
+    clearError: useCallback(() => setError(null), []),
+  };
+}
+
+/**
+ * Default text for a file-only message (attachment(s) present, no typed draft).
+ * Kept non-empty so the wire contract (`text: z.string().min(1)`) and the
+ * worker's non-whitespace guard accept it; the attached files still ride in
+ * `resources`. Exported for tests.
+ */
+export const FILE_ONLY_MESSAGE_TEXT = "(see attached files)";
+
+/** Resolve possibly-deferred extras to a concrete bag (function evaluated now). */
+export function resolveSendExtras(
+  extras: ComposerSendExtras | (() => ComposerSendExtras) | undefined,
+): ComposerSendExtras {
+  return (typeof extras === "function" ? extras() : extras) ?? {};
+}
+
+/**
+ * Merge the draft text + idempotency key with caller-provided extras. The
+ * text and clientEventId always win over extras. Exported for tests.
+ */
+export function composeSendInput(
+  text: string,
+  clientEventId: string,
+  extras: ComposerSendExtras | (() => ComposerSendExtras) | undefined,
+): SendMessageInput {
+  return { ...resolveSendExtras(extras), text, clientEventId };
+}
+
+/** Submit on plain Enter; Shift+Enter inserts a newline. Exported for tests. */
+export function shouldSubmitOnKey(event: { key: string; shiftKey: boolean; nativeEvent?: { isComposing?: boolean } }): boolean {
+  if (event.key !== "Enter" || event.shiftKey) {
+    return false;
+  }
+  return event.nativeEvent?.isComposing !== true;
+}
+
+function generateClientEventId(): string {
+  const cryptoApi = globalThis.crypto;
+  if (cryptoApi && "randomUUID" in cryptoApi) {
+    return cryptoApi.randomUUID();
+  }
+  return `ce-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}

package/src/hooks/use-environments.ts

@@ -0,0 +1,118 @@
+import type {
+  CreateWorkspaceEnvironmentRequest,
+  UpdateWorkspaceEnvironmentRequest,
+  WorkspaceEnvironment,
+  WorkspaceEnvironmentVariableMetadata,
+} from "@opengeni/sdk";
+import { useCallback } from "react";
+import { useOpenGeni, type ClientOverride } from "../provider";
+import { useMutationRunner, usePolledValue } from "./internal";
+
+export type UseEnvironmentsOptions = ClientOverride & {
+  pollIntervalMs?: number | undefined;
+  enabled?: boolean | undefined;
+};
+
+export type UseEnvironmentsResult = {
+  environments: WorkspaceEnvironment[];
+  loading: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+  create: (request: CreateWorkspaceEnvironmentRequest) => Promise<WorkspaceEnvironment | null>;
+  update: (environmentId: string, request: UpdateWorkspaceEnvironmentRequest) => Promise<WorkspaceEnvironment | null>;
+  remove: (environmentId: string) => Promise<boolean>;
+  /** Set/rotate a variable. Values are write-only — reads expose metadata only. */
+  setVariable: (environmentId: string, name: string, value: string) => Promise<WorkspaceEnvironmentVariableMetadata | null>;
+  deleteVariable: (environmentId: string, name: string) => Promise<boolean>;
+  mutating: boolean;
+  mutationError: Error | null;
+  clearMutationError: () => void;
+};
+
+/**
+ * Workspace environments (named, encrypted variable sets attached to sessions
+ * and scheduled tasks). Variable values are write-only end to end: this hook
+ * never sees a value after it is sent.
+ */
+export function useEnvironments(options: UseEnvironmentsOptions = {}): UseEnvironmentsResult {
+  const { client, workspaceId } = useOpenGeni(options);
+  const load = useCallback(async () => await client.listEnvironments(workspaceId), [client, workspaceId]);
+  const state = usePolledValue(load, { pollIntervalMs: options.pollIntervalMs, enabled: options.enabled });
+  const mutation = useMutationRunner();
+
+  const create = useCallback(
+    async (request: CreateWorkspaceEnvironmentRequest): Promise<WorkspaceEnvironment | null> => {
+      const result = await mutation.run(() => client.createEnvironment(workspaceId, request));
+      if (result) {
+        await state.refresh();
+      }
+      return result;
+    },
+    [client, workspaceId, mutation.run, state.refresh],
+  );
+
+  const update = useCallback(
+    async (environmentId: string, request: UpdateWorkspaceEnvironmentRequest): Promise<WorkspaceEnvironment | null> => {
+      const result = await mutation.run(() => client.updateEnvironment(workspaceId, environmentId, request));
+      if (result) {
+        await state.refresh();
+      }
+      return result;
+    },
+    [client, workspaceId, mutation.run, state.refresh],
+  );
+
+  const remove = useCallback(
+    async (environmentId: string): Promise<boolean> => {
+      const result = await mutation.run(async () => {
+        await client.deleteEnvironment(workspaceId, environmentId);
+        return true;
+      });
+      if (result) {
+        await state.refresh();
+      }
+      return result === true;
+    },
+    [client, workspaceId, mutation.run, state.refresh],
+  );
+
+  const setVariable = useCallback(
+    async (environmentId: string, name: string, value: string): Promise<WorkspaceEnvironmentVariableMetadata | null> => {
+      const result = await mutation.run(() => client.setEnvironmentVariable(workspaceId, environmentId, name, value));
+      if (result) {
+        await state.refresh();
+      }
+      return result;
+    },
+    [client, workspaceId, mutation.run, state.refresh],
+  );
+
+  const deleteVariable = useCallback(
+    async (environmentId: string, name: string): Promise<boolean> => {
+      const result = await mutation.run(async () => {
+        await client.deleteEnvironmentVariable(workspaceId, environmentId, name);
+        return true;
+      });
+      if (result) {
+        await state.refresh();
+      }
+      return result === true;
+    },
+    [client, workspaceId, mutation.run, state.refresh],
+  );
+
+  return {
+    environments: state.data ?? [],
+    loading: state.loading,
+    error: state.error,
+    refresh: state.refresh,
+    create,
+    update,
+    remove,
+    setVariable,
+    deleteVariable,
+    mutating: mutation.mutating,
+    mutationError: mutation.mutationError,
+    clearMutationError: mutation.clearMutationError,
+  };
+}