@opengeni/react 0.48.0 → 0.57.0

package/src/components/queue-surface-implementation.tsx

@@ -16,7 +16,7 @@ import {
   verticalListSortingStrategy,
 } from "@dnd-kit/sortable";
 import { CSS } from "@dnd-kit/utilities";
-import type { SessionPendingInputPreview, SessionTurn } from "@opengeni/sdk";
+import type { SessionPendingInputPreview, SessionTurn, TimelineAnnotation } from "@opengeni/sdk";
 import {
   ArrowDownToLineIcon,
   ArrowUpToLineIcon,
@@ -46,6 +46,7 @@ import {
 } from "../lib/use-portal-token-style";
 import { requestQueueDraftEdit } from "./queue-draft-policy";
 import { QueueErrorAlert, QueueStoppingStatus } from "./queue-surface-state";
+import { TimelineAnnotationsChip } from "./timeline-annotations";
 
 /** The sole pending-input surface: compact above Goal, Agents, and composer. */
 type QueueSurfaceCommonProps = {
@@ -99,14 +100,15 @@ export function QueueSurface({
     (input) => !attachedInputIds.includes(input.id),
   );
   const canEditInComposer = queueComposerCheckoutEnabled(composer, readOnly);
-  const collapsedPreview = useMemo(
-    () =>
-      queuePromptPreview(
-        queue.queue[0]?.prompt ?? queue.pendingInputs[0]?.summary ?? "",
-        QUEUE_COLLAPSED_PREVIEW_CHARACTERS,
-      ),
-    [queue.pendingInputs, queue.queue],
-  );
+  const collapsedPreview = useMemo(() => {
+    const firstTurn = queue.queue[0];
+    return firstTurn
+      ? queueTurnPreview(firstTurn, QUEUE_COLLAPSED_PREVIEW_CHARACTERS)
+      : queuePromptPreview(
+          queue.pendingInputs[0]?.summary ?? "",
+          QUEUE_COLLAPSED_PREVIEW_CHARACTERS,
+        );
+  }, [queue.pendingInputs, queue.queue]);
   const sensors = useSensors(useSensor(PointerSensor, { activationConstraint: { distance: 6 } }));
 
   const displayedQueue = useMemo(() => {
@@ -409,8 +411,8 @@ export function QueueSurface({
                     dir="auto"
                   >
                     {
-                      queuePromptPreview(
-                        queue.queue.find((turn) => turn.id === draggedTurnId)?.prompt ?? "",
+                      queueTurnPreview(
+                        queue.queue.find((turn) => turn.id === draggedTurnId),
                         QUEUE_ROW_PREVIEW_CHARACTERS,
                       ).summary
                     }
@@ -490,6 +492,29 @@ type QueuePromptPreview = {
   isFallback: boolean;
 };
 
+function annotationOnlyQueuePreview(count: number): QueuePromptPreview {
+  const summary = `${count} timeline ${count === 1 ? "annotation" : "annotations"}`;
+  return {
+    summary,
+    collapsedVisual: summary,
+    visibleStart: summary,
+    visibleIdentity: null,
+    visibleIdentityLabel: null,
+    isFallback: false,
+  };
+}
+
+function queueTurnPreview(
+  turn: SessionTurn | undefined,
+  maxCharacters: number,
+): QueuePromptPreview {
+  if (!turn) return queuePromptPreview("", maxCharacters);
+  const annotations = turn.annotations ?? [];
+  return turn.prompt.length === 0 && annotations.length > 0
+    ? annotationOnlyQueuePreview(annotations.length)
+    : queuePromptPreview(turn.prompt, maxCharacters);
+}
+
 /**
  * Build a bounded head/tail summary of an arbitrary queued prompt. Sampling
  * both ends distinguishes prompts with equal long prefixes. Each sampled edge
@@ -752,73 +777,94 @@ function isLowSurrogate(codeUnit: number): boolean {
 
 function QueuePrompt({
   prompt,
+  annotations,
   index,
   onDisclosureChange,
 }: {
   prompt: string;
+  annotations: readonly TimelineAnnotation[];
   index: number;
   onDisclosureChange: (expanded: boolean) => void;
 }) {
   const [expanded, setExpanded] = useState(false);
   const fullContentId = useId();
-  const preview = useMemo(() => queuePromptPreview(prompt, QUEUE_ROW_PREVIEW_CHARACTERS), [prompt]);
+  const preview = useMemo(
+    () =>
+      prompt.length === 0 && annotations.length > 0
+        ? annotationOnlyQueuePreview(annotations.length)
+        : queuePromptPreview(prompt, QUEUE_ROW_PREVIEW_CHARACTERS),
+    [annotations.length, prompt],
+  );
 
   return (
     <div className="w-full min-w-0 max-w-full">
-      <div
-        aria-label={`Queued prompt ${index + 1} summary: ${preview.summary}`}
-        className="max-w-full overflow-hidden text-og-control leading-5 text-fg"
-        data-testid={`queue-prompt-preview-${index + 1}`}
-        dir="auto"
-        role="note"
-      >
-        <span aria-hidden="true" className="flex min-w-0 max-w-full items-baseline gap-2 sm:block">
+      {prompt ? (
+        <div
+          aria-label={`Queued prompt ${index + 1} summary: ${preview.summary}`}
+          className="max-w-full overflow-hidden text-og-control leading-5 text-fg"
+          data-testid={`queue-prompt-preview-${index + 1}`}
+          dir="auto"
+          role="note"
+        >
           <span
-            className={`${preview.isFallback ? "" : "line-clamp-1 sm:line-clamp-2"} min-w-0 flex-1 whitespace-pre-wrap break-all [unicode-bidi:plaintext]`}
-            data-testid={`queue-prompt-start-${index + 1}`}
-            dir="auto"
+            aria-hidden="true"
+            className="flex min-w-0 max-w-full items-baseline gap-2 sm:block"
           >
-            {preview.visibleStart}
-          </span>
-          {preview.visibleIdentity && preview.visibleIdentityLabel ? (
             <span
-              className="flex min-w-0 max-w-[70%] shrink-0 items-center gap-1 text-og-xs leading-4 text-fg-muted sm:mt-0.5 sm:max-w-full"
-              data-testid={`queue-prompt-identity-row-${index + 1}`}
+              className={`${preview.isFallback ? "" : "line-clamp-1 sm:line-clamp-2"} min-w-0 flex-1 whitespace-pre-wrap break-all [unicode-bidi:plaintext]`}
+              data-testid={`queue-prompt-start-${index + 1}`}
+              dir="auto"
             >
-              <span className="shrink-0 font-medium text-fg-subtle">
-                {preview.visibleIdentityLabel}
-              </span>
+              {preview.visibleStart}
+            </span>
+            {preview.visibleIdentity && preview.visibleIdentityLabel ? (
               <span
-                className="min-w-0 overflow-hidden text-ellipsis whitespace-nowrap font-mono [unicode-bidi:plaintext]"
-                data-testid={`queue-prompt-identity-${index + 1}`}
-                dir="auto"
+                className="flex min-w-0 max-w-[70%] shrink-0 items-center gap-1 text-og-xs leading-4 text-fg-muted sm:mt-0.5 sm:max-w-full"
+                data-testid={`queue-prompt-identity-row-${index + 1}`}
               >
-                {preview.visibleIdentity}
+                <span className="shrink-0 font-medium text-fg-subtle">
+                  {preview.visibleIdentityLabel}
+                </span>
+                <span
+                  className="min-w-0 overflow-hidden text-ellipsis whitespace-nowrap font-mono [unicode-bidi:plaintext]"
+                  data-testid={`queue-prompt-identity-${index + 1}`}
+                  dir="auto"
+                >
+                  {preview.visibleIdentity}
+                </span>
               </span>
-            </span>
-          ) : null}
-        </span>
-      </div>
-      <button
-        type="button"
-        aria-controls={fullContentId}
-        aria-expanded={expanded}
-        aria-label={`${expanded ? "Hide" : "Show"} full content for queued prompt ${index + 1}`}
-        className="mt-1 inline-flex min-h-7 min-w-0 max-w-full items-center gap-1 whitespace-normal rounded-md text-left text-og-xs font-medium text-fg outline-hidden focus-visible:ring-2 focus-visible:ring-ring/40 pointer-coarse:min-h-[44px]"
-        data-testid={`queue-prompt-disclosure-${index + 1}`}
-        onClick={() => {
-          const next = !expanded;
-          setExpanded(next);
-          onDisclosureChange(next);
-        }}
-      >
-        <ChevronDownIcon
-          aria-hidden="true"
-          className={`size-3 shrink-0 transition-transform ${expanded ? "rotate-180" : ""}`}
+            ) : null}
+          </span>
+        </div>
+      ) : null}
+      {annotations.length > 0 ? (
+        <TimelineAnnotationsChip
+          annotations={annotations}
+          className={prompt ? "mt-1" : undefined}
         />
-        {expanded ? "Hide full prompt" : "View full prompt"}
-      </button>
-      {expanded ? (
+      ) : null}
+      {prompt ? (
+        <button
+          type="button"
+          aria-controls={fullContentId}
+          aria-expanded={expanded}
+          aria-label={`${expanded ? "Hide" : "Show"} full content for queued prompt ${index + 1}`}
+          className="mt-1 inline-flex min-h-7 min-w-0 max-w-full items-center gap-1 whitespace-normal rounded-md text-left text-og-xs font-medium text-fg outline-hidden focus-visible:ring-2 focus-visible:ring-ring/40 pointer-coarse:min-h-[44px]"
+          data-testid={`queue-prompt-disclosure-${index + 1}`}
+          onClick={() => {
+            const next = !expanded;
+            setExpanded(next);
+            onDisclosureChange(next);
+          }}
+        >
+          <ChevronDownIcon
+            aria-hidden="true"
+            className={`size-3 shrink-0 transition-transform ${expanded ? "rotate-180" : ""}`}
+          />
+          {expanded ? "Hide full prompt" : "View full prompt"}
+        </button>
+      ) : null}
+      {expanded && prompt ? (
         <pre
           id={fullContentId}
           role="region"
@@ -850,7 +896,12 @@ function ReadOnlyQueueRow({
     <li className="flex min-w-0 items-start gap-2 bg-surface px-3 py-2">
       <span className="mt-1 shrink-0 font-mono text-og-xs text-fg-subtle">{index + 1}</span>
       <div className="min-w-0 flex-1">
-        <QueuePrompt prompt={turn.prompt} index={index} onDisclosureChange={onDisclosureChange} />
+        <QueuePrompt
+          prompt={turn.prompt}
+          annotations={turn.annotations ?? []}
+          index={index}
+          onDisclosureChange={onDisclosureChange}
+        />
         {attachedInputs.length > 0 ? (
           <PendingMachineInputs inputs={attachedInputs} attached />
         ) : null}
@@ -941,7 +992,12 @@ function SortableQueueRow({
           {index + 1}
         </span>
         <div className="col-span-full row-start-2 min-w-0 sm:col-span-1 sm:col-start-3 sm:row-start-1">
-          <QueuePrompt prompt={turn.prompt} index={index} onDisclosureChange={onDisclosureChange} />
+          <QueuePrompt
+            prompt={turn.prompt}
+            annotations={turn.annotations ?? []}
+            index={index}
+            onDisclosureChange={onDisclosureChange}
+          />
           {attachedInputs.length > 0 ? (
             <PendingMachineInputs inputs={attachedInputs} attached />
           ) : null}

package/src/components/sandbox-files.tsx

@@ -319,8 +319,8 @@ export function SandboxFiles({
                   path={viewPath}
                   initialContents={fileView.content}
                   themeType={resolvedTheme}
-                  onSave={(contents) =>
-                    files.writeFile(viewPath, contents, { expectedContent: fileView.content! })
+                  onSave={(contents, expectedContents) =>
+                    files.writeFile(viewPath, contents, { expectedContent: expectedContents })
                   }
                   onOverwrite={(contents) => files.writeFile(viewPath, contents, { force: true })}
                   onReload={() => setViewReloadRevision((revision) => revision + 1)}

package/src/components/sandbox-terminal.tsx

@@ -1,9 +1,11 @@
 import type { TerminalCapability } from "@opengeni/sdk";
-import { type ReactNode, useEffect, useRef, useState } from "react";
+import { type ReactNode, useEffect, useLayoutEffect, useRef, useState } from "react";
 import { cn } from "../lib/cn";
-import { useTerminalStream } from "../hooks/use-terminal-stream";
+import { type TerminalStreamStatus, useTerminalStream } from "../hooks/use-terminal-stream";
 import type { UseSandboxTerminalResult } from "../hooks/use-sandbox-terminal";
 import { resolveTerminalFont, xtermThemeFromTokens } from "../lib/xterm-theme";
+import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
+import { terminalCanAcquirePty } from "../lib/terminal-capability";
 import { attachRenderer, type RendererLoaders, type RendererTier } from "../lib/xterm-renderer";
 
 /**
@@ -60,7 +62,7 @@ export type SandboxTerminalProps = {
   fontSize?: number | undefined;
   /**
    * Lease liveness (`cold` | `warming` | `warm` | `draining`). Drives the
-   * boot-in-terminal status lines: once the user has focused the terminal and
+   * boot-in-terminal status lines: once the user has engaged the terminal and
    * the box is not yet warm, a styled "● waking machine — Ns…" line is rendered
    * INSIDE xterm (no overlay/spinner) until the live PTY connects.
    */
@@ -85,6 +87,8 @@ export type SandboxTerminalProps = {
    * the firehose-only default).
    */
   onActivate?: (() => void) | undefined;
+  /** Re-negotiate the terminal capability after an unexpected socket failure. */
+  onReconnectNeeded?: (() => void) | undefined;
   className?: string | undefined;
 };
 
@@ -92,6 +96,7 @@ export type SandboxTerminalProps = {
 // drive it without a hard type dep on the lazily-imported lib.
 type XtermLike = {
   open: (el: HTMLElement) => void;
+  focus: () => void;
   write: (data: string) => void;
   clear: () => void;
   onData: (cb: (data: string) => void) => { dispose: () => void };
@@ -110,6 +115,44 @@ type XtermLike = {
 };
 type FitAddonLike = { fit: () => void };
 
+export type TerminalSurfaceState =
+  | "loading"
+  | "connecting"
+  | "error"
+  | "waking"
+  | "output-only"
+  | "interactive";
+
+/**
+ * Stable semantic state for hosts and browser acceptance. The xterm helper
+ * textarea exists before the live PTY socket is ready, so its presence alone
+ * must never be treated as proof that keystrokes can reach the sandbox.
+ */
+export function terminalSurfaceState(input: {
+  ready: boolean;
+  acceptsInput: boolean;
+  inputPending: boolean;
+  ptyStatus: TerminalStreamStatus;
+  booting: boolean;
+}): TerminalSurfaceState {
+  if (!input.ready) return "loading";
+  if (input.acceptsInput) return "interactive";
+  if (input.inputPending) return "connecting";
+  if (input.ptyStatus === "connecting") return "connecting";
+  if (input.ptyStatus === "error") return "error";
+  if (input.booting) return "waking";
+  return "output-only";
+}
+
+export function subscribeTerminalInput(
+  term: Pick<XtermLike, "onData"> | null,
+  sink: ((data: string) => void) | null,
+  enabled: boolean,
+): { dispose: () => void } | null {
+  if (!enabled || !term || !sink) return null;
+  return term.onData(sink);
+}
+
 /** Clear the transient wake line and put the first live prompt at cell 1,1.
  * `Terminal.clear()` removes scrollback but deliberately preserves the cursor,
  * which lets the first PTY frame append to the old wake message. */
@@ -183,6 +226,7 @@ export function SandboxTerminal({
   showHeader,
   shell,
   onActivate,
+  onReconnectNeeded,
   className,
 }: SandboxTerminalProps) {
   const containerRef = useRef<HTMLDivElement | null>(null);
@@ -193,50 +237,63 @@ export function SandboxTerminal({
   const wroteFirehoseRef = useRef(false);
   const bootActiveRef = useRef(false);
   const [ready, setReady] = useState(false);
+  const [inputReady, setInputReady] = useState(false);
   const [activated, setActivated] = useState(false);
 
   // ── Interactive transport switch ─────────────────────────────────────────────
-  const ptyWs = terminalCapability?.transport === "pty-ws" && Boolean(terminalCapability?.url);
-  // Output frames buffer here until xterm has mounted; the write effect drains it.
-  const ptyOutputQueueRef = useRef<string[]>([]);
+  const ptyDescriptor =
+    terminalCapability?.transport === "pty-ws" || terminalCapability?.transport === "relay-pty";
+  const ptyAttachable = terminalCanAcquirePty(terminalCapability);
   const {
     status: ptyStatus,
     write: ptyWrite,
     resize: resizePty,
     connected: ptyConnected,
   } = useTerminalStream({
-    capability: ptyWs
-      ? {
-          transport: terminalCapability!.transport,
-          url: terminalCapability!.url,
-          token: terminalCapability!.token,
-        }
-      : null,
+    // Connect only after xterm exists. This makes the renderer the sole output
+    // owner from the first websocket frame and removes an otherwise unbounded
+    // pre-mount output queue during large command bursts.
+    capability:
+      ptyAttachable && ready
+        ? {
+            transport: terminalCapability!.transport,
+            url: ptyDescriptor ? terminalCapability!.url : null,
+            token: ptyDescriptor ? terminalCapability!.token : null,
+            expiresAt: ptyDescriptor ? terminalCapability!.expiresAt : null,
+          }
+        : null,
     onOutput: (data) => {
-      const term = termRef.current;
-      if (term) term.write(data);
-      else ptyOutputQueueRef.current.push(data);
+      termRef.current?.write(data);
     },
+    onReconnectNeeded,
   });
 
-  // PTY mode = a live ttyd socket drives the screen. Firehose mode = the
-  // read-only projection (or the legacy HTTP-write fallback).
-  const ptyMode = ptyWs && ptyStatus !== "closed";
-  const interactive = !readOnly && (ptyMode ? ptyConnected : result.write !== null);
-  const terminalModeLabel = interactive
-    ? null
-    : readOnly
-      ? "read-only"
-      : ptyMode && ptyStatus === "connecting"
-        ? "connecting"
-        : ptyMode && ptyStatus === "error"
-          ? "connection error"
-          : "output only";
-
-  // Boot-in-terminal: after the user focuses a not-yet-warm box, show styled
+  // A pty-ws capability exclusively owns the screen even while connecting or
+  // after a visible connection failure; never silently switch one terminal UI
+  // between two PTYs. Input is enabled during the handshake because the stream
+  // hook buffers it strictly and flushes only after ttyd auth succeeds.
+  const ptyMode = ptyDescriptor;
+  // Keep xterm stdin live for an attachable descriptor even before its URL has
+  // arrived. Focus/click triggers the grant; any immediately following input is
+  // bounded in the stream hook instead of disappearing in that HTTP interval.
+  const ptyCapturesInput = ptyAttachable && ptyStatus !== "error";
+  const interactive = !readOnly && (ptyAttachable ? ptyCapturesInput : result.write !== null);
+  // Public "interactive" means the mounted input subscription can reach a live
+  // PTY now. Before that point xterm still captures into the bounded queue, but
+  // acceptance and embedders see an explicit connecting state.
+  const acceptsInput = inputReady && (!ptyAttachable || ptyConnected);
+  const inputPending = inputReady && ptyAttachable && !ptyConnected && activated;
+  let terminalModeLabel: string | null;
+  if (readOnly) terminalModeLabel = "read-only";
+  else if (!ptyAttachable) terminalModeLabel = acceptsInput ? null : "output only";
+  else if (ptyStatus === "error") terminalModeLabel = "connection error";
+  else if (acceptsInput) terminalModeLabel = null;
+  else terminalModeLabel = activated ? "connecting" : "connect on input";
+
+  // Boot-in-terminal: after the user engages a not-yet-warm box, show styled
   // status lines INSIDE xterm instead of an overlay — but only when there is no
   // firehose transcript to show yet (otherwise the projected output is shown).
-  const warm = liveness === "warm" || liveness === "draining";
+  const warm = sandboxAcceptsLiveIo(liveness);
   const booting =
     activated &&
     !ptyMode &&
@@ -244,8 +301,25 @@ export function SandboxTerminal({
     liveness !== null &&
     liveness !== undefined &&
     result.chunks.length === 0;
+  const surfaceState = terminalSurfaceState({
+    ready,
+    acceptsInput,
+    inputPending,
+    ptyStatus,
+    booting,
+  });
 
   function handleActivate() {
+    // Capture-phase activation may synchronously negotiate a fresh terminal
+    // capability and rerender the shell. Focus xterm before that state change so
+    // the user's first keystroke or paste reaches its already-bounded input
+    // queue instead of landing on the surrounding dock.
+    const term = termRef.current;
+    if (term && !readOnly && (ptyAttachable || result.write !== null)) {
+      term.options.disableStdin = false;
+      term.options.cursorBlink = true;
+    }
+    term?.focus();
     if (!activated) setActivated(true);
     onActivate?.();
   }
@@ -361,10 +435,6 @@ export function SandboxTerminal({
       requestAnimationFrame(() => {
         if (disposed) return;
         settle();
-        if (ptyOutputQueueRef.current.length > 0) {
-          for (const data of ptyOutputQueueRef.current) term.write(data);
-          ptyOutputQueueRef.current = [];
-        }
         el.setAttribute("data-og-term-ready", "true");
         if (typeof globalThis.__OG_TERMINAL_DEBUG__ === "function") {
           globalThis.__OG_TERMINAL_DEBUG__({
@@ -397,7 +467,7 @@ export function SandboxTerminal({
 
   // Sync stdin/cursor at runtime (NOT a remount) when interactivity flips, so the
   // projection→PTY handoff keeps the single Terminal instance + its scrollback.
-  useEffect(() => {
+  useLayoutEffect(() => {
     const term = termRef.current;
     if (!ready || !term) return;
     term.options.disableStdin = !interactive;
@@ -455,16 +525,24 @@ export function SandboxTerminal({
     }
   }, [ready, result.chunks, ptyMode]);
 
-  // Wire interactive input when allowed. PTY mode pipes keystrokes to the ttyd
-  // socket; firehose mode uses the legacy ptyWrite-over-HTTP fn.
-  useEffect(() => {
+  // Wire interactive input when allowed. `ptyWrite` is stable across socket
+  // status changes, so this subscription does not tear down while a grant opens
+  // or rotates and cannot create a first-keystroke gap.
+  useLayoutEffect(() => {
     const term = termRef.current;
-    if (!ready || !term || !interactive) return;
-    const sink = ptyMode ? ptyWrite : result.write;
-    if (!sink) return;
-    const sub = term.onData((data) => sink(data));
-    return () => sub.dispose();
-  }, [ready, interactive, ptyMode, ptyWrite, result.write]);
+    if (!ready || !term || !interactive) {
+      setInputReady(false);
+      return;
+    }
+    const sink = ptyAttachable ? ptyWrite : result.write;
+    if (!sink) {
+      setInputReady(false);
+      return;
+    }
+    const sub = subscribeTerminalInput(term, sink, true);
+    setInputReady(sub !== null);
+    return () => sub?.dispose();
+  }, [ready, interactive, ptyAttachable, ptyWrite, result.write]);
 
   // In PTY mode, tell ttyd the window size on the xterm resize event.
   useEffect(() => {
@@ -551,6 +629,10 @@ export function SandboxTerminal({
           className="h-full w-full"
           style={{ visibility: ready ? "visible" : "hidden" }}
           data-opengeni-terminal
+          data-opengeni-terminal-ready={ready ? "true" : "false"}
+          data-opengeni-terminal-interactive={surfaceState === "interactive" ? "true" : "false"}
+          data-opengeni-terminal-state={surfaceState}
+          data-opengeni-terminal-status={ptyAttachable ? ptyStatus : "firehose"}
         />
       </div>
     </div>