@opengeni/react 0.36.0 → 0.37.0

package/src/components/session-chrome.tsx

@@ -32,6 +32,7 @@
  */
 import type { SessionGoal, SessionPendingInputPreview, SessionTurn } from "@opengeni/sdk";
 import {
+  AudioLinesIcon,
   ArrowDownIcon,
   ArrowUpIcon,
   BotIcon,
@@ -64,7 +65,7 @@ import { cn } from "../lib/cn";
 import { requestQueueDraftEdit } from "./queue-draft-policy";
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "./tooltip";
 
-export type SessionChromeSignalId = "incoming" | "queue" | "goal" | "agents";
+export type SessionChromeSignalId = "incoming" | "steering" | "queue" | "goal" | "agents";
 
 export type SessionChromeSignalTone = "neutral" | "accent" | "waiting" | "running";
 
@@ -105,6 +106,11 @@ type GoalPillState =
   | "invariant_broken"
   | "completed";
 
+type QueuedTurnPresentation = {
+  kind: "prompt" | "realtime_voice" | "realtime_voice_handoff";
+  text: string;
+};
+
 const GOAL_LABEL: Record<GoalPillState, string> = {
   pursuing: "Pursuing",
   scheduled: "Scheduled",
@@ -115,6 +121,28 @@ const GOAL_LABEL: Record<GoalPillState, string> = {
   completed: "Done",
 };
 
+function queuedTurnPresentation(turn: SessionTurn): QueuedTurnPresentation {
+  const realtimeDelegation = objectValue(turn.metadata.realtimeDelegation);
+  const inputTranscript = realtimeDelegation?.inputTranscript;
+  if (typeof inputTranscript === "string" && inputTranscript.trim()) {
+    return { kind: "realtime_voice", text: inputTranscript.trim() };
+  }
+  if (objectValue(turn.metadata.realtimeTailFlush)) {
+    return { kind: "realtime_voice_handoff", text: "Remaining voice context" };
+  }
+  return { kind: "prompt", text: turn.prompt };
+}
+
+function isSteeringTurn(turn: SessionTurn): boolean {
+  return turn.metadata.delivery === "steer";
+}
+
+function objectValue(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
 /** Select pill state from the goal's authoritative continuation projection. */
 export function sessionChromeGoalPillState(
   goalStatus: "active" | "paused" | "completed",
@@ -215,6 +243,34 @@ export function SessionChrome({
   const record = goal?.goal ?? null;
   const incoming = queue.pendingInputs;
   const turns = queue.queue;
+  const composerSteering = composer?.steering ?? null;
+  const { steering, queuedTurns } = useMemo(() => {
+    const pendingQueueSteer =
+      turns.find((turn) => queue.pendingByTurn[turn.id] === "steer") ?? null;
+    const durableQueueSteer =
+      !pendingQueueSteer && turns[0] && isSteeringTurn(turns[0]) ? turns[0] : null;
+    const currentSteering =
+      composerSteering?.phase === "submitting"
+        ? composerSteering
+        : pendingQueueSteer
+          ? {
+              phase: "submitting" as const,
+              text: queuedTurnPresentation(pendingQueueSteer).text,
+              turnId: pendingQueueSteer.id,
+            }
+          : durableQueueSteer
+            ? {
+                phase: "accepted" as const,
+                text: queuedTurnPresentation(durableQueueSteer).text,
+                turnId: durableQueueSteer.id,
+              }
+            : composerSteering;
+    const currentTurnId = currentSteering?.turnId ?? null;
+    return {
+      steering: currentSteering,
+      queuedTurns: currentTurnId ? turns.filter((turn) => turn.id !== currentTurnId) : turns,
+    };
+  }, [composerSteering, queue.pendingByTurn, turns]);
   const canMutateQueue = !readOnly && composer !== undefined;
 
   const liveGoal =
@@ -250,14 +306,44 @@ export function SessionChrome({
         icon: <InboxIcon className="size-3" />,
       });
     }
-    if (turns.length > 0) {
-      const detail = turns[0]?.prompt;
+    if (steering) {
+      rows.push({
+        id: "steering",
+        label: "Changing direction…",
+        detail: steering.text,
+        tone: "accent",
+        icon:
+          steering.phase === "submitting" ? (
+            <Loader2Icon className="size-3 animate-og-spin" />
+          ) : (
+            <ZapIcon className="size-3" />
+          ),
+      });
+    }
+    if (queuedTurns.length > 0) {
+      const presentations = queuedTurns.map(queuedTurnPresentation);
+      const first = presentations[0];
+      const allVoiceRequests = presentations.every(({ kind }) => kind === "realtime_voice");
+      const onlyVoiceHandoff =
+        presentations.length === 1 && first?.kind === "realtime_voice_handoff";
+      const voiceOnly = allVoiceRequests || onlyVoiceHandoff;
+      const detail = first?.text;
       rows.push({
         id: "queue",
-        label: `${turns.length} queued prompt${turns.length === 1 ? "" : "s"}`,
+        label: allVoiceRequests
+          ? queuedTurns.length === 1
+            ? "Voice request queued"
+            : `${queuedTurns.length} voice requests queued`
+          : onlyVoiceHandoff
+            ? "Voice handoff queued"
+            : `${queuedTurns.length} queued prompt${queuedTurns.length === 1 ? "" : "s"}`,
         ...(detail ? { detail } : {}),
         tone: "neutral",
-        icon: <ListOrderedIcon className="size-3" />,
+        icon: voiceOnly ? (
+          <AudioLinesIcon className="size-3" />
+        ) : (
+          <ListOrderedIcon className="size-3" />
+        ),
       });
     }
     if (record && goalState) {
@@ -292,7 +378,7 @@ export function SessionChrome({
       });
     }
     return rows;
-  }, [agentsSignal, elapsed, goalState, incoming, record, turns]);
+  }, [agentsSignal, elapsed, goalState, incoming, queuedTurns, record, steering]);
 
   const [activeUncontrolled, setActiveUncontrolled] = useState<SessionChromeSignalId | null>(
     defaultActive,
@@ -320,10 +406,10 @@ export function SessionChrome({
 
   useEffect(() => {
     if (active !== "queue" || !replaceDraftFor) return;
-    if (!turns.some((turn) => turn.id === replaceDraftFor)) {
+    if (!queuedTurns.some((turn) => turn.id === replaceDraftFor)) {
       setReplaceDraftFor(null);
     }
-  }, [active, replaceDraftFor, turns]);
+  }, [active, queuedTurns, replaceDraftFor]);
 
   useEffect(() => {
     const rail = railRef.current;
@@ -363,7 +449,7 @@ export function SessionChrome({
     const node = panelBodyRef.current;
     if (!node) return;
     setPanelHeight(node.offsetHeight);
-  }, [open, active, incoming, turns, record, goalState, agentsPanel, agentsSignal]);
+  }, [open, active, incoming, queuedTurns, record, goalState, agentsPanel, agentsSignal, steering]);
 
   useEffect(() => {
     if (!open) return;
@@ -385,9 +471,11 @@ export function SessionChrome({
   const panelBody =
     active === "incoming" ? (
       <IncomingPanel inputs={incoming} onDismiss={onDismissIncoming} />
+    ) : active === "steering" && steering ? (
+      <SteeringPanel phase={steering.phase} text={steering.text} />
     ) : active === "queue" ? (
       <QueuePanel
-        turns={turns}
+        turns={queuedTurns}
         readOnly={!canMutateQueue}
         mutationFor={queue.mutationFor}
         replaceDraftFor={replaceDraftFor}
@@ -661,6 +749,33 @@ function IncomingPanel({
   );
 }
 
+function SteeringPanel({ phase, text }: { phase: "submitting" | "accepted"; text: string }) {
+  return (
+    <div
+      className="flex items-start gap-2 rounded-og-sm px-1.5 py-1"
+      role="status"
+      aria-live="polite"
+      data-og-session-chrome-panel="steering"
+    >
+      <span className="mt-0.5 inline-flex size-5 shrink-0 items-center justify-center rounded-full bg-og-accent-soft text-og-accent">
+        {phase === "submitting" ? (
+          <Loader2Icon className="size-3 animate-og-spin" aria-hidden="true" />
+        ) : (
+          <ZapIcon className="size-3" aria-hidden="true" />
+        )}
+      </span>
+      <div className="min-w-0">
+        <p className="truncate text-og-xs font-medium leading-4 text-og-fg">{text}</p>
+        <p className="mt-0.5 text-[10px] leading-4 text-og-fg-muted">
+          {phase === "submitting"
+            ? "Sending your latest direction…"
+            : "Direction accepted. The agent will continue from it."}
+        </p>
+      </div>
+    </div>
+  );
+}
+
 function QueuePanel({
   turns,
   readOnly,
@@ -691,6 +806,8 @@ function QueuePanel({
       data-og-session-chrome-panel="queue"
     >
       {turns.map((turn, index) => {
+        const presentation = queuedTurnPresentation(turn);
+        const voice = presentation.kind !== "prompt";
         const pending = mutationFor(turn.id);
         const beforeUp = index > 0 ? (turns[index - 1]?.id ?? null) : null;
         const beforeDown = index < turns.length - 1 ? (turns[index + 2]?.id ?? null) : null;
@@ -703,11 +820,18 @@ function QueuePanel({
             className="group flex flex-col gap-1 rounded-og-sm px-1.5 py-1 transition-colors hover:bg-[var(--og-session-chrome-row-hover)]"
           >
             <div className="flex items-start gap-1.5">
-              <span className="mt-px shrink-0 font-og-mono text-[10px] leading-4 text-og-fg-subtle">
-                {index + 1}
-              </span>
+              {voice ? (
+                <AudioLinesIcon
+                  aria-hidden="true"
+                  className="mt-0.5 size-3 shrink-0 text-og-accent"
+                />
+              ) : (
+                <span className="mt-px shrink-0 font-og-mono text-[10px] leading-4 text-og-fg-subtle">
+                  {index + 1}
+                </span>
+              )}
               <p className="min-w-0 flex-1 truncate text-og-xs leading-4 text-og-fg">
-                {turn.prompt}
+                {presentation.text}
               </p>
               {showActions ? (
                 <div className="flex shrink-0 items-center gap-0.5 opacity-0 transition-opacity group-hover:opacity-100 focus-within:opacity-100 max-sm:opacity-100">

package/src/composer.ts

@@ -4,6 +4,19 @@
  * `import * as Composer from "@opengeni/react/composer"`.
  */
 export { OPEN_WORKSTREAM_CONTROL_EVENT } from "./workstream-control-event";
+export {
+  BillingClassMark,
+  ModelPolicyPicker,
+  ModelPolicyPickerMenu,
+  PickerAnimatedPage,
+  PickerBackHeader,
+  PickerNavRow,
+  defaultModelPolicyPickerMessages,
+} from "./components/model-policy-picker";
+export type {
+  ModelPolicyPickerMessages,
+  ModelPolicyPickerProps,
+} from "./components/model-policy-picker";
 export {
   Actions,
   AttachButton,

package/src/hooks/use-composer.ts

@@ -225,6 +225,8 @@ export type ComposerState = {
   send: (text?: string) => Promise<boolean>;
   /** Supersede current direction with the draft. */
   steer: (text?: string) => Promise<boolean>;
+  /** Optimistic-to-durable projection for a Steer that has not started yet. */
+  steering?: ComposerSteeringState | null | undefined;
   sending: boolean;
   canSend: boolean;
   /** Pause the session without deleting its prompt queue. */
@@ -250,6 +252,59 @@ export type ComposerState = {
   clearError: () => void;
 };
 
+export type ComposerSteeringState = {
+  phase: "submitting" | "accepted";
+  text: string;
+  clientEventId: string | null;
+  triggerEventId: string | null;
+  turnId: string | null;
+};
+
+const STEERING_SETTLEMENT_EVENT_TYPES = new Set([
+  "turn.started",
+  "turn.completed",
+  "turn.failed",
+  "turn.cancelled",
+  "turn.superseded",
+]);
+
+function isSteeringSettlementEvent(event: SessionEvent): boolean {
+  return STEERING_SETTLEMENT_EVENT_TYPES.has(event.type);
+}
+
+function steeringAcceptedEvent(
+  steering: ComposerSteeringState,
+  events: readonly SessionEvent[],
+): SessionEvent | undefined {
+  return events.find(
+    (event) =>
+      event.type === "user.message" &&
+      steering.clientEventId !== null &&
+      event.clientEventId === steering.clientEventId,
+  );
+}
+
+function steeringSettledByEvents(
+  steering: ComposerSteeringState,
+  events: readonly SessionEvent[],
+): boolean {
+  const acceptedEventId =
+    steering.triggerEventId ?? steeringAcceptedEvent(steering, events)?.id ?? null;
+  return events.some((event) => {
+    if (steering.turnId && event.turnId === steering.turnId && isSteeringSettlementEvent(event)) {
+      return true;
+    }
+    if (event.type !== "turn.started" || !acceptedEventId) return false;
+    const payload = event.payload;
+    return (
+      typeof payload === "object" &&
+      payload !== null &&
+      "triggerEventId" in payload &&
+      payload.triggerEventId === acceptedEventId
+    );
+  });
+}
+
 /**
  * Draft + send + Pause/Resume state for the chat composer — the only
  * human-to-agent input surface. The draft survives a failed send (nothing is
@@ -271,6 +326,17 @@ export function useComposer(
   // a parent may switch sessionId without remounting this public hook.
   const [stateTargetKey, setStateTargetKey] = useState(targetKey);
   const [sending, setSending] = useState(false);
+  const [steering, setSteering] = useState<ComposerSteeringState | null>(() =>
+    initialPendingOperation?.delivery === "steer"
+      ? {
+          phase: "submitting",
+          text: initialPendingOperation.input.text,
+          clientEventId: initialPendingOperation.input.clientEventId ?? null,
+          triggerEventId: null,
+          turnId: null,
+        }
+      : null,
+  );
   const [pausing, setPausing] = useState(false);
   const [resuming, setResuming] = useState(false);
   const [error, setError] = useState<Error | null>(null);
@@ -282,6 +348,8 @@ export function useComposer(
     () => initialShadow?.resources ?? [],
   );
   const pendingOperationRef = useRef<PendingComposerOperation | null>(initialPendingOperation);
+  const steeringSettlementEventsRef = useRef<SessionEvent[]>([]);
+  const steeringRef = useRef(steering);
   const pendingClientEventId = useRef<string | null>(
     initialPendingOperation?.input.clientEventId ?? null,
   );
@@ -303,6 +371,9 @@ export function useComposer(
   useLayoutEffect(() => {
     onDraftAppliedRef.current = onDraftApplied;
   }, [onDraftApplied]);
+  useLayoutEffect(() => {
+    steeringRef.current = steering;
+  }, [steering]);
   // 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);
@@ -320,6 +391,7 @@ export function useComposer(
     targetGeneration.current += 1;
     draftReadGeneration.current += 1;
     pendingOperationRef.current = restorePendingComposerOperation(pendingOperationKey);
+    steeringSettlementEventsRef.current = [];
     pendingClientEventId.current = pendingOperationRef.current?.input.clientEventId ?? null;
     const shadow = pendingOperationRef.current?.newerShadow;
     localEditRevision.current = shadow ? 1 : 0;
@@ -333,6 +405,17 @@ export function useComposer(
     setStateTargetKey(targetKey);
     setValue(shadow?.text ?? "");
     setSending(false);
+    setSteering(
+      pendingOperationRef.current?.delivery === "steer"
+        ? {
+            phase: "submitting",
+            text: pendingOperationRef.current.input.text,
+            clientEventId: pendingOperationRef.current.input.clientEventId ?? null,
+            triggerEventId: null,
+            turnId: null,
+          }
+        : null,
+    );
     setPausing(false);
     setResuming(false);
     setError(null);
@@ -503,18 +586,76 @@ export function useComposer(
     if (!sessionId || !durableDrafts) return;
     return registerSessionReconciler(sessionId, "composer", async () => await loadDraft(false));
   }, [durableDrafts, loadDraft, registerSessionReconciler, sessionId]);
+  const reconcileSteering = useCallback(async (): Promise<void> => {
+    if (!sessionId || !steeringRef.current) return;
+    const ownedTargetKey = targetKey;
+    let events: SessionEvent[];
+    try {
+      events = await client.listEvents(workspaceId, sessionId, {
+        includeTypes: [
+          "user.message",
+          "turn.started",
+          "turn.completed",
+          "turn.failed",
+          "turn.cancelled",
+          "turn.superseded",
+        ],
+        limit: 250,
+        payloadMode: "full",
+      });
+    } catch {
+      // Best effort: the live stream still settles steering when its event arrives.
+      return;
+    }
+    if (targetKeyRef.current !== ownedTargetKey) return;
+    setSteering((current) => {
+      if (!current) return current;
+      if (steeringSettledByEvents(current, events)) {
+        steeringSettlementEventsRef.current = [];
+        return null;
+      }
+      const accepted = steeringAcceptedEvent(current, events);
+      if (!accepted || current.triggerEventId) return current;
+      return {
+        ...current,
+        phase: "accepted",
+        triggerEventId: accepted.id,
+      };
+    });
+  }, [client, sessionId, targetKey, workspaceId]);
   useSessionEventTrigger(
     client,
     workspaceId,
     sessionId,
-    isComposerDraftEvent,
-    () => void loadDraft(false),
+    (event) => isComposerDraftEvent(event) || isSteeringSettlementEvent(event),
+    (event) => {
+      if (isComposerDraftEvent(event)) void loadDraft(false);
+      if (!isSteeringSettlementEvent(event)) return;
+      steeringSettlementEventsRef.current = [
+        ...steeringSettlementEventsRef.current.slice(-15),
+        event,
+      ];
+      setSteering((current) => {
+        if (!current || !steeringSettledByEvents(current, [event])) return current;
+        steeringSettlementEventsRef.current = [];
+        return null;
+      });
+    },
     {
-      enabled: Boolean(sessionId) && durableDrafts,
+      enabled: Boolean(sessionId) && (durableDrafts || steering !== null),
       ...(options.events !== undefined ? { events: options.events } : {}),
     },
+    reconcileSteering,
   );
 
+  useEffect(() => {
+    if (!steering) return;
+    const observed = [...(options.events ?? []), ...steeringSettlementEventsRef.current];
+    if (!steeringSettledByEvents(steering, observed)) return;
+    steeringSettlementEventsRef.current = [];
+    setSteering(null);
+  }, [options.events, steering]);
+
   const currentDraftPayload = useCallback((): SaveComposerDraftRequest | null => {
     if (!durableDrafts || targetKeyRef.current !== targetKey) return null;
     const base = draftRef.current;
@@ -667,6 +808,8 @@ export function useComposer(
         forgetPendingComposerOperation(operationKey);
       };
 
+      let keepSteering = pending?.delivery === "steer";
+
       const settleAccepted = (operation: PendingComposerOperation): void => {
         clearPending();
         const draftWasUnchanged = valueRef.current === operation.draftAtSend;
@@ -699,30 +842,40 @@ export function useComposer(
         onSent?.(operation.input.text, operation.input);
       };
 
-      const deliver = async (operation: PendingComposerOperation): Promise<void> => {
+      const deliver = async (operation: PendingComposerOperation) => {
         if (operation.delivery === "steer") {
-          await client.steerMessage(workspaceId, sessionId, operation.input);
-        } else {
-          await client.sendMessage(workspaceId, sessionId, operation.input);
+          return await client.steerMessage(workspaceId, sessionId, operation.input);
         }
+        await client.sendMessage(workspaceId, sessionId, operation.input);
+        return null;
       };
 
+      if (delivery === "steer") {
+        setSteering({
+          phase: "submitting",
+          text: rawText,
+          clientEventId: pending?.input.clientEventId ?? pendingClientEventId.current,
+          triggerEventId: null,
+          turnId: null,
+        });
+      }
       setSending(true);
       setError(null);
       try {
         if (pending) {
-          let accepted = false;
+          let acceptedEvent: SessionEvent | null = null;
           try {
             const events = await client.listEvents(workspaceId, sessionId, {
               includeTypes: ["user.message"],
               limit: 100,
               payloadMode: "none",
             });
-            accepted = events.some(
-              (event) =>
-                event.type === "user.message" &&
-                event.clientEventId === pending.input.clientEventId,
-            );
+            acceptedEvent =
+              events.find(
+                (event) =>
+                  event.type === "user.message" &&
+                  event.clientEventId === pending.input.clientEventId,
+              ) ?? null;
           } catch (cause) {
             if (
               targetKeyRef.current === ownedTargetKey &&
@@ -738,7 +891,17 @@ export function useComposer(
           ) {
             return false;
           }
-          if (accepted) {
+          if (acceptedEvent) {
+            if (pending.delivery === "steer") {
+              keepSteering = true;
+              setSteering({
+                phase: "accepted",
+                text: pending.input.text,
+                clientEventId: pending.input.clientEventId ?? null,
+                triggerEventId: acceptedEvent.id,
+                turnId: null,
+              });
+            }
             settleAccepted(pending);
             return true;
           }
@@ -751,8 +914,19 @@ export function useComposer(
             return false;
           }
           try {
-            await deliver(pending);
+            const result = await deliver(pending);
+            if (pending.delivery === "steer" && result) {
+              keepSteering = true;
+              setSteering({
+                phase: "accepted",
+                text: pending.input.text,
+                clientEventId: pending.input.clientEventId ?? null,
+                triggerEventId: result.accepted.id,
+                turnId: result.turn.id,
+              });
+            }
           } catch (cause) {
+            if (pending.delivery === "steer") keepSteering = true;
             if (
               targetKeyRef.current === ownedTargetKey &&
               targetGeneration.current === ownedGeneration
@@ -812,11 +986,32 @@ export function useComposer(
         };
         pendingOperationRef.current = operation;
         rememberPendingComposerOperation(operationKey, operation);
+        if (delivery === "steer") {
+          setSteering({
+            phase: "submitting",
+            text: sendText,
+            clientEventId: input.clientEventId ?? null,
+            triggerEventId: null,
+            turnId: null,
+          });
+        }
         try {
-          await deliver(operation);
+          const result = await deliver(operation);
+          if (delivery === "steer" && result) {
+            keepSteering = true;
+            setSteering({
+              phase: "accepted",
+              text: sendText,
+              clientEventId: input.clientEventId ?? null,
+              triggerEventId: result.accepted.id,
+              turnId: result.turn.id,
+            });
+          }
         } catch (cause) {
           if (!isOutcomeUnknownError(cause)) {
             clearPending();
+          } else if (delivery === "steer") {
+            keepSteering = true;
           }
           if (
             targetKeyRef.current === ownedTargetKey &&
@@ -840,6 +1035,7 @@ export function useComposer(
           targetGeneration.current === ownedGeneration
         ) {
           setSending(false);
+          if (delivery === "steer" && !keepSteering) setSteering(null);
         }
       }
     },
@@ -1095,6 +1291,7 @@ export function useComposer(
     hasDraftContent,
     send,
     steer,
+    steering: identityMatches ? steering : null,
     sending: identityMatches ? sending : false,
     canSend:
       identityMatches &&

package/src/index.ts

@@ -393,6 +393,19 @@ export { defaultChatComposerMessages } from "./components/composer";
 export type { ChatComposerMessages } from "./components/composer";
 export { ModelPicker } from "./components/model-picker";
 export type { ModelPickerProps } from "./components/model-picker";
+export {
+  BillingClassMark,
+  ModelPolicyPicker,
+  ModelPolicyPickerMenu,
+  PickerAnimatedPage,
+  PickerBackHeader,
+  PickerNavRow,
+  defaultModelPolicyPickerMessages,
+} from "./components/model-policy-picker";
+export type {
+  ModelPolicyPickerMessages,
+  ModelPolicyPickerProps,
+} from "./components/model-policy-picker";
 export {
   advancedSourceSummary,
   availabilityReasonLabel,
@@ -404,7 +417,9 @@ export {
   findPickerRow,
   groupPickerRowsByBillingClass,
   labelLatencyMode,
+  labelReasoningEffort,
   payerSummaryForModel,
+  projectClientModelRows,
   projectPickerRows,
   runnableLatencyModesForModel,
   sortPickerRows,