@opengeni/react 0.3.1 → 0.5.0

package/src/hooks/use-terminal-stream.ts

@@ -0,0 +1,207 @@
+import {
+  TTYD_SUBPROTOCOL,
+  TerminalCapability,
+  terminalSocketUrl,
+  ttydAuthFrame,
+  ttydInputFrame,
+  ttydResizeFrame,
+  TtydServerCommand,
+} from "@opengeni/sdk";
+import { useEffect, useMemo, useRef, useState } from "react";
+
+/** The ttyd connection lifecycle as surfaced to the component. */
+export type TerminalStreamStatus = "connecting" | "open" | "closed" | "error";
+
+export type UseTerminalStreamOptions = {
+  /** The Terminal cell of the negotiated capabilities (`capabilities.Terminal`).
+   *  The stream connects ONLY when `transport === "pty-ws"` and `url` is set; on a
+   *  cold box (`transport === "sse-events"` / no url) it stays idle and the caller
+   *  falls back to the Channel-A read-only firehose. */
+  capability: Pick<TerminalCapability, "transport" | "url" | "token"> | null;
+  /** Called for each OUTPUT payload from ttyd (write verbatim into xterm). */
+  onOutput?: ((data: string) => void) | undefined;
+  /** Called when ttyd sends a SET_WINDOW_TITLE frame. */
+  onTitle?: ((title: string) => void) | undefined;
+  /** Initial PTY size to seed the ttyd auth frame + first resize. */
+  initialCols?: number | undefined;
+  initialRows?: number | undefined;
+};
+
+export type UseTerminalStreamResult = {
+  /** True once the ttyd socket is open (and the auth frame has been sent). */
+  connected: boolean;
+  status: TerminalStreamStatus;
+  /** Pipe a keystroke/paste to the PTY stdin. No-op until the socket is open. */
+  write: (data: string) => void;
+  /** Tell ttyd the PTY window changed size (on xterm fit/resize). */
+  resize: (cols: number, rows: number) => void;
+  /** Tear the socket down (the effect also tears down on unmount / url change). */
+  disconnect: () => void;
+};
+
+/** Decode an inbound ttyd frame's payload (everything after the 1-char command).
+ *  ttyd may send either a text frame (string) or a binary frame (ArrayBuffer);
+ *  for binary we slice off the first byte (the command) and utf-8 decode the rest. */
+function decodeFrame(data: string | ArrayBuffer): { command: string; payload: string } {
+  if (typeof data === "string") {
+    return { command: data.charAt(0), payload: data.slice(1) };
+  }
+  const bytes = new Uint8Array(data);
+  const command = bytes.length > 0 ? String.fromCharCode(bytes[0]!) : "";
+  const payload = bytes.length > 1 ? new TextDecoder().decode(bytes.subarray(1)) : "";
+  return { command, payload };
+}
+
+/**
+ * Drive a ttyd PTY-over-websocket connection from a `pty-ws` Terminal capability,
+ * symmetric with `use-desktop-stream` (the noVNC-over-tunnel hook). The scoped
+ * stream token is already embedded in the minted tunnel `url`; the WebSocket is
+ * opened with the REQUIRED ttyd subprotocol "tty".
+ *
+ * ttyd wire protocol (see `@opengeni/sdk/terminal`):
+ *   - first frame: `JSON.stringify({ AuthToken: "" })` (+ optional columns/rows).
+ *   - client→server: INPUT = "0"+data ; RESIZE = "1"+JSON({columns,rows}).
+ *   - server→client: "0" = OUTPUT (→ xterm) ; "1" = SET_WINDOW_TITLE ;
+ *     "2" = SET_PREFERENCES (ignored). Binary frames are decoded the same way.
+ *
+ * On a `url`/`token` rotation (a box rollover folds a fresh address into the cell)
+ * the effect re-runs: the old socket closes and a fresh one connects — a brief
+ * terminal blink, acceptable on rollover (mirrors the desktop's RFB hot-swap).
+ * SSR-safe: the socket open lives in `useEffect`, so a server render is a no-op.
+ */
+export function useTerminalStream(options: UseTerminalStreamOptions): UseTerminalStreamResult {
+  const { capability, onOutput, onTitle, initialCols, initialRows } = options;
+  const [status, setStatus] = useState<TerminalStreamStatus>("closed");
+  const wsRef = useRef<WebSocket | null>(null);
+  // Latest size, so a resize() before the socket opens is replayed on open, and a
+  // reconnect seeds the right geometry.
+  const sizeRef = useRef<{ cols: number; rows: number }>({
+    cols: initialCols ?? 80,
+    rows: initialRows ?? 24,
+  });
+  // Keep the callbacks current without re-running the connect effect on every
+  // render (the parent passes fresh closures each time).
+  const onOutputRef = useRef(onOutput);
+  const onTitleRef = useRef(onTitle);
+  onOutputRef.current = onOutput;
+  onTitleRef.current = onTitle;
+
+  const transport = capability?.transport ?? null;
+  const url = capability?.url ?? null;
+  const token = capability?.token ?? null;
+
+  useEffect(() => {
+    // SSR / no WebSocket / not a live pty-ws cell: stay closed; the caller falls
+    // back to the Channel-A read-only firehose.
+    if (typeof window === "undefined" || typeof WebSocket === "undefined") return;
+    if (transport !== "pty-ws" || !url) {
+      setStatus("closed");
+      return;
+    }
+
+    let disposed = false;
+    let socket: WebSocket;
+    setStatus("connecting");
+    try {
+      // The ttyd "tty" subprotocol is REQUIRED — ttyd rejects a handshake without
+      // it. The scoped token is already in the tunnel `url`.
+      socket = new WebSocket(terminalSocketUrl({ url }), TTYD_SUBPROTOCOL);
+    } catch {
+      setStatus("error");
+      return;
+    }
+    socket.binaryType = "arraybuffer";
+    wsRef.current = socket;
+
+    socket.onopen = () => {
+      if (disposed) return;
+      // ttyd's required first frame: the auth message (empty token — the gate is
+      // the tunnel url + scoped stream token, not a ttyd -c credential), seeded
+      // with the current PTY geometry. Then an explicit resize to be safe.
+      try {
+        socket.send(ttydAuthFrame({ columns: sizeRef.current.cols, rows: sizeRef.current.rows }));
+        socket.send(ttydResizeFrame(sizeRef.current.cols, sizeRef.current.rows));
+      } catch {
+        // a closed socket between open and send — onclose handles state.
+      }
+      setStatus("open");
+    };
+
+    socket.onmessage = (ev: MessageEvent) => {
+      if (disposed) return;
+      const { command, payload } = decodeFrame(ev.data as string | ArrayBuffer);
+      switch (command) {
+        case TtydServerCommand.OUTPUT:
+          onOutputRef.current?.(payload);
+          break;
+        case TtydServerCommand.SET_WINDOW_TITLE:
+          onTitleRef.current?.(payload);
+          break;
+        // SET_PREFERENCES ("2") and anything else: ignored.
+        default:
+          break;
+      }
+    };
+
+    socket.onerror = () => {
+      if (!disposed) setStatus("error");
+    };
+    socket.onclose = () => {
+      if (!disposed) setStatus("closed");
+    };
+
+    return () => {
+      disposed = true;
+      wsRef.current = null;
+      // Drop handlers so an in-flight close/error doesn't mutate state post-unmount.
+      socket.onopen = null;
+      socket.onmessage = null;
+      socket.onerror = null;
+      socket.onclose = null;
+      try {
+        socket.close();
+      } catch {
+        // ignore teardown errors
+      }
+    };
+    // A url/token change (rotation) re-runs this effect → close old, open new.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [transport, url, token]);
+
+  return useMemo<UseTerminalStreamResult>(() => {
+    const write = (data: string) => {
+      const ws = wsRef.current;
+      if (ws && ws.readyState === WebSocket.OPEN) {
+        try {
+          ws.send(ttydInputFrame(data));
+        } catch {
+          // socket raced closed — the reconnect effect will re-establish.
+        }
+      }
+    };
+    const resize = (cols: number, rows: number) => {
+      if (cols <= 0 || rows <= 0) return;
+      sizeRef.current = { cols, rows };
+      const ws = wsRef.current;
+      if (ws && ws.readyState === WebSocket.OPEN) {
+        try {
+          ws.send(ttydResizeFrame(cols, rows));
+        } catch {
+          // socket raced closed — geometry is replayed on the next open.
+        }
+      }
+    };
+    const disconnect = () => {
+      const ws = wsRef.current;
+      wsRef.current = null;
+      if (ws) {
+        try {
+          ws.close();
+        } catch {
+          // ignore
+        }
+      }
+    };
+    return { connected: status === "open", status, write, resize, disconnect };
+  }, [status]);
+}

package/src/index.ts

@@ -9,7 +9,7 @@ export { OpenGeniProvider, useOpenGeni, useOpenGeniClient } from "./provider";
 export type { ClientOverride, OpenGeniContextValue, OpenGeniProviderProps } from "./provider";
 
 // Hooks
-export { useSession } from "./hooks/use-session";
+export { useSession, isTitleEvent } from "./hooks/use-session";
 export type { UseSessionOptions, UseSessionResult } from "./hooks/use-session";
 export { useSessionEvents } from "./hooks/use-session-events";
 export type { SessionEventsConnectionState, UseSessionEventsOptions, UseSessionEventsResult } from "./hooks/use-session-events";
@@ -46,6 +46,37 @@ export type { UseBillingUsageOptions, UseBillingUsageResult } from "./hooks/use-
 export { useAvailableModels } from "./hooks/use-available-models";
 export type { UseAvailableModelsOptions, UseAvailableModelsResult } from "./hooks/use-available-models";
 
+// Sandbox surfacing (Phase 5): capability negotiation + terminal/files/diff/desktop
+export { useSessionCapabilities } from "./hooks/use-session-capabilities";
+export type {
+  SessionCapabilitiesState,
+  UseSessionCapabilitiesOptions,
+  UseSessionCapabilitiesResult,
+} from "./hooks/use-session-capabilities";
+export { useDesktopStream } from "./hooks/use-desktop-stream";
+export type { UseDesktopStreamOptions, UseDesktopStreamResult } from "./hooks/use-desktop-stream";
+export { useTerminalStream } from "./hooks/use-terminal-stream";
+export type {
+  TerminalStreamStatus,
+  UseTerminalStreamOptions,
+  UseTerminalStreamResult,
+} from "./hooks/use-terminal-stream";
+export { useSandboxTerminal } from "./hooks/use-sandbox-terminal";
+export type {
+  TerminalChunk,
+  UseSandboxTerminalOptions,
+  UseSandboxTerminalResult,
+} from "./hooks/use-sandbox-terminal";
+export { useSandboxFiles } from "./hooks/use-sandbox-files";
+export type {
+  FileTreeNode,
+  FileTreeStatus,
+  UseSandboxFilesOptions,
+  UseSandboxFilesResult,
+} from "./hooks/use-sandbox-files";
+export { useSandboxGit } from "./hooks/use-sandbox-git";
+export type { UseSandboxGitOptions, UseSandboxGitResult } from "./hooks/use-sandbox-git";
+
 // Pending-approvals projection
 export { approvalsFromRequiresAction, projectPendingApprovals } from "./approvals";
 export type { PendingApproval } from "./approvals";
@@ -53,13 +84,13 @@ export type { PendingApproval } from "./approvals";
 // Timeline projection
 export {
   buildTimeline,
-  compactPayloadPreview,
   extractSessionRef,
   groupTimeline,
   sessionStatusFromEvents,
   toolDisplayName,
 } from "./timeline";
 export type {
+  ActivityItem,
   AgentMessageItem,
   GoalItem,
   NoticeItem,
@@ -73,6 +104,60 @@ export type {
   WorkerItem,
 } from "./timeline";
 
+// Tool-renderer registry + the per-tool renderers (the timeline's extension API)
+export { createDefaultToolRegistry, createToolRegistry, defaultToolRegistry, rawTypeOf } from "./timeline";
+export type {
+  CreateToolRegistryOptions,
+  ToolRegistry,
+  ToolRegistryEntry,
+  ToolRenderer,
+  ToolRendererProps,
+} from "./timeline";
+
+// Timeline rendering primitives + the screenshot lightbox (compose custom renderers)
+export {
+  ActivityDisclosure,
+  ActivityRail,
+  BodyNote,
+  DisclosureDefaultsProvider,
+  LightboxProvider,
+  MediaEmpty,
+  MediaSkeleton,
+  PayloadBlock,
+  ScreenshotFigure,
+  TermBlock,
+  Thumbnail,
+  TurnSummary,
+  useLightbox,
+  useLightboxOptional,
+} from "./timeline";
+export type {
+  ActivityDisclosureProps,
+  ActivityRailProps,
+  DisclosureChip,
+  TurnOutcome,
+  TurnSummaryProps,
+} from "./timeline";
+
+// Pure provider-shape parsers (exec banner, V4A diff, secret redaction, …)
+export {
+  applyPatchOps,
+  controlCaret,
+  execTruncated,
+  isApplyPatch,
+  isExecSessionLostBanner,
+  looksBinary,
+  parseExecBannerSessionId,
+  parseToolArgs,
+  redactSecrets,
+  sandboxCommandExitCode,
+  stripExecBanner,
+  tailPeek,
+  unwrapMcpOutput,
+  v4aToGitFileDiff,
+} from "./timeline";
+export type { ApplyPatchOperation } from "./timeline";
+
 // Slash-command palette (registry + UI + hook)
 export {
   argHint,
@@ -107,7 +192,7 @@ export { ChatComposer } from "./components/chat-composer";
 export type { ChatComposerProps } from "./components/chat-composer";
 export { ModelPicker } from "./components/model-picker";
 export type { ModelPickerProps } from "./components/model-picker";
-export { MessageTimeline } from "./components/message-timeline";
+export { MessageTimeline, TimelineRow } from "./components/message-timeline";
 export type { MessageTimelineProps } from "./components/message-timeline";
 export { Markdown } from "./components/markdown";
 export type { MarkdownProps } from "./components/markdown";
@@ -116,6 +201,30 @@ export type { SessionStatusProps, StatusDotProps, SessionStatusMeta } from "./co
 export { FleetTile, sessionDisplayTitle } from "./components/fleet-tile";
 export type { FleetTileProps } from "./components/fleet-tile";
 
+// Sandbox surfacing components (Phase 5)
+export { SandboxTerminal } from "./components/sandbox-terminal";
+export type { SandboxTerminalProps, XtermTheme } from "./components/sandbox-terminal";
+export { FileBrowser } from "./components/file-browser";
+export type { FileBrowserProps } from "./components/file-browser";
+export { DiffView } from "./components/diff-view";
+export type { DiffViewProps, DiffTheme } from "./components/diff-view";
+export { PierreDiff } from "./components/pierre-diff";
+export type { PierreDiffProps } from "./components/pierre-diff";
+export { PierreFile } from "./components/pierre-file";
+export type { PierreFileProps } from "./components/pierre-file";
+export { CodeEditor, languageForPath } from "./components/code-editor";
+export type { CodeEditorProps } from "./components/code-editor";
+export { SandboxFiles } from "./components/sandbox-files";
+export type { SandboxFilesProps } from "./components/sandbox-files";
+export { DesktopViewer } from "./components/desktop-viewer";
+export type { DesktopViewerProps } from "./components/desktop-viewer";
+export { WorkspaceDock } from "./components/workspace-dock";
+export type { WorkspaceDockProps, WorkspaceTab } from "./components/workspace-dock";
+
+// Sandbox helpers
+export { gitFileDiffToPatch } from "./lib/git-patch";
+export { xtermThemeFromTokens } from "./lib/xterm-theme";
+
 // Utilities
 export { cn } from "./lib/cn";
 export { formatBytes, formatRelativeTime, stringifyPayload, truncate, tryParseJson } from "./lib/format";

package/src/lib/cn.ts

@@ -1,5 +1,24 @@
 import { clsx, type ClassValue } from "clsx";
-import { twMerge } from "tailwind-merge";
+import { extendTailwindMerge } from "tailwind-merge";
+
+/* ----------------------------------------------------------------------------
+   tailwind-merge, taught our design tokens.
+
+   Our type scale and color ramp share the `og-` prefix: `text-og-base` is a
+   FONT SIZE, `text-og-fg-muted` is a COLOR. Stock tailwind-merge can't tell
+   them apart — it lumps every `text-og-*` into one `font-size` group and, when
+   two land in the same class list, drops the earlier one. That silently ate the
+   size off rows like `text-og-base text-og-fg-muted`, leaving titles at the
+   browser-default 16px. Register the custom font-size scale so the size and the
+   color live in different conflict groups and both survive a merge.
+   -------------------------------------------------------------------------- */
+const twMerge = extendTailwindMerge({
+  extend: {
+    classGroups: {
+      "font-size": [{ text: ["og-xs", "og-sm", "og-base", "og-md"] }],
+    },
+  },
+});
 
 /** Merge class names with Tailwind-aware conflict resolution. */
 export function cn(...inputs: ClassValue[]): string {

package/src/lib/git-patch.ts

@@ -0,0 +1,43 @@
+import type { GitFileDiff } from "@opengeni/sdk";
+
+/**
+ * Reconstruct a unified-diff patch string for a single `GitFileDiff` so it can
+ * be fed to a generic patch renderer (e.g. Pierre's `PatchDiff`). The hook
+ * already carries per-line old/new numbers and a hunk header, so we emit a
+ * conventional `--- / +++ / @@` patch the parser understands.
+ */
+export function gitFileDiffToPatch(file: GitFileDiff): string {
+  const oldPath = file.oldPath ?? file.path;
+  const newPath = file.path;
+  const lines: string[] = [];
+  lines.push(`diff --git a/${oldPath} b/${newPath}`);
+  if (file.status === "deleted") {
+    lines.push(`--- a/${oldPath}`);
+    lines.push(`+++ /dev/null`);
+  } else if (file.status === "added" || file.status === "untracked") {
+    lines.push(`--- /dev/null`);
+    lines.push(`+++ b/${newPath}`);
+  } else {
+    lines.push(`--- a/${oldPath}`);
+    lines.push(`+++ b/${newPath}`);
+  }
+  for (const hunk of file.hunks) {
+    // Only trust a pre-parsed header if it carries the full unified range form
+    // `@@ -<o>[,<n>] +<o>[,<n>] @@`. A synthesized create_file hunk (parsers.ts)
+    // can carry a degenerate `@@ +1 @@` with no `-`/`+` ranges; a generic patch
+    // parser (Pierre) renders zero lines from it, so the expanded diff comes up
+    // empty while the collapsed chip still shows the (correct) addition count.
+    // In that case regenerate a valid header from the hunk's range fields.
+    const headerIsValid = /^@@ -\d+(?:,\d+)? \+\d+(?:,\d+)? @@/.test(hunk.header ?? "");
+    const header = headerIsValid
+      ? hunk.header
+      : `@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@`;
+    lines.push(header);
+    for (const line of hunk.lines) {
+      if (line.type === "meta") continue;
+      const prefix = line.type === "add" ? "+" : line.type === "del" ? "-" : " ";
+      lines.push(`${prefix}${line.text}`);
+    }
+  }
+  return lines.join("\n") + "\n";
+}

package/src/lib/use-theme-type.ts

@@ -0,0 +1,40 @@
+import { useEffect, useState } from "react";
+
+/* ----------------------------------------------------------------------------
+   useThemeType
+
+   Resolve the effective dark/light theme for surfaces (the Pierre/Shiki diff)
+   that render outside the reach of host CSS — they need the theme as a value,
+   not a cascade. An explicit prop always wins; otherwise read the host's
+   `data-og-theme` attribute (set on `<html>` or any ancestor by the same opt-in
+   the tokens use) and default to dark, the first-class theme. A MutationObserver
+   keeps it live across runtime theme flips.
+
+   One detector, shared by every diff surface (the Files tab and the timeline),
+   so the two can never drift onto different themes.
+   -------------------------------------------------------------------------- */
+
+/**
+ * Resolve the diff theme. An explicit `forced` value wins; otherwise auto-detect
+ * from the host `data-og-theme` (defaulting to dark) and track live flips.
+ */
+export function useThemeType(forced: "dark" | "light" | undefined): "dark" | "light" {
+  const [detected, setDetected] = useState<"dark" | "light">("dark");
+  useEffect(() => {
+    if (forced || typeof document === "undefined") return;
+    const read = () => {
+      const el = document.querySelector("[data-og-theme]");
+      const value = el?.getAttribute("data-og-theme");
+      setDetected(value === "light" ? "light" : "dark");
+    };
+    read();
+    const observer = new MutationObserver(read);
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["data-og-theme"],
+      subtree: true,
+    });
+    return () => observer.disconnect();
+  }, [forced]);
+  return forced ?? detected;
+}

package/src/lib/xterm-theme.ts

@@ -0,0 +1,34 @@
+import type { XtermTheme } from "../components/sandbox-terminal";
+
+/**
+ * Derive an xterm `ITheme` subset from the live OKLCH `--og-*` token system (or
+ * the app's `--color-*` aliases). Reads the COMPUTED values so xterm — which
+ * paints into a canvas and can't consume CSS vars — gets concrete colors. Call
+ * on mount and re-derive on a `data-og-theme` flip.
+ *
+ * SSR-safe: returns undefined off the DOM (the caller keeps xterm's defaults).
+ */
+export function xtermThemeFromTokens(root?: HTMLElement | null): XtermTheme | undefined {
+  if (typeof window === "undefined" || typeof getComputedStyle === "undefined") return undefined;
+  const el = root ?? document.documentElement;
+  const style = getComputedStyle(el);
+  const read = (names: string[]): string | undefined => {
+    for (const name of names) {
+      const value = style.getPropertyValue(name).trim();
+      if (value) return value;
+    }
+    return undefined;
+  };
+  const bg = read(["--og-color-bg", "--color-bg"]);
+  const fg = read(["--og-color-fg", "--color-fg"]);
+  const accent = read(["--og-color-accent", "--color-brand", "--color-accent"]);
+  const theme: XtermTheme = {};
+  if (bg) theme.background = bg;
+  if (fg) theme.foreground = fg;
+  if (accent) {
+    theme.cursor = accent;
+    theme.selectionBackground = accent;
+  }
+  if (bg) theme.cursorAccent = bg;
+  return Object.keys(theme).length > 0 ? theme : undefined;
+}