@opengeni/react 0.57.0 → 2.2.0-canary.0

package/src/realtime/realtime-control.tsx

@@ -6,6 +6,7 @@ import {
   type SessionRealtimeController,
   type SessionRealtimeControllerSnapshot,
   type CreateSessionRealtimeControllerOptions,
+  type SessionRealtimeLifecycleProjection,
   type SessionRealtimeModel,
   type WorkspaceRealtimeModelCatalogItem,
 } from "@opengeni/sdk/realtime";
@@ -98,9 +99,108 @@ const REALTIME_PROVIDER_META: Record<
   "Your Gateway": { billingClass: "byok", hint: "Billed to your AI Gateway" },
 };
 const REALTIME_MODEL_STORAGE_PREFIX = "opengeni:realtime-model";
+const REALTIME_MODEL_CATALOG_CACHE_TTL_MS = 60_000;
+const REALTIME_MODEL_CATALOG_CACHE_MAX_WORKSPACES = 64;
 
 type RealtimeControllerClient = EmbeddedRealtimeSessionClientLike & SessionRealtimeClientLike;
 
+type RealtimeModelCatalogCacheEntry =
+  | { state: "loading"; promise: Promise<RealtimeModelOption[]> }
+  | { state: "ready"; models: RealtimeModelOption[]; expiresAt: number };
+
+// Scope advisory availability to the exact client object and workspace. The
+// server still authorizes every realtime operation; changing principals should
+// replace the client just as it does for the rest of the SDK state.
+const realtimeModelCatalogCache = new WeakMap<
+  RealtimeControllerClient,
+  Map<string, RealtimeModelCatalogCacheEntry>
+>();
+
+function realtimeModelFallback(codexConnected: boolean): RealtimeModelOption[] {
+  return [
+    {
+      ...CODEX_LIVE_MODEL,
+      available: codexConnected,
+      unavailableReason: codexConnected ? null : CODEX_LIVE_MODEL.unavailableReason,
+    },
+  ];
+}
+
+function realtimeModelCatalogCacheFor(
+  client: RealtimeControllerClient,
+): Map<string, RealtimeModelCatalogCacheEntry> {
+  const existing = realtimeModelCatalogCache.get(client);
+  if (existing) return existing;
+  const created = new Map<string, RealtimeModelCatalogCacheEntry>();
+  realtimeModelCatalogCache.set(client, created);
+  return created;
+}
+
+function readCachedRealtimeModelCatalog(
+  client: RealtimeControllerClient,
+  workspaceId: string,
+  now = Date.now(),
+): RealtimeModelOption[] | null {
+  const cache = realtimeModelCatalogCache.get(client);
+  const entry = cache?.get(workspaceId);
+  if (!entry || entry.state === "loading") return null;
+  if (entry.expiresAt > now) return entry.models;
+  cache?.delete(workspaceId);
+  return null;
+}
+
+function pruneRealtimeModelCatalogCache(
+  cache: Map<string, RealtimeModelCatalogCacheEntry>,
+  now: number,
+): void {
+  for (const [workspaceId, entry] of cache) {
+    if (entry.state === "ready" && entry.expiresAt <= now) cache.delete(workspaceId);
+  }
+  while (cache.size >= REALTIME_MODEL_CATALOG_CACHE_MAX_WORKSPACES) {
+    const oldestWorkspaceId = cache.keys().next().value;
+    if (oldestWorkspaceId === undefined) return;
+    cache.delete(oldestWorkspaceId);
+  }
+}
+
+function loadRealtimeModelCatalog(
+  client: RealtimeControllerClient,
+  workspaceId: string,
+): Promise<RealtimeModelOption[]> | null {
+  const load = client.getWorkspaceRealtimeModelCatalog;
+  if (!load) return null;
+  const now = Date.now();
+  const cache = realtimeModelCatalogCacheFor(client);
+  const entry = cache.get(workspaceId);
+  if (entry?.state === "loading") return entry.promise;
+  if (entry?.state === "ready" && entry.expiresAt > now) return Promise.resolve(entry.models);
+  if (entry) cache.delete(workspaceId);
+  pruneRealtimeModelCatalogCache(cache, now);
+
+  const promise = load
+    .call(client, workspaceId)
+    .then((response) => response.models.map(toRealtimeModelOption))
+    .then((models) => {
+      const current = cache.get(workspaceId);
+      if (current?.state === "loading" && current.promise === promise) {
+        cache.delete(workspaceId);
+        cache.set(workspaceId, {
+          state: "ready",
+          models,
+          expiresAt: Date.now() + REALTIME_MODEL_CATALOG_CACHE_TTL_MS,
+        });
+      }
+      return models;
+    })
+    .catch((error: unknown) => {
+      const current = cache.get(workspaceId);
+      if (current?.state === "loading" && current.promise === promise) cache.delete(workspaceId);
+      throw error;
+    });
+  cache.set(workspaceId, { state: "loading", promise });
+  return promise;
+}
+
 export type SessionRealtimeControllerFactory = (
   options: CreateSessionRealtimeControllerOptions,
 ) => SessionRealtimeController;
@@ -138,6 +238,8 @@ export function useSessionRealtime(options: {
   model?: SessionRealtimeModel | undefined;
   modelAvailable?: boolean | undefined;
   modelUnavailableReason?: string | null | undefined;
+  /** Model-visible application context captured with each durable realtime message. */
+  getModelContext?: (() => string | undefined) | undefined;
   /** Deterministic browser-test/demo seam. Production hosts should use the SDK default. */
   controllerFactory?: SessionRealtimeControllerFactory | undefined;
 }) {
@@ -149,6 +251,8 @@ export function useSessionRealtime(options: {
   const audioRef = useRef<HTMLAudioElement>(null);
   const controllerRef = useRef<SessionRealtimeController | null>(null);
   const controllerModelRef = useRef<SessionRealtimeModel | null>(null);
+  const modelContextProviderRef = useRef(options.getModelContext);
+  modelContextProviderRef.current = options.getModelContext;
   const [snapshot, setSnapshot] = useState<SessionRealtimeControllerSnapshot>(() => ({
     status: hasStoredSessionRealtimeOwnerProof({
       workspaceId,
@@ -177,7 +281,7 @@ export function useSessionRealtime(options: {
   const eventsReadyRef = useRef(options.eventsReady);
   lifecycleRef.current = lifecycle;
   eventsReadyRef.current = options.eventsReady;
-  const lifecycleActive = lifecycle?.state === "active";
+  const lifecycleActive = sessionRealtimeLifecycleIsActive(lifecycle);
 
   useEffect(() => {
     let disposed = false;
@@ -193,6 +297,7 @@ export function useSessionRealtime(options: {
           sessionId: options.sessionId,
           ...(audioRef.current ? { remoteAudio: audioRef.current } : {}),
           model,
+          getModelContext: () => modelContextProviderRef.current?.(),
         });
         controllerRef.current = controller;
         controllerModelRef.current = model;
@@ -297,6 +402,14 @@ export function useSessionRealtime(options: {
   };
 }
 
+function sessionRealtimeLifecycleIsActive(
+  lifecycle: SessionRealtimeLifecycleProjection | null,
+): boolean {
+  if (lifecycle?.state !== "active") return false;
+  const leaseExpiresAt = Date.parse(lifecycle.leaseExpiresAt);
+  return !Number.isFinite(leaseExpiresAt) || leaseExpiresAt > Date.now();
+}
+
 export function SessionRealtimeControl(props: {
   client?: RealtimeControllerClient | undefined;
   workspaceId?: string | undefined;
@@ -306,6 +419,8 @@ export function SessionRealtimeControl(props: {
   events: SessionEvent[];
   eventsReady: boolean;
   codexConnected: boolean;
+  /** Model-visible application context captured with each durable realtime message. */
+  getModelContext?: (() => string | undefined) | undefined;
   realtimeAutostartModel?: SessionRealtimeModel | undefined;
   onRealtimeAutostartConsumed?: (() => void) | undefined;
   /** Host hides dictate (and can choreograph layout) while realtime voice is live. */
@@ -317,15 +432,18 @@ export function SessionRealtimeControl(props: {
    * `none` never attaches a model menu to the bar button.
    */
   modelMenu?: "split" | "split-desktop" | "none" | undefined;
+  /** Explicitly expose low-level controller diagnostics; disabled by default. */
+  showDiagnostics?: boolean | undefined;
   /** Deterministic browser-test/demo seam. Production hosts should use the SDK default. */
   controllerFactory?: SessionRealtimeControllerFactory | undefined;
 }) {
   const lifecycle = useMemo(() => projectSessionRealtimeLifecycle(props.events), [props.events]);
+  const lifecycleActive = sessionRealtimeLifecycleIsActive(lifecycle);
   const selection = useRealtimeModelSelection({
     client: props.client,
     workspaceId: props.workspaceId,
     codexConnected: props.codexConnected,
-    activeModel: lifecycle?.state === "active" ? lifecycle.model : null,
+    activeModel: lifecycleActive && lifecycle?.state === "active" ? lifecycle.model : null,
   });
   const selectedModel = selection.selectedModel;
   const realtime = useSessionRealtime({
@@ -349,7 +467,7 @@ export function SessionRealtimeControl(props: {
 
   useEffect(() => {
     const pending = autostartModelRef.current;
-    if (!pending || autostartStartedRef.current || lifecycle?.state === "active") return;
+    if (!pending || autostartStartedRef.current || lifecycleActive) return;
     const available = models.some((model) => model.id === pending && model.available);
     if (!available) return;
     if (selectedRealtimeModel.id !== pending) {
@@ -368,7 +486,7 @@ export function SessionRealtimeControl(props: {
       });
   }, [
     canStart,
-    lifecycle?.state,
+    lifecycleActive,
     models,
     props.sessionId,
     props.workspaceId,
@@ -386,6 +504,7 @@ export function SessionRealtimeControl(props: {
       modelAvailable={selectedModel.available}
       menuSide="top"
       modelMenu={props.modelMenu ?? "split"}
+      showDiagnostics={props.showDiagnostics}
       audioRef={realtime.audioRef}
       selectedModel={selectedModel}
       models={selection.models}
@@ -411,31 +530,52 @@ export function useRealtimeModelSelection(options: {
     workspaceId: options.workspaceId,
   });
   const activeModel = options.activeModel;
-  const [catalog, setCatalog] = useState<RealtimeModelOption[]>(() => [
-    {
-      ...CODEX_LIVE_MODEL,
-      available: options.codexConnected,
-      unavailableReason: options.codexConnected ? null : CODEX_LIVE_MODEL.unavailableReason,
-    },
-  ]);
-  const [selectedModelId, setSelectedModelId] = useState<SessionRealtimeModel>(
-    () => readRealtimeModelPreference(workspaceId) ?? CODEX_LIVE_MODEL.id,
+  const initialCachedCatalog = readCachedRealtimeModelCatalog(client, workspaceId);
+  const [catalog, setCatalog] = useState<RealtimeModelOption[]>(
+    () => initialCachedCatalog ?? realtimeModelFallback(options.codexConnected),
   );
+  const catalogScopeRef = useRef({
+    client,
+    workspaceId,
+    source: initialCachedCatalog ? ("cache" as const) : ("fallback" as const),
+  });
+  const [selectedModelId, setSelectedModelId] = useState<SessionRealtimeModel>(() => {
+    const preferred = readRealtimeModelPreference(workspaceId) ?? CODEX_LIVE_MODEL.id;
+    if (!initialCachedCatalog) return preferred;
+    if (initialCachedCatalog.some((model) => model.id === preferred && model.available)) {
+      return preferred;
+    }
+    return initialCachedCatalog.find((model) => model.available)?.id ?? CODEX_LIVE_MODEL.id;
+  });
 
   useEffect(() => {
     let disposed = false;
-    const load = client.getWorkspaceRealtimeModelCatalog;
-    if (!load) return;
-    void load
-      .call(client, workspaceId)
-      .then((response) => {
+    const applyCatalog = (models: RealtimeModelOption[]) => {
+      catalogScopeRef.current = { client, workspaceId, source: "cache" };
+      setCatalog(models);
+      setSelectedModelId((current) => {
+        if (models.some((model) => model.id === current && model.available)) return current;
+        return models.find((model) => model.available)?.id ?? CODEX_LIVE_MODEL.id;
+      });
+    };
+    const cached = readCachedRealtimeModelCatalog(client, workspaceId);
+    if (cached) {
+      const scope = catalogScopeRef.current;
+      if (
+        scope.client !== client ||
+        scope.workspaceId !== workspaceId ||
+        scope.source !== "cache"
+      ) {
+        applyCatalog(cached);
+      }
+      return;
+    }
+    const loading = loadRealtimeModelCatalog(client, workspaceId);
+    if (!loading) return;
+    void loading
+      .then((models) => {
         if (disposed) return;
-        const models = response.models.map(toRealtimeModelOption);
-        setCatalog(models);
-        setSelectedModelId((current) => {
-          if (models.some((model) => model.id === current && model.available)) return current;
-          return models.find((model) => model.available)?.id ?? CODEX_LIVE_MODEL.id;
-        });
+        applyCatalog(models);
       })
       .catch(() => undefined);
     return () => {
@@ -482,7 +622,7 @@ const IDLE_REALTIME_SNAPSHOT: SessionRealtimeControllerSnapshot = {
   error: null,
 };
 
-export function NewSessionRealtimeControl(props: {
+type NewSessionRealtimeControlProps = {
   client?: RealtimeControllerClient | undefined;
   workspaceId?: string | undefined;
   codexConnected: boolean;
@@ -500,20 +640,43 @@ export function NewSessionRealtimeControl(props: {
    * `none` never attaches a model menu to the bar button.
    */
   modelMenu?: "split" | "split-desktop" | "none" | undefined;
-}) {
-  const internalSelection = useRealtimeModelSelection({
+};
+
+type NewSessionRealtimeSelection = {
+  models: readonly RealtimeModelOption[];
+  selectedModel: RealtimeModelOption;
+  selectModel: (modelId: string) => void;
+};
+
+export function NewSessionRealtimeControl(props: NewSessionRealtimeControlProps) {
+  if (props.models && props.selectedModel && props.onSelectModel) {
+    return (
+      <NewSessionRealtimeControlView
+        {...props}
+        selection={{
+          models: props.models,
+          selectedModel: props.selectedModel,
+          selectModel: props.onSelectModel,
+        }}
+      />
+    );
+  }
+  return <NewSessionRealtimeControlWithInternalSelection {...props} />;
+}
+
+function NewSessionRealtimeControlWithInternalSelection(props: NewSessionRealtimeControlProps) {
+  const selection = useRealtimeModelSelection({
     client: props.client,
     workspaceId: props.workspaceId,
     codexConnected: props.codexConnected,
   });
-  const selection =
-    props.models && props.selectedModel && props.onSelectModel
-      ? {
-          models: props.models,
-          selectedModel: props.selectedModel,
-          selectModel: props.onSelectModel,
-        }
-      : internalSelection;
+  return <NewSessionRealtimeControlView {...props} selection={selection} />;
+}
+
+function NewSessionRealtimeControlView(
+  props: NewSessionRealtimeControlProps & { selection: NewSessionRealtimeSelection },
+) {
+  const selection = props.selection;
   const audioRef = useRef<HTMLAudioElement>(null);
   const [starting, setStarting] = useState(false);
   const [error, setError] = useState<string | null>(null);
@@ -582,7 +745,7 @@ export function RealtimeVoiceControl(props: {
    * `none` = start button only.
    */
   modelMenu?: "split" | "split-desktop" | "none" | undefined;
-  showDiagnostics?: boolean;
+  showDiagnostics?: boolean | undefined;
   /** Extra classes on the in-bar mute cluster (e.g. `max-sm:hidden` when mutes live in “+”). */
   muteControlsClassName?: string | undefined;
   audioRef: RefObject<HTMLAudioElement | null>;
@@ -636,7 +799,7 @@ export function RealtimeVoiceControl(props: {
       : modeOwned
         ? props.onStop
         : props.onStart;
-  const diagnosticsVisible = props.showDiagnostics ?? import.meta.env.DEV;
+  const diagnosticsVisible = props.showDiagnostics ?? false;
   const modelMenu = props.modelMenu ?? "split";
   const showAttachedModelMenu = modelMenu === "split" || modelMenu === "split-desktop";
   const desktopOnlyModelMenu = modelMenu === "split-desktop";

package/src/session-context.ts

@@ -316,6 +316,7 @@ export function useEmbeddedSession(
       "streamEvents",
       "getComposerDraft",
       "saveComposerDraft",
+      "submitComposerDraft",
       "sendMessage",
       "steerMessage",
       "getQueue",

package/src/session-ui.ts

@@ -24,7 +24,12 @@ export type {
 } from "./timeline/turn-summary";
 export { QueueSurface } from "./components/queue-surface";
 export type { QueueSurfaceProps } from "./components/queue-surface";
-export { SessionChrome, sessionChromeGoalPillState } from "./components/session-chrome";
+export {
+  SessionChrome,
+  sessionChromeGoalPillExplanation,
+  sessionChromeGoalPillLabel,
+  sessionChromeGoalPillState,
+} from "./components/session-chrome";
 export type {
   SessionChromeAgentsSignal,
   SessionChromeProps,

package/src/session.ts

@@ -38,7 +38,13 @@ export {
   shouldSubmitOnKey,
   FILE_ONLY_MESSAGE_TEXT,
 } from "./hooks/use-composer";
-export type { ComposerSendExtras, ComposerState, UseComposerOptions } from "./hooks/use-composer";
+export type {
+  ComposerControllerState,
+  ComposerPolicy,
+  ComposerSendExtras,
+  ComposerState,
+  UseComposerOptions,
+} from "./hooks/use-composer";
 export { useFileAttachments } from "./hooks/use-file-attachments";
 export type {
   FileAttachment,
@@ -96,6 +102,8 @@ export type {
   AgentMessageItem,
   AuthNeededItem,
   GoalItem,
+  HumanInputAnswerSummary,
+  HumanInputItem,
   MachineInputBatchItem,
   MachineInputMember,
   MemoryItem,

package/src/timeline/activity-rail.tsx

@@ -1,10 +1,4 @@
-import {
-  ArrowRightIcon,
-  BotIcon,
-  BrainCircuitIcon,
-  BrainIcon,
-  SquareTerminalIcon,
-} from "lucide-react";
+import { ArrowRightIcon, BotIcon, BrainCircuitIcon } from "lucide-react";
 import { lazy, Suspense, useLayoutEffect, useRef } from "react";
 import { jsx as rowJsx, jsxs as rowJsxs } from "react/jsx-runtime";
 import { Markdown } from "../components/markdown";
@@ -16,9 +10,10 @@ import type { RetainedArtifactLoader, RetainedScreenshotLoader, ToolRegistry } f
 import { useSeenActivityIds } from "./seen-activity-ids";
 import { BodyNote, PayloadBlock, ActivityDisclosure, ToolCallTruncationProvider } from "./shared";
 import { toolDisplayName } from "./tool-display-name";
-import type { ActivityItem, MemoryItem, ReasoningItem, SandboxItem, WorkerItem } from "./types";
+import type { ActivityItem, MemoryItem, WorkerItem } from "./types";
 
 const LazyFleetDecisionRow = lazy(() => import("./fleet-decision-row"));
+const LazyPlatformActivityRow = lazy(() => import("./platform-activity-row"));
 
 /* ----------------------------------------------------------------------------
    Activity rail
@@ -157,7 +152,23 @@ function renderActivity(
 ) {
   switch (item.kind) {
     case "reasoning":
-      return <ReasoningRow item={item} />;
+    case "sandbox":
+    case "startup-phase":
+      return (
+        <Suspense fallback={null}>
+          <LazyPlatformActivityRow
+            item={item}
+            d={ActivityDisclosure}
+            p={PayloadBlock}
+            t={toolDisplayName}
+            b={BotIcon}
+            m={Markdown}
+            r={truncate}
+            j={rowJsx}
+            s={rowJsxs}
+          />
+        </Suspense>
+      );
     case "tool-call": {
       const Renderer = toolRegistry.resolve(item);
       return (
@@ -172,8 +183,6 @@ function renderActivity(
     }
     case "worker":
       return <WorkerRow item={item} onOpenSession={onOpenSession} />;
-    case "sandbox":
-      return <SandboxRow item={item} />;
     case "memory":
       return <MemoryRow item={item} onMemoryClick={onMemoryClick} />;
     case "fleet-decision":
@@ -193,32 +202,6 @@ function renderActivity(
   }
 }
 
-function ReasoningRow({ item }: { item: ReasoningItem }) {
-  // Reasoning recedes: a dimmer, lighter-weight title so action rows lead and
-  // thought rows sit a half-step back in the hierarchy. Body uses the same
-  // GFM markdown path as agent messages — Codex reasoning often carries
-  // headings/lists/bold that were previously shown as raw plaintext.
-  return (
-    <ActivityDisclosure
-      icon={<BrainIcon className="size-3.5" />}
-      iconTone="muted"
-      title={
-        item.streaming ? (
-          "Thinking"
-        ) : (
-          <span className="font-normal italic text-og-fg-subtle">Thought</span>
-        )
-      }
-      running={item.streaming}
-      preview={truncate(item.text, 110)}
-    >
-      <div className="text-og-base leading-6 text-og-fg-muted [&_strong]:text-og-fg-muted">
-        <Markdown streaming={item.streaming}>{item.text}</Markdown>
-      </div>
-    </ActivityDisclosure>
-  );
-}
-
 /**
  * Human labels for the memory kinds, translated at the SDK boundary so a raw
  * enum slug never renders as UI. Kept local to the library (the app has its own
@@ -317,44 +300,6 @@ function MemoryRow({
   );
 }
 
-/**
- * A human title for a sandbox operation row. Named platform operations (the lazy
- * `sandbox.provision` first-establish that now runs mid-turn) read as calm,
- * status-aware English instead of a raw op id — the box coming up should look
- * like "Starting sandbox", never an unexplained long-running command. Unnamed /
- * unknown ops fall back to the generic id-to-words {@link toolDisplayName}.
- */
-function sandboxRowTitle(item: SandboxItem): string {
-  if (item.name === "sandbox.provision") {
-    if (item.status === "failed") return "Sandbox didn’t start";
-    if (item.status === "running") return "Starting sandbox";
-    if (item.origin === "resumed") return "Sandbox reattached";
-    if (item.origin === "restored") return "Sandbox restored";
-    if (item.origin === "created") return "Sandbox created";
-    return "Sandbox ready";
-  }
-  return toolDisplayName(item.name);
-}
-
-function SandboxRow({ item }: { item: SandboxItem }) {
-  return (
-    <ActivityDisclosure
-      icon={<SquareTerminalIcon className="size-3.5" />}
-      iconTone={
-        item.status === "failed" ? "failed" : item.status === "running" ? "running" : "muted"
-      }
-      title={sandboxRowTitle(item)}
-      running={item.status === "running"}
-      failed={item.status === "failed"}
-      cancelled={item.status === "cancelled"}
-      preview={item.command ?? undefined}
-    >
-      {item.command ? <PayloadBlock label="Command" value={item.command} /> : null}
-      {item.output ? <PayloadBlock label="Output" value={item.output} /> : null}
-    </ActivityDisclosure>
-  );
-}
-
 /** Spawned/messaged worker sessions get a first-class card, not a tool row. */
 function WorkerRow({
   item,

package/src/timeline/index.ts

@@ -36,12 +36,16 @@ export type {
   FleetDecisionItem,
   FleetDecisionScoreItem,
   GoalItem,
+  HumanInputAnswerSummary,
+  HumanInputItem,
   MachineInputBatchItem,
   MachineInputMember,
   MemoryItem,
   NoticeItem,
   ReasoningItem,
   SandboxItem,
+  StartupPhase,
+  StartupPhaseItem,
   SessionStatusItem,
   TimelineGroup,
   TimelineItem,