@opengeni/react 1.0.1 → 1.0.2-canary.37191796234001

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/lib/xterm-theme.ts

@@ -24,11 +24,13 @@ export type TokenReader = (name: string) => string | undefined;
  * The 16 ANSI colors + selection/cursor treatment, designed against the og
  * OKLCH palette. Hues are borrowed from the og status ramp so terminal color
  * reads as part of the same system: red≈status-failed(22), green≈status-idle
- * (155), yellow≈status-running(80), blue≈accent(255), magenta≈status-waiting
- * (305), cyan≈200. Dark uses lifted lightness on the dark slate ground; light
- * uses deeper, more saturated inks on the near-white ground. Bright variants
- * add lightness + a touch of chroma. `black`/`white` are neutral slate ramp
- * stops (never pure #000/#fff — that clashes with the calm neutral ground).
+ * (155), yellow≈status-running(80), magenta(305), cyan≈200. The ANSI blue and
+ * magenta slots stay chromatic because program output means them; the app
+ * chrome around the terminal is neutral. Dark uses lifted lightness on the
+ * dark neutral ground; light uses deeper, more saturated inks on the
+ * near-white ground. Bright variants add lightness + a touch of chroma.
+ * `black`/`white` and the selection are neutral grey ramp stops (never pure
+ * #000/#fff — that clashes with the calm neutral ground).
  */
 export type AnsiPalette = {
   black: string;
@@ -54,47 +56,47 @@ export type AnsiPalette = {
 };
 
 const DARK_ANSI: AnsiPalette = {
-  black: "oklch(0.3 0.014 260)",
+  black: "oklch(0.3 0 0)",
   red: "oklch(0.68 0.17 22)",
   green: "oklch(0.75 0.13 155)",
   yellow: "oklch(0.8 0.11 80)",
   blue: "oklch(0.7 0.14 255)",
   magenta: "oklch(0.72 0.13 305)",
   cyan: "oklch(0.75 0.1 210)",
-  white: "oklch(0.8 0.01 260)",
-  brightBlack: "oklch(0.45 0.014 260)",
+  white: "oklch(0.8 0 0)",
+  brightBlack: "oklch(0.45 0 0)",
   brightRed: "oklch(0.76 0.17 22)",
   brightGreen: "oklch(0.82 0.14 155)",
   brightYellow: "oklch(0.86 0.12 85)",
   brightBlue: "oklch(0.78 0.13 255)",
   brightMagenta: "oklch(0.8 0.13 305)",
   brightCyan: "oklch(0.83 0.1 200)",
-  brightWhite: "oklch(0.97 0.005 260)",
-  selectionBackground: "oklch(0.72 0.15 255 / 0.34)",
-  selectionForeground: "oklch(0.985 0.005 260)",
-  selectionInactiveBackground: "oklch(0.72 0.02 260 / 0.22)",
+  brightWhite: "oklch(0.97 0 0)",
+  selectionBackground: "oklch(0.8 0 0 / 0.3)",
+  selectionForeground: "oklch(0.985 0 0)",
+  selectionInactiveBackground: "oklch(0.72 0 0 / 0.2)",
 };
 
 const LIGHT_ANSI: AnsiPalette = {
-  black: "oklch(0.35 0.015 260)",
+  black: "oklch(0.35 0 0)",
   red: "oklch(0.52 0.19 22)",
   green: "oklch(0.5 0.13 155)",
   yellow: "oklch(0.56 0.13 80)",
   blue: "oklch(0.52 0.18 255)",
   magenta: "oklch(0.52 0.16 305)",
   cyan: "oklch(0.52 0.1 210)",
-  white: "oklch(0.7 0.01 260)",
-  brightBlack: "oklch(0.5 0.014 260)",
+  white: "oklch(0.7 0 0)",
+  brightBlack: "oklch(0.5 0 0)",
   brightRed: "oklch(0.55 0.2 22)",
   brightGreen: "oklch(0.54 0.14 155)",
   brightYellow: "oklch(0.6 0.14 80)",
   brightBlue: "oklch(0.48 0.19 255)",
   brightMagenta: "oklch(0.54 0.17 305)",
   brightCyan: "oklch(0.54 0.11 210)",
-  brightWhite: "oklch(0.3 0.015 260)",
-  selectionBackground: "oklch(0.55 0.18 255 / 0.24)",
-  selectionForeground: "oklch(0.21 0.015 260)",
-  selectionInactiveBackground: "oklch(0.6 0.02 260 / 0.16)",
+  brightWhite: "oklch(0.3 0 0)",
+  selectionBackground: "oklch(0.45 0 0 / 0.2)",
+  selectionForeground: "oklch(0.21 0 0)",
+  selectionInactiveBackground: "oklch(0.6 0 0 / 0.14)",
 };
 
 /** The designed ANSI-16 palette for a theme mode. Pure. */
@@ -110,8 +112,8 @@ export function ogAnsiPalette(mode: ThemeMode): AnsiPalette {
  */
 export function buildXtermTheme(read: TokenReader, mode: ThemeMode): XtermTheme {
   const ansi = ogAnsiPalette(mode);
-  const bgFallback = mode === "light" ? "oklch(0.978 0.003 260)" : "oklch(0.155 0.012 260)";
-  const fgFallback = mode === "light" ? "oklch(0.21 0.015 260)" : "oklch(0.955 0.005 260)";
+  const bgFallback = mode === "light" ? "#ffffff" : "#202020";
+  const fgFallback = mode === "light" ? "#242424" : "#e6e6e6";
   const bg = read("--og-color-bg") ?? bgFallback;
   const fg = read("--og-color-fg") ?? fgFallback;
   const accent = read("--og-color-accent") ?? ansi.brightBlue;

package/src/machines.ts

@@ -9,6 +9,7 @@
 export type {
   ConnectionStatus,
   MachineKind,
+  MachineOperationPolicy,
   MachineMetricsSeriesResponse,
   MachineState,
   MachineView,
@@ -48,6 +49,8 @@ export type {
 } from "./components/machines/metric-history-chart";
 export { MachineDetail } from "./components/machines/machine-detail";
 export type { MachineDetailProps } from "./components/machines/machine-detail";
+export { MachineOperationPolicyEditor } from "./components/machines/machine-operation-policy";
+export type { MachineOperationPolicyEditorProps } from "./components/machines/machine-operation-policy";
 export { METRICS, METRIC_WINDOWS, WINDOW_LABEL, pointsFor } from "./components/machines/series";
 export type { MetricDef, MetricKey, MetricWindow } from "./components/machines/series";
 export { MachinesDashboard } from "./components/machines-dashboard";
@@ -68,7 +71,12 @@ export type {
   EnrollmentConsentPhase,
   EnrollmentConsentProps,
 } from "./components/enrollment-consent";
-export { useMachines } from "./hooks/use-machines";
+export {
+  useMachines,
+  MACHINES_COMPOSER_POLL_MS,
+  MACHINES_DASHBOARD_POLL_MS,
+  MACHINES_SESSION_POLL_MS,
+} from "./hooks/use-machines";
 export type {
   MachinesClientLike,
   UseMachinesOptions,

package/src/mcp-connection-status.ts

@@ -0,0 +1,35 @@
+import type { CapabilityCatalogItem, ConnectionMetadata } from "@opengeni/sdk";
+
+/** Status only; runtime use is authorized for the authenticated initiating user. */
+export function matchingActiveMcpConnections(
+  item: CapabilityCatalogItem,
+  connections: ConnectionMetadata[],
+) {
+  return matchingMcpConnections(item, connections).filter((entry) => entry.status === "active");
+}
+
+function matchingMcpConnections(item: CapabilityCatalogItem, connections: ConnectionMetadata[]) {
+  const ref = item.connectionRef;
+  if (!item.enabled || !ref) return [];
+  return connections.filter(
+    (entry) =>
+      entry.status !== "revoked" &&
+      entry.kind === "oauth2" &&
+      entry.metadata.mcpUrl === (item.mcpUrl ?? item.endpointUrl) &&
+      (ref.subjectScope !== "subject"
+        ? entry.id === ref.connectionId && entry.subjectId === null
+        : entry.subjectId !== null),
+  );
+}
+
+/** Installation availability is not account readiness. Revoked history is not actionable. */
+export function mcpConnectionDiscoveryState(
+  item: CapabilityCatalogItem,
+  connections: ConnectionMetadata[],
+) {
+  const matching = matchingMcpConnections(item, connections);
+  const active = matching.filter((entry) => entry.status === "active");
+  if (active.length === 1) return { status: "added", label: "Connected" } as const;
+  if (matching.length > 0) return { status: "attention", label: "Review connection" } as const;
+  return { status: "available", label: "Connect" } as const;
+}

package/src/model-policy.ts

@@ -1,10 +1,12 @@
+import {
+  compareModelPickerOrder,
+  modelPickerBillingClassFor,
+  type ModelPickerBillingClass,
+} from "@opengeni/sdk/model-picker-order";
+import { modelDisplayName } from "@opengeni/sdk/model-display";
 import type { ClientModel, ReasoningEffort, WorkspaceModelCatalogModel } from "@opengeni/sdk";
 
-export type PickerBillingClass =
-  | "opengeni_credits"
-  | "codex_subscription"
-  | "supergrok_subscription"
-  | "byok";
+export type PickerBillingClass = ModelPickerBillingClass;
 
 export type PickerModelRow<TCatalog extends ClientModel = WorkspaceModelCatalogModel> = {
   id: string;
@@ -22,18 +24,23 @@ export type PickerModelRow<TCatalog extends ClientModel = WorkspaceModelCatalogM
 
 export type LatencyModeId = "standard" | "priority" | "fast";
 
-const BILLING_CLASS_ORDER: PickerBillingClass[] = [
-  "opengeni_credits",
-  "codex_subscription",
-  "supergrok_subscription",
-  "byok",
-];
-
 const BILLING_CLASS_LABELS: Record<PickerBillingClass, string> = {
-  opengeni_credits: "OpenGeni",
+  opengeni_credits: "Models",
+  external: "External",
   codex_subscription: "Codex",
   supergrok_subscription: "SuperGrok",
-  byok: "Your Gateway",
+  claude_subscription: "Claude subscription",
+  // Who connected the key (organization or workspace) is a settings fact, not
+  // a model choice: both scopes share one label and one picker group.
+  byok: "API keys",
+  organization_byok: "API keys",
+};
+
+/** Models settings keeps naming who connected the key. */
+const SCOPED_BILLING_CLASS_LABELS: Record<PickerBillingClass, string> = {
+  ...BILLING_CLASS_LABELS,
+  byok: "Workspace providers",
+  organization_byok: "Organization providers",
 };
 
 const AVAILABILITY_REASON_LABELS: Record<string, string> = {
@@ -47,36 +54,29 @@ const AVAILABILITY_REASON_LABELS: Record<string, string> = {
 };
 
 export function billingClassForModel(model: ClientModel): PickerBillingClass {
-  if (model.source === "supergrok") {
-    return "supergrok_subscription";
-  }
-  if (model.source === "codex") {
-    return "codex_subscription";
-  }
-  if (model.source === "workspace_gateway") {
-    return "byok";
+  if (model.provider === "organization-gateway" || model.provider === "organization-openrouter") {
+    return "organization_byok";
   }
-  if (model.credentialSource?.kind === "connected_subscription") {
-    return model.credentialSource.provider === "xai"
-      ? "supergrok_subscription"
-      : "codex_subscription";
-  }
-  if (model.credentialSource?.kind === "workspace_connection") {
+  if (
+    model.provider?.startsWith("workspace-openai-") ||
+    model.provider?.startsWith("workspace-azure-openai-")
+  )
     return "byok";
-  }
-  if (model.billing?.upstreamPayer === "connected_subscription") {
-    return "codex_subscription";
-  }
-  if (model.billing?.upstreamPayer === "workspace") {
+  if (model.provider === "workspace-gateway" || model.provider === "workspace-openrouter") {
     return "byok";
   }
-  return "opengeni_credits";
+  return modelPickerBillingClassFor(model);
 }
 
 export function billingClassLabel(billingClass: PickerBillingClass): string {
   return BILLING_CLASS_LABELS[billingClass];
 }
 
+/** The group label that names the connection scope, for Models settings only. */
+export function scopedBillingClassLabel(billingClass: PickerBillingClass): string {
+  return SCOPED_BILLING_CLASS_LABELS[billingClass];
+}
+
 export function availabilityReasonLabel(
   reason: WorkspaceModelCatalogModel["availability"]["reason"],
 ): string | null {
@@ -137,37 +137,84 @@ export function labelReasoningEffort(effort: ReasoningEffort): string {
   return effort.slice(0, 1).toUpperCase() + effort.slice(1);
 }
 
+/** Payment prompts must use cost policy, never the presentation group. */
+export function modelUsesCredits(model: ClientModel | undefined): boolean {
+  if (model?.cost !== undefined) return model.cost === "credits";
+  return model?.billing?.metering === "opengeni_credits";
+}
+
 export function payerSummaryForModel(model: ClientModel): string {
+  if (model.cost === "free") {
+    return "Free in this deployment";
+  }
+  if (model.cost === "credits") {
+    return "Opengeni credits";
+  }
+  if (model.cost === "subscription") {
+    return model.credentialSource?.kind === "connected_subscription" &&
+      model.credentialSource.provider === "claude"
+      ? "Claude subscription · external billing"
+      : model.source === "supergrok"
+        ? "SuperGrok subscription · external billing"
+        : "Codex subscription · external billing";
+  }
+  if (model.cost === "workspace") {
+    return workspaceProviderPayerSummary(model);
+  }
+  if (model.cost === "organization") {
+    return organizationProviderPayerSummary(model);
+  }
+
+  // Older client-config payloads do not carry `cost`; preserve their existing
+  // settlement-derived label until every deployment has rolled forward.
   const billing = model.billing;
   if (!billing) {
     return "Route unknown";
   }
   if (billing.metering === "opengeni_credits") {
-    return "OpenGeni credits · automatic managed route";
+    return "Opengeni credits · automatic managed route";
   }
   if (billing.upstreamPayer === "connected_subscription") {
-    return model.source === "supergrok"
-      ? "SuperGrok subscription · external billing"
-      : "Codex subscription · external billing";
+    return model.credentialSource?.kind === "connected_subscription" &&
+      model.credentialSource.provider === "claude"
+      ? "Claude subscription · external billing"
+      : model.source === "supergrok"
+        ? "SuperGrok subscription · external billing"
+        : "Codex subscription · external billing";
   }
   if (billing.upstreamPayer === "workspace") {
-    return "Billed to your AI Gateway";
+    return workspaceProviderPayerSummary(model);
+  }
+  if (billing.upstreamPayer === "organization") {
+    return organizationProviderPayerSummary(model);
   }
-  return "Deployment route · external billing";
+  return billing.upstreamPayer === "deployment"
+    ? "Opengeni · no model credits"
+    : "External provider · no Opengeni credits";
 }
 
 export function advancedSourceSummary(model: ClientModel): string | null {
   const source = model.credentialSource;
   if (!source) {
-    return null;
+    return model.billing?.metering === "external" && model.billing.upstreamPayer === "deployment"
+      ? "Deployment-provided connection"
+      : null;
   }
   if (source.kind === "connected_subscription") {
-    return source.provider === "xai"
-      ? "Connected SuperGrok subscription"
-      : "Connected Codex subscription";
+    return source.provider === "claude"
+      ? "Connected Claude subscription"
+      : source.provider === "xai"
+        ? "Connected SuperGrok subscription"
+        : "Connected Codex subscription";
   }
   if (source.kind === "workspace_connection") {
-    return "Workspace AI Gateway";
+    if (model.provider === "workspace-openrouter") {
+      return "Workspace OpenRouter connection";
+    }
+    if (model.provider === "workspace-gateway" || model.source === "workspace_gateway") {
+      return "Workspace Vercel AI Gateway";
+    }
+    return "Workspace provider connection";
   }
   if (source.kind === "deployment") {
     return source.mechanism === "azure_ad_bearer"
@@ -177,18 +224,53 @@ export function advancedSourceSummary(model: ClientModel): string | null {
   return null;
 }
 
+function workspaceProviderPayerSummary(model: ClientModel): string {
+  if (model.provider === "workspace-anthropic")
+    return "Billed to the workspace Anthropic API account";
+  if (model.provider === "workspace-claude-subscription")
+    return "Uses the workspace Claude subscription · no OpenGeni credits";
+  if (model.provider === "workspace-openrouter") {
+    return "Billed to the workspace OpenRouter account";
+  }
+  if (model.provider === "workspace-gateway" || model.source === "workspace_gateway") {
+    return "Billed to the workspace Vercel account";
+  }
+  return "Billed to the workspace provider account";
+}
+
+function organizationProviderPayerSummary(model: ClientModel): string {
+  if (model.provider === "organization-anthropic")
+    return "Billed to the organization Anthropic API account";
+  if (model.provider === "organization-claude-subscription")
+    return "Uses the connected Claude subscription · no OpenGeni credits";
+  if (model.provider === "organization-openrouter") {
+    return "Billed to the organization OpenRouter account";
+  }
+  if (model.provider === "organization-gateway") {
+    return "Billed to the organization Vercel account";
+  }
+  return "Billed to the organization provider account";
+}
+
+/**
+ * The curated compact label, else the family-free name for Claude models
+ * ("Opus 5.5"): the maker's mark beside it already says Claude.
+ */
+function compactLabel(catalog: ClientModel): { shortLabel?: string } {
+  if (catalog.shortLabel) return { shortLabel: catalog.shortLabel };
+  const name = modelDisplayName(catalog);
+  return name.startsWith("Claude ") ? { shortLabel: name.slice("Claude ".length) } : {};
+}
+
 export function projectPickerRows(models: WorkspaceModelCatalogModel[]): PickerModelRow[] {
   return models
-    .filter((catalog) => {
-      const billingClass = billingClassForModel(catalog);
-      return billingClass === "opengeni_credits" || catalog.credentialReadiness.status === "ready";
-    })
+    .filter((catalog) => catalog.credentialReadiness.status === "ready")
     .map((catalog) => {
       const billingClass = billingClassForModel(catalog);
       return {
         id: catalog.id,
-        label: catalog.label,
-        ...(catalog.shortLabel ? { shortLabel: catalog.shortLabel } : {}),
+        label: modelDisplayName(catalog),
+        ...compactLabel(catalog),
         billingClass,
         billingClassLabel: billingClassLabel(billingClass),
         selectable: catalog.availability.selectable,
@@ -208,8 +290,8 @@ export function projectClientModelRows(models: ClientModel[]): PickerModelRow<Cl
     const billingClass = billingClassForModel(catalog);
     return {
       id: catalog.id,
-      label: catalog.label,
-      ...(catalog.shortLabel ? { shortLabel: catalog.shortLabel } : {}),
+      label: modelDisplayName(catalog),
+      ...compactLabel(catalog),
       billingClass,
       billingClassLabel: billingClassLabel(billingClass),
       selectable: true,
@@ -224,18 +306,7 @@ export function projectClientModelRows(models: ClientModel[]): PickerModelRow<Cl
 export function sortPickerRows<TCatalog extends ClientModel>(
   rows: PickerModelRow<TCatalog>[],
 ): PickerModelRow<TCatalog>[] {
-  return [...rows].sort((left, right) => {
-    const classDelta =
-      BILLING_CLASS_ORDER.indexOf(left.billingClass) -
-      BILLING_CLASS_ORDER.indexOf(right.billingClass);
-    if (classDelta !== 0) {
-      return classDelta;
-    }
-    if (left.selectable !== right.selectable) {
-      return left.selectable ? -1 : 1;
-    }
-    return left.label.localeCompare(right.label);
-  });
+  return [...rows].sort(compareModelPickerOrder);
 }
 
 export function findPickerRow<TCatalog extends ClientModel>(
@@ -245,11 +316,62 @@ export function findPickerRow<TCatalog extends ClientModel>(
   return rows.find((row) => row.id === modelId) ?? null;
 }
 
+export type GroupPickerRowsOptions = {
+  codexOnly?: boolean;
+  /**
+   * Default true: organization- and workspace-connected keys share one group
+   * and identical copies show once. Models settings passes false.
+   */
+  collapseScopes?: boolean | undefined;
+  /** Kept visible when it has an identical twin (see below). */
+  selectedId?: string | undefined;
+};
+
+/**
+ * Organization- and workspace-connected API keys are one choice for the person
+ * picking a model, so they share one group.
+ */
+function displayGroupFor(billingClass: PickerBillingClass): PickerBillingClass {
+  return billingClass === "organization_byok" ? "byok" : billingClass;
+}
+
+/**
+ * The same model through the same provider kind, whichever scope connected it:
+ * `organization-anthropic/claude-opus-5-5` and `workspace-anthropic/claude-opus-5-5`
+ * share a key, while OpenRouter and the Anthropic API never do (different
+ * accounts and bills).
+ */
+function scopeFreeIdentity(row: PickerModelRow<ClientModel>): string | null {
+  const provider = row.provider.replace(/^(?:organization|workspace)-/, "");
+  if (provider === row.provider) return null;
+  const upstream =
+    row.catalog.deployment?.upstreamModelId ??
+    (row.id.startsWith(`${row.provider}/`) ? row.id.slice(row.provider.length + 1) : row.id);
+  return `${provider}\u0000${upstream}`;
+}
+
+/**
+ * Two rows that are the same model through the same provider kind, connected
+ * by the organization and by the workspace, are one choice: show one. Keep the
+ * current selection, else a selectable row, else the first in picker order.
+ */
+function prefersTwin<TCatalog extends ClientModel>(
+  candidate: PickerModelRow<TCatalog>,
+  current: PickerModelRow<TCatalog>,
+  selectedId: string | undefined,
+): boolean {
+  if (selectedId !== undefined && current.id === selectedId) return false;
+  if (selectedId !== undefined && candidate.id === selectedId) return true;
+  return candidate.selectable && !current.selectable;
+}
+
 export function groupPickerRowsByBillingClass(
   rows: PickerModelRow[],
+  options?: GroupPickerRowsOptions,
 ): Array<{ billingClass: PickerBillingClass; label: string; rows: PickerModelRow[] }>;
 export function groupPickerRowsByBillingClass<TCatalog extends ClientModel>(
   rows: PickerModelRow<TCatalog>[],
+  options?: GroupPickerRowsOptions,
 ): Array<{
   billingClass: PickerBillingClass;
   label: string;
@@ -257,6 +379,7 @@ export function groupPickerRowsByBillingClass<TCatalog extends ClientModel>(
 }>;
 export function groupPickerRowsByBillingClass<TCatalog extends ClientModel>(
   rows: PickerModelRow<TCatalog>[],
+  options?: GroupPickerRowsOptions,
 ): Array<{
   billingClass: PickerBillingClass;
   label: string;
@@ -269,16 +392,47 @@ export function groupPickerRowsByBillingClass<TCatalog extends ClientModel>(
     rows: PickerModelRow<TCatalog>[];
   }> = [];
   for (const row of sorted) {
-    const existing = groups.find((group) => group.billingClass === row.billingClass);
+    const collapse = options?.collapseScopes !== false;
+    const billingClass = collapse ? displayGroupFor(row.billingClass) : row.billingClass;
+    const existing = groups.find((group) => group.billingClass === billingClass);
     if (existing) {
-      existing.rows.push(row);
+      const identity = collapse ? scopeFreeIdentity(row) : null;
+      const twin =
+        identity === null
+          ? -1
+          : existing.rows.findIndex((candidate) => scopeFreeIdentity(candidate) === identity);
+      if (twin < 0) {
+        existing.rows.push(row);
+      } else if (prefersTwin(row, existing.rows[twin]!, options?.selectedId)) {
+        existing.rows[twin] = row;
+      }
       continue;
     }
     groups.push({
-      billingClass: row.billingClass,
-      label: row.billingClassLabel,
+      billingClass,
+      label:
+        billingClass === row.billingClass ? row.billingClassLabel : billingClassLabel(billingClass),
       rows: [row],
     });
   }
+  const codexIndex = groups.findIndex((group) => group.billingClass === "codex_subscription");
+  const codex = groups[codexIndex];
+  const selectableOpenGeni = groups
+    .find((group) => group.billingClass === "opengeni_credits")
+    ?.rows.filter((row) => row.selectable);
+  // Presentation only: never change the catalog/default model ordering or selection.
+  const onlyFreeOpenGeni =
+    selectableOpenGeni !== undefined &&
+    selectableOpenGeni.length > 0 &&
+    selectableOpenGeni.every((row) => row.catalog.cost === "free");
+  if (
+    codex &&
+    codex.rows.some((row) => row.selectable) &&
+    (options?.codexOnly || onlyFreeOpenGeni)
+  ) {
+    groups.splice(codexIndex, 1);
+    groups.unshift(codex);
+  }
   return groups;
 }
+export { modelDisplayName, modelVendor } from "@opengeni/sdk/model-display";