@opengeni/react 7.4.0 → 7.5.0-canary.36927100590001

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 };
+}

package/src/index.ts

@@ -536,6 +536,8 @@ export { MessageTimeline, TimelineRow } from "./components/message-timeline";
 export { GeneratedVideoPlayer } from "./components/generated-video-player";
 export type { GeneratedVideoPlayerProps } from "./components/generated-video-player";
 export type { MessageTimelineProps } from "./components/message-timeline";
+export type { RenderAllowanceExhausted } from "./timeline/allowance-exhausted-row";
+export type { AllowanceLabels, AllowanceScope } from "./usage/allowance-copy";
 export type { TimelineSearchTarget } from "./components/timeline-search";
 export { UserMessageBody, userMessageLikelyNeedsDisclosure } from "./components/user-message-body";
 export type {
@@ -557,13 +559,20 @@ export {
   chainLinkResolvers,
   sessionLinkResolver,
   useOpenGeniLinkResolver,
+  viewerLinkResolver,
 } from "./components/open-geni-links";
 export type {
   OpenGeniLinkResolution,
   OpenGeniLinkResolver,
   OpenGeniLinkTarget,
+  OpenGeniViewerTarget,
 } from "./components/open-geni-links";
 export { parseOpenGeniLink } from "@opengeni/sdk";
+export {
+  ArtifactLabelsProvider,
+  DEFAULT_ARTIFACT_LABELS,
+  type ArtifactLabels,
+} from "./components/artifacts/artifact-chrome";
 export { CopyButton, CopyHoverFrame } from "./components/copy-button";
 export { copyTextToClipboard, tableElementToTsv } from "./lib/clipboard";
 export { SessionStatus, StatusDot, SESSION_STATUS_META } from "./components/session-status";
@@ -588,6 +597,19 @@ export { PierreDiff } from "./components/pierre-diff";
 // Opt in to the optional `@pierre/diffs` peer with `enablePierreDiffs()` from
 // `@opengeni/react/diffs`; the root entry never names the peer.
 export { registerPierreDiffs, type PierreDiffsLoader } from "./lib/pierre-diffs-loader";
+// Bundler-visible optional workbench imports live only on opt-in subpaths.
+export {
+  registerSandboxTerminal,
+  registerCodeEditor,
+  registerDesktopViewer,
+} from "./lib/workbench-peers";
+export type {
+  WorkbenchPeerLoader,
+  SandboxTerminalPeers,
+  CodeEditorPeers,
+  CodeEditorLanguage,
+  CodeEditorLanguages,
+} from "./lib/workbench-peers";
 export type { PierreDiffProps } from "./components/pierre-diff";
 export { PierreFile } from "./components/pierre-file";
 export type { PierreFileProps } from "./components/pierre-file";

package/src/lib/format.ts

@@ -111,20 +111,46 @@ export function tryParseJson(text: string): unknown {
 export const CREDIT_EXHAUSTION_MESSAGE =
   "Out of Opengeni credits — this workspace's balance is empty. Add credits to continue; the conversation is preserved.";
 
+/** A usage ceiling refused the send; the default allowance wording, plus what is safe. */
+export const COMPOSER_MEMBER_ALLOWANCE_MESSAGE =
+  "Usage limit reached. A workspace admin can raise this limit. Your draft is preserved.";
+export const COMPOSER_WORKSPACE_ALLOWANCE_MESSAGE =
+  "Workspace usage limit reached. An organization admin can raise the workspace budget. Your draft is preserved.";
+
 /**
  * Actionable composer copy for an edge rejection before a turn is accepted.
  * Unlike an in-flight credit exhaustion, this path has not consumed the
  * actor-private draft or any finalized attachment.
  */
 export const COMPOSER_PAYMENT_REQUIRED_MESSAGE =
-  "This turn requires Opengeni managed credits, but the account balance is empty. Add credits or choose a connected Codex subscription model, then retry. Your draft and attachments are preserved.";
+  "Your organization doesn't have enough OpenGeni credits to send this message. Add credits or choose a model with another payment source. Your message and attachments are saved.";
 
 export function composerSubmissionErrorMessage(error: Error): string {
-  return error instanceof OpenGeniApiError &&
-    error.status === 402 &&
-    error.code === "payment_required"
-    ? COMPOSER_PAYMENT_REQUIRED_MESSAGE
-    : error.message;
+  if (error instanceof OpenGeniApiError && error.code === "allowance_exhausted") {
+    // OpenGeniAllowanceExhaustedError carries the scope; read it structurally
+    // so this startup-path helper adds no SDK or wording imports.
+    return (error as { scope?: unknown }).scope === "workspace"
+      ? COMPOSER_WORKSPACE_ALLOWANCE_MESSAGE
+      : COMPOSER_MEMBER_ALLOWANCE_MESSAGE;
+  }
+  return isComposerCreditRefusal(error) ? COMPOSER_PAYMENT_REQUIRED_MESSAGE : error.message;
+}
+
+/** These definitive refusals need a payment or allowance change, not an unchanged retry. */
+export function composerSubmissionCanRetry(error: Error): boolean {
+  return !(
+    isComposerCreditRefusal(error) ||
+    (error instanceof OpenGeniApiError && error.code === "allowance_exhausted")
+  );
+}
+
+function isComposerCreditRefusal(error: Error): boolean {
+  return (
+    (error instanceof OpenGeniApiError &&
+      error.status === 402 &&
+      (error.code === "payment_required" || error.code === "insufficient_credits")) ||
+    isCreditExhaustion(error.message)
+  );
 }
 
 /**

package/src/lib/workbench-peers.ts

@@ -0,0 +1,62 @@
+import type { DesktopRfbFactory } from "@opengeni/sdk";
+
+/** Host-owned imports keep optional peers outside the root's bundler graph. */
+export type WorkbenchPeerLoader<T = unknown> = () => Promise<T>;
+export type CodeEditorLanguage = "javascript" | "json" | "python" | "markdown" | "css" | "html";
+export type CodeEditorLanguages = Partial<Record<CodeEditorLanguage, WorkbenchPeerLoader>>;
+export type CodeEditorPeers = { module: unknown; languages?: CodeEditorLanguages | undefined };
+export type SandboxTerminalPeers = {
+  Terminal: unknown;
+  FitAddon: unknown;
+  WebLinksAddon: unknown;
+  loadWebgl?: WorkbenchPeerLoader | undefined;
+};
+
+function optionalPeer<T>(setup: string) {
+  let loader: WorkbenchPeerLoader<T> | null = null;
+  let loaded: Promise<T> | null = null;
+  let version = 0;
+  const listeners = new Set<() => void>();
+  return {
+    register(next: WorkbenchPeerLoader<T> | null): void {
+      if (next === loader) return;
+      loader = next;
+      loaded = null;
+      version += 1;
+      for (const listener of listeners) listener();
+    },
+    revision: () => version,
+    subscribe(listener: () => void): () => void {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    load(): Promise<T> {
+      if (!loader) return Promise.reject(new Error(`Call ${setup} to enable this surface`));
+      if (!loaded) {
+        // A synchronous host-loader failure is also a rejected, retryable load.
+        const pending = Promise.resolve()
+          .then(loader)
+          .catch((error: unknown) => {
+            if (loaded === pending) loaded = null;
+            throw error;
+          });
+        loaded = pending;
+      }
+      return loaded;
+    },
+  };
+}
+
+export const sandboxTerminalPeers = optionalPeer<SandboxTerminalPeers>(
+  "enableSandboxTerminal() from @opengeni/react/terminal",
+);
+export const codeEditorPeers = optionalPeer<CodeEditorPeers>(
+  "enableCodeEditor() from @opengeni/react/editor",
+);
+export const desktopViewerPeers = optionalPeer<DesktopRfbFactory>(
+  "enableDesktopViewer() from @opengeni/react/desktop",
+);
+
+export const registerSandboxTerminal = sandboxTerminalPeers.register;
+export const registerCodeEditor = codeEditorPeers.register;
+export const registerDesktopViewer = desktopViewerPeers.register;

package/src/session-ui.ts

@@ -13,18 +13,27 @@ export type { ApprovalSurfaceProps, ApprovalSurfaceMessages } from "./components
 export type { HumanInputSurfaceProps } from "./components/human-input-surface";
 export { MessageTimeline, TimelineRow } from "./components/message-timeline";
 export type { MessageTimelineProps } from "./components/message-timeline";
+export type { RenderAllowanceExhausted } from "./timeline/allowance-exhausted-row";
+export type { AllowanceLabels, AllowanceScope } from "./usage/allowance-copy";
 export {
   OpenGeniLinkProvider,
   chainLinkResolvers,
   sessionLinkResolver,
   useOpenGeniLinkResolver,
+  viewerLinkResolver,
 } from "./components/open-geni-links";
 export type {
   OpenGeniLinkResolution,
   OpenGeniLinkResolver,
   OpenGeniLinkTarget,
+  OpenGeniViewerTarget,
 } from "./components/open-geni-links";
 export { parseOpenGeniLink } from "@opengeni/sdk";
+export {
+  ArtifactLabelsProvider,
+  DEFAULT_ARTIFACT_LABELS,
+  type ArtifactLabels,
+} from "./components/artifacts/artifact-chrome";
 export type { TimelineSearchTarget } from "./components/timeline-search";
 export { createOlderHistoryLoadReceipt } from "./older-history";
 export type { OlderHistoryLoader, OlderHistoryLoadReceipt } from "./older-history";
@@ -43,6 +52,19 @@ export type {
   TurnSummaryOptions,
 } from "./timeline/turn-summary";
 export { QueueSurface } from "./components/queue-surface";
+// The provider too, so a host needs only this entry (the root also exports the
+// workbench, whose editors, terminal and desktop are optional peers).
+export { OpenGeniProvider } from "./provider";
+export type { OpenGeniProviderProps } from "./provider";
+// The tool-renderer registry, so custom tool renderers need no root import.
+export { createDefaultToolRegistry, createToolRegistry, defaultToolRegistry } from "./timeline";
+export type {
+  CreateToolRegistryOptions,
+  ToolRegistry,
+  ToolRegistryEntry,
+  ToolRenderer,
+  ToolRendererProps,
+} from "./timeline";
 export { SessionConversation } from "./components/session-conversation";
 export { SessionList } from "./components/session-list";
 export type { SessionListLabels, SessionListProps } from "./components/session-list";

package/src/terminal.ts

@@ -0,0 +1,26 @@
+import {
+  registerSandboxTerminal,
+  type SandboxTerminalPeers,
+  type WorkbenchPeerLoader,
+} from "./lib/workbench-peers";
+
+export { SandboxTerminal } from "./components/sandbox-terminal";
+export type { SandboxTerminalProps, XtermTheme } from "./components/sandbox-terminal";
+export { registerSandboxTerminal } from "./lib/workbench-peers";
+
+async function loadTerminal(): Promise<SandboxTerminalPeers> {
+  const [{ Terminal }, { FitAddon }, { WebLinksAddon }] = await Promise.all([
+    import("@xterm/xterm"),
+    import("@xterm/addon-fit"),
+    import("@xterm/addon-web-links"),
+  ]);
+  return { Terminal, FitAddon, WebLinksAddon };
+}
+
+/** Opt in once on a terminal route; WebGL remains a separate optional import. */
+export function enableSandboxTerminal(options?: { webgl?: WorkbenchPeerLoader | undefined }): void {
+  const loadWebgl = options?.webgl;
+  registerSandboxTerminal(
+    loadWebgl ? async () => ({ ...(await loadTerminal()), loadWebgl }) : loadTerminal,
+  );
+}

package/src/timeline/activity-rail.tsx

@@ -105,7 +105,8 @@ export function ActivityRail({
   const providerResponded = phases.some(
     (item) => item.phase === "provider_first_byte" && item.status === "complete",
   );
-  const preparing =
+  const responsePending = phases.some((item) => item.phase === "provider_first_byte");
+  const loading =
     !hasWork &&
     !interrupted &&
     (startupActive ?? (!providerResponded && phases.some((item) => item.status === "running")));
@@ -164,7 +165,7 @@ export function ActivityRail({
       )}
     >
       <AnimatePresence initial={false}>
-        {preparing && !debug ? (
+        {loading && !debug ? (
           <motion.div
             key="startup"
             initial={{ opacity: 0 }}
@@ -182,13 +183,14 @@ export function ActivityRail({
           >
             <GenieLoading
               startedAt={startedAt}
+              phase={responsePending ? "waiting" : "preparing"}
               detailsOpen={detailsOpen}
               onShowDetails={() => setDetailsOpen((open) => !open)}
             />
           </motion.div>
         ) : null}
       </AnimatePresence>
-      {detailsOpen && !debug && !preparing ? (
+      {detailsOpen && !debug && !loading ? (
         <button
           type="button"
           className="og-genie-details self-start"

package/src/timeline/allowance-exhausted-row.tsx

@@ -0,0 +1,86 @@
+import type { AllowanceExhaustedRefusal } from "@opengeni/sdk";
+import { GaugeIcon } from "lucide-react";
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+
+import { cn } from "../lib/cn";
+import {
+  allowanceLabels,
+  allowanceResetSentence,
+  formatAllowanceInstant,
+  type AllowanceLabels,
+} from "../usage/allowance-copy";
+import { useEntranceAnimation } from "./entrance";
+
+/**
+ * Replace the built-in "usage limit reached" row. Return `undefined` to keep
+ * the default for this refusal (for example, only customize member limits).
+ */
+export type RenderAllowanceExhausted = (
+  refusal: AllowanceExhaustedRefusal,
+  context: { labels: AllowanceLabels; defaultRow: ReactNode },
+) => ReactNode | undefined;
+
+type AllowancePresentation = {
+  render: RenderAllowanceExhausted | undefined;
+  labels: AllowanceLabels;
+};
+
+const AllowancePresentationContext = createContext<AllowancePresentation>({
+  render: undefined,
+  labels: allowanceLabels(),
+});
+
+export function AllowancePresentationProvider({
+  render,
+  labels,
+  children,
+}: {
+  render: RenderAllowanceExhausted | undefined;
+  labels: Partial<AllowanceLabels> | undefined;
+  children: ReactNode;
+}) {
+  const value = useMemo(() => ({ render, labels: allowanceLabels(labels) }), [render, labels]);
+  return (
+    <AllowancePresentationContext.Provider value={value}>
+      {children}
+    </AllowancePresentationContext.Provider>
+  );
+}
+
+/**
+ * A usage ceiling stopped further work. Calm by design: nothing failed, the
+ * conversation is kept, and the row says who can raise the limit and when it
+ * resets. Never the server's prose or a member identifier.
+ */
+export function AllowanceExhaustedRow({ refusal }: { refusal: AllowanceExhaustedRefusal }) {
+  const { render, labels } = useContext(AllowancePresentationContext);
+  const enter = useEntranceAnimation();
+  const workspace = refusal.scope === "workspace";
+  const defaultRow = (
+    <div
+      className={cn(
+        enter && "animate-og-enter",
+        "flex items-start gap-2.5 rounded-og-md border border-og-status-waiting/35 bg-og-status-waiting/8 px-3.5 py-2.5 text-og-menu text-og-fg",
+      )}
+      role="status"
+      data-og-allowance-exhausted={refusal.scope}
+    >
+      <GaugeIcon aria-hidden className="mt-0.5 size-4 shrink-0 text-og-status-waiting" />
+      <div className="min-w-0 flex-1">
+        <p className="font-medium">
+          {workspace ? labels.workspaceLimitReachedTitle : labels.memberLimitReachedTitle}
+        </p>
+        <p className="mt-0.5 text-og-fg-muted">
+          {workspace ? labels.workspaceRemedy : labels.memberRemedy}{" "}
+          <span
+            title={refusal.resetsAt ? formatAllowanceInstant(refusal.resetsAt) : undefined}
+            className="whitespace-nowrap"
+          >
+            {allowanceResetSentence(labels, refusal.resetsAt)}
+          </span>
+        </p>
+      </div>
+    </div>
+  );
+  return <>{render?.(refusal, { labels, defaultRow }) ?? defaultRow}</>;
+}

package/src/timeline/genie-loading.tsx

@@ -4,6 +4,7 @@ import { createContext, useContext, useEffect, useState, type ReactNode } from "
 
 export type GenieLoadingRenderProps = {
   startedAt: string;
+  phase: "preparing" | "waiting";
   detailsOpen: boolean;
   onShowDetails: () => void;
 };
@@ -55,19 +56,23 @@ const PHRASES = [
   "Putting a wish into motion…",
   "A little hocus. A little pocus…",
 ];
+const WAITING_PHRASES = ["Waiting for a response…"];
 
 /** Decorative copy never substitutes for a failure or claims measurable progress. */
 export function GenieLoading({
   startedAt,
+  phase = "preparing",
   onShowDetails,
   detailsOpen = false,
 }: {
   startedAt: string;
+  phase?: GenieLoadingRenderProps["phase"];
   onShowDetails: () => void;
   detailsOpen?: boolean;
 }) {
   const options = useContext(GenieLoadingOptionsContext);
-  const phrases = options?.phrases?.length ? options.phrases : PHRASES;
+  const waiting = phase === "waiting";
+  const phrases = options?.phrases?.length ? options.phrases : waiting ? WAITING_PHRASES : PHRASES;
   const theme = useThemeType(undefined);
   const [phrase, setPhrase] = useState(0);
   const [showDetails, setShowDetails] = useState(false);
@@ -82,7 +87,7 @@ export function GenieLoading({
     const timer = window.setInterval(update, 5_000);
     return () => window.clearInterval(timer);
   }, [startedAt, phrases]);
-  if (options?.render) return options.render({ startedAt, detailsOpen, onShowDetails });
+  if (options?.render) return options.render({ startedAt, phase, detailsOpen, onShowDetails });
   return (
     <div className="og-genie-loading">
       <div
@@ -99,12 +104,17 @@ export function GenieLoading({
       <div className="og-genie-copy">
         <span className="sr-only" role="status">
           {slow
-            ? (options?.messages?.slowStatus ?? "Preparing your task. Taking longer than usual.")
-            : (options?.messages?.status ?? "Preparing your task.")}
+            ? (options?.messages?.slowStatus ??
+              (waiting
+                ? "Waiting for a response. Taking longer than usual."
+                : "Preparing your task. Taking longer than usual."))
+            : (options?.messages?.status ??
+              (waiting ? "Waiting for a response." : "Preparing your task."))}
         </span>
         <span key={slow ? "slow" : phrase} className="og-genie-phrase" aria-hidden="true">
           {slow
-            ? (options?.messages?.slowText ?? "A little longer than usual…")
+            ? (options?.messages?.slowText ??
+              (waiting ? "Still waiting for a response…" : "A little longer than usual…"))
             : phrases[phrase % phrases.length]}
         </span>
         {showDetails || detailsOpen ? (
@@ -116,7 +126,7 @@ export function GenieLoading({
           >
             {detailsOpen
               ? (options?.messages?.hideDetails ?? "Hide details")
-              : (options?.messages?.showDetails ?? "Behind the magic")}
+              : (options?.messages?.showDetails ?? (waiting ? "Show details" : "Behind the magic"))}
             <span aria-hidden="true"> ↗</span>
           </button>
         ) : null}