@opengeni/react 0.3.1 → 0.5.0

package/src/{timeline.ts → timeline/projection.ts}

@@ -1,5 +1,16 @@
-import type { ResourceRef, SessionEvent, SessionStatus, ToolRef } from "@opengeni/sdk";
-import { stringifyPayload, tryParseJson } from "./lib/format";
+import type { SessionEvent, SessionStatus } from "@opengeni/sdk";
+import { tryParseJson } from "../lib/format";
+import type {
+  AgentMessageItem,
+  ActivityItem,
+  GoalItem,
+  SandboxItem,
+  SessionStatusItem,
+  TimelineGroup,
+  TimelineItem,
+  ToolCallItem,
+  WorkerItem,
+} from "./types";
 
 /* ----------------------------------------------------------------------------
    Timeline projection
@@ -15,112 +26,6 @@ import { stringifyPayload, tryParseJson } from "./lib/format";
    memoized, unit-tested, and re-run incrementally as new events stream in.
    -------------------------------------------------------------------------- */
 
-export type UserMessageItem = {
-  kind: "user-message";
-  id: string;
-  text: string;
-  /** Resources attached to this message (file uploads, repositories). */
-  resources: ResourceRef[];
-  /** Tools requested for the turn this message starts. */
-  tools: ToolRef[];
-  occurredAt: string;
-};
-
-export type AgentMessageItem = {
-  kind: "agent-message";
-  id: string;
-  turnId: string | null;
-  text: string;
-  /** Still receiving deltas (no completed/turn-end seen yet). */
-  streaming: boolean;
-  occurredAt: string;
-};
-
-export type ReasoningItem = {
-  kind: "reasoning";
-  id: string;
-  turnId: string | null;
-  text: string;
-  streaming: boolean;
-  occurredAt: string;
-};
-
-export type ToolCallItem = {
-  kind: "tool-call";
-  id: string;
-  turnId: string | null;
-  callId: string | null;
-  name: string;
-  arguments: unknown;
-  output: unknown;
-  status: "running" | "complete";
-  occurredAt: string;
-};
-
-/**
- * An orchestration call against another session — the manager spawning or
- * messaging a worker. Rendered as a first-class "worker" row, not a generic
- * tool call.
- */
-export type WorkerItem = {
-  kind: "worker";
-  id: string;
-  turnId: string | null;
-  callId: string | null;
-  action: "spawn" | "message";
-  /** The worker's initial message / the message sent to it, when parseable. */
-  prompt: string | null;
-  /** The target/spawned worker session id, when parseable from args/output. */
-  workerSessionId: string | null;
-  status: "running" | "complete";
-  occurredAt: string;
-};
-
-export type SandboxItem = {
-  kind: "sandbox";
-  id: string;
-  turnId: string | null;
-  name: string;
-  command: string | null;
-  output: string;
-  status: "running" | "complete" | "failed";
-  occurredAt: string;
-};
-
-export type SessionStatusItem = {
-  kind: "session-status";
-  id: string;
-  status: SessionStatus;
-  occurredAt: string;
-};
-
-export type GoalItem = {
-  kind: "goal";
-  id: string;
-  action: "set" | "updated" | "completed" | "paused" | "resumed" | "continuation";
-  text: string | null;
-  occurredAt: string;
-};
-
-export type NoticeItem = {
-  kind: "notice";
-  id: string;
-  tone: "waiting" | "cancelled" | "failed";
-  text: string;
-  occurredAt: string;
-};
-
-export type TimelineItem =
-  | UserMessageItem
-  | AgentMessageItem
-  | ReasoningItem
-  | ToolCallItem
-  | WorkerItem
-  | SandboxItem
-  | SessionStatusItem
-  | GoalItem
-  | NoticeItem;
-
 /** Tool names on the first-party OpenGeni MCP server that operate on sessions. */
 const WORKER_SPAWN_TOOL = "session_create";
 const WORKER_MESSAGE_TOOL = "session_send_message";
@@ -139,7 +44,7 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
     }
   };
 
-  const finalizeOpen = (turnId?: string | null): void => {
+  const finalizeOpen = (turnId?: string | null, disposition: "complete" | "failed" | "cancelled" = "complete"): void => {
     for (const item of items) {
       if (turnId !== undefined && "turnId" in item && item.turnId && turnId && item.turnId !== turnId) {
         continue;
@@ -148,10 +53,10 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         item.streaming = false;
       }
       if ((item.kind === "tool-call" || item.kind === "worker") && item.status === "running") {
-        item.status = "complete";
+        item.status = disposition;
       }
       if (item.kind === "sandbox" && item.status === "running") {
-        item.status = "complete";
+        item.status = disposition;
       }
     }
   };
@@ -276,6 +181,9 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
           name,
           arguments: args,
           output: undefined,
+          // The provider-native item drives the per-tool renderers (apply_patch
+          // operation, computer_call action, web_search providerData, …).
+          raw: payload.raw,
           status: "running",
           occurredAt: event.occurredAt,
         });
@@ -289,11 +197,15 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
           break;
         }
         if (target.kind === "worker") {
-          target.status = "complete";
+          // A worker spawn/message that returns an error flag (or an MCP
+          // isError result) settles to "failed" too, so WorkerRow surfaces it.
+          target.status = isErrorOutput(payload) ? "failed" : "complete";
           target.workerSessionId = target.workerSessionId ?? extractSessionRef(payload.output);
           break;
         }
-        target.status = "complete";
+        // An output carrying an explicit error flag (or an MCP isError result)
+        // settles the tool to "failed" so the renderer can surface it loudly.
+        target.status = isErrorOutput(payload) ? "failed" : "complete";
         target.output = payload.output;
         break;
       }
@@ -375,7 +287,7 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
       }
 
       case "turn.failed": {
-        finalizeOpen(turnId);
+        finalizeOpen(turnId, "failed");
         items.push({
           kind: "notice",
           id: event.id,
@@ -387,7 +299,7 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
       }
 
       case "turn.cancelled": {
-        finalizeOpen(turnId);
+        finalizeOpen(turnId, "cancelled");
         items.push({
           kind: "notice",
           id: event.id,
@@ -442,22 +354,32 @@ export function sessionStatusFromEvents(events: SessionEvent[]): SessionStatus |
    sandbox) cluster into one collapsible block between chat messages.
    -------------------------------------------------------------------------- */
 
-export type TimelineGroup =
-  | { kind: "item"; item: TimelineItem }
-  | { kind: "activity"; id: string; items: (ReasoningItem | ToolCallItem | WorkerItem | SandboxItem)[] };
-
-const ACTIVITY_KINDS = new Set(["reasoning", "tool-call", "worker", "sandbox"]);
+/**
+ * Whether an item clusters into an activity block. A `switch` (not a stringly-
+ * typed set) so adding an {@link ActivityItem} kind is a compile-time prompt to
+ * decide its grouping — and it narrows `item` to `ActivityItem` with no cast.
+ */
+function isActivityItem(item: TimelineItem): item is ActivityItem {
+  switch (item.kind) {
+    case "reasoning":
+    case "tool-call":
+    case "worker":
+    case "sandbox":
+      return true;
+    default:
+      return false;
+  }
+}
 
 export function groupTimeline(items: TimelineItem[]): TimelineGroup[] {
   const groups: TimelineGroup[] = [];
   for (const item of items) {
-    if (ACTIVITY_KINDS.has(item.kind)) {
+    if (isActivityItem(item)) {
       const open = groups[groups.length - 1];
-      const activity = item as ReasoningItem | ToolCallItem | WorkerItem | SandboxItem;
       if (open?.kind === "activity") {
-        open.items.push(activity);
+        open.items.push(item);
       } else {
-        groups.push({ kind: "activity", id: `activity-${item.id}`, items: [activity] });
+        groups.push({ kind: "activity", id: `activity-${item.id}`, items: [item] });
       }
       continue;
     }
@@ -475,11 +397,11 @@ function asRecord(value: unknown): Record<string, unknown> {
 const SESSION_STATUSES: readonly SessionStatus[] = ["queued", "running", "idle", "requires_action", "failed", "cancelled"];
 
 /** Keep only entries that match the wire shapes; user payloads are untyped. */
-function resourceRefs(value: unknown): ResourceRef[] {
+function resourceRefs(value: unknown): import("@opengeni/sdk").ResourceRef[] {
   if (!Array.isArray(value)) {
     return [];
   }
-  return value.filter((entry): entry is ResourceRef => {
+  return value.filter((entry): entry is import("@opengeni/sdk").ResourceRef => {
     const record = asRecord(entry);
     if (record.kind === "repository") {
       return typeof record.uri === "string" && typeof record.ref === "string";
@@ -488,11 +410,11 @@ function resourceRefs(value: unknown): ResourceRef[] {
   });
 }
 
-function toolRefs(value: unknown): ToolRef[] {
+function toolRefs(value: unknown): import("@opengeni/sdk").ToolRef[] {
   if (!Array.isArray(value)) {
     return [];
   }
-  return value.filter((entry): entry is ToolRef => {
+  return value.filter((entry): entry is import("@opengeni/sdk").ToolRef => {
     const record = asRecord(entry);
     return record.kind === "mcp" && typeof record.id === "string";
   });
@@ -502,6 +424,15 @@ function isSessionStatus(value: unknown): value is SessionStatus {
   return typeof value === "string" && (SESSION_STATUSES as readonly string[]).includes(value);
 }
 
+/** Does this tool output represent an error (explicit flag or MCP `isError`)? */
+function isErrorOutput(payload: Record<string, unknown>): boolean {
+  if (payload.error === true || payload.failed === true) {
+    return true;
+  }
+  const output = payload.output;
+  return !!output && typeof output === "object" && (output as { isError?: unknown }).isError === true;
+}
+
 function findOpenCall(items: TimelineItem[], callId: string | null): ToolCallItem | WorkerItem | undefined {
   const reversed = [...items].reverse();
   const isCall = (item: TimelineItem): item is ToolCallItem | WorkerItem => item.kind === "tool-call" || item.kind === "worker";
@@ -624,9 +555,3 @@ function looksLikeId(value: string): boolean {
 export function toolDisplayName(name: string): string {
   return name.replace(/[_-]+/g, " ").trim();
 }
-
-/** Compact, single-line preview of tool arguments/outputs for collapsed rows. */
-export function compactPayloadPreview(value: unknown, maxLength = 120): string {
-  const text = stringifyPayload(value).replace(/\s+/g, " ").trim();
-  return text.length > maxLength ? `${text.slice(0, maxLength - 1)}…` : text;
-}

package/src/timeline/registry.ts

@@ -0,0 +1,96 @@
+import type { ComponentType } from "react";
+import type { ToolCallItem } from "./types";
+
+/* ----------------------------------------------------------------------------
+   Tool renderer registry
+
+   The extension point. A `ToolRenderer` is a React component fed one projected
+   `ToolCallItem`; the registry resolves which renderer handles a given call,
+   keyed on the tool `name` and (secondarily) its provider-native `raw.type`.
+
+   Resolution order (most → least specific):
+     1. exact match on `raw.type`        (e.g. "apply_patch_call", "computer_call")
+     2. exact match on the tool `name`   (e.g. "exec_command", "web_search_call")
+     3. the registry's generic fallback
+
+   A consumer extends the defaults without forking by passing overrides to
+   `createToolRegistry` — e.g. a custom renderer for their own MCP tool, or a
+   replacement for a built-in one. The registry is immutable and fully typed.
+   -------------------------------------------------------------------------- */
+
+export type ToolRendererProps = {
+  item: ToolCallItem;
+};
+
+export type ToolRenderer = ComponentType<ToolRendererProps>;
+
+/** A registry entry: which key it matches and the component that renders it. */
+export type ToolRegistryEntry =
+  | { match: "rawType"; type: string; render: ToolRenderer }
+  | { match: "name"; name: string; render: ToolRenderer };
+
+export type ToolRegistry = {
+  /** Resolve the renderer for a call (never null — falls back to generic). */
+  resolve: (item: ToolCallItem) => ToolRenderer;
+  /** The generic fallback renderer. */
+  fallback: ToolRenderer;
+};
+
+export type CreateToolRegistryOptions = {
+  /**
+   * Entries that take precedence over the built-ins. Earlier entries win, so a
+   * consumer can shadow a default renderer for the same key.
+   */
+  entries?: ToolRegistryEntry[] | undefined;
+  /** Replace the generic fallback used for unmatched tools. */
+  fallback?: ToolRenderer | undefined;
+};
+
+/** The `raw.type` of a projected tool call, when the provider item carries one. */
+export function rawTypeOf(item: ToolCallItem): string | null {
+  const raw = item.raw;
+  if (raw && typeof raw === "object" && typeof (raw as { type?: unknown }).type === "string") {
+    return (raw as { type: string }).type;
+  }
+  return null;
+}
+
+/**
+ * Build a tool registry from a set of entries and a fallback. The returned
+ * registry resolves in priority order: `raw.type` entries first, then `name`
+ * entries, then the fallback. Consumer `entries` are consulted before the
+ * built-in `baseEntries`, so they shadow defaults cleanly.
+ */
+export function createToolRegistry(
+  baseEntries: ToolRegistryEntry[],
+  baseFallback: ToolRenderer,
+  options: CreateToolRegistryOptions = {},
+): ToolRegistry {
+  const entries = [...(options.entries ?? []), ...baseEntries];
+  const fallback = options.fallback ?? baseFallback;
+
+  const byRawType = new Map<string, ToolRenderer>();
+  const byName = new Map<string, ToolRenderer>();
+  for (const entry of entries) {
+    if (entry.match === "rawType") {
+      if (!byRawType.has(entry.type)) {
+        byRawType.set(entry.type, entry.render);
+      }
+    } else if (!byName.has(entry.name)) {
+      byName.set(entry.name, entry.render);
+    }
+  }
+
+  const resolve = (item: ToolCallItem): ToolRenderer => {
+    const rawType = rawTypeOf(item);
+    if (rawType) {
+      const byType = byRawType.get(rawType);
+      if (byType) {
+        return byType;
+      }
+    }
+    return byName.get(item.name) ?? fallback;
+  };
+
+  return { resolve, fallback };
+}

package/src/timeline/screenshot-lightbox.tsx

@@ -0,0 +1,152 @@
+import { XIcon } from "lucide-react";
+import { AnimatePresence, motion } from "motion/react";
+import { createContext, useCallback, useContext, useMemo, useState, type ReactNode } from "react";
+import { Dialog } from "radix-ui";
+import { cn } from "../lib/cn";
+
+/* ----------------------------------------------------------------------------
+   Screenshot lightbox
+
+   A single, app-level lightbox the computer_call / view_image renderers open by
+   `src`. Built on Radix Dialog so it is focus-trapped, ESC-closable, and
+   scroll-locked — fixing the v1 mockup's broken expand (an absolutely-positioned
+   <img> that overflowed its row). The image is centered, constrained to the
+   viewport (`max-w/max-h` + `object-contain`), and sits on a dimmed backdrop.
+
+   Consumers render `<LightboxProvider>` once near the timeline; renderers call
+   `useLightbox().open(src)`.
+   -------------------------------------------------------------------------- */
+
+type LightboxController = {
+  open: (src: string, caption?: string) => void;
+};
+
+const LightboxContext = createContext<LightboxController | null>(null);
+
+/** Open the app-level screenshot lightbox. No-op outside a `LightboxProvider`. */
+export function useLightbox(): LightboxController {
+  return useContext(LightboxContext) ?? NOOP;
+}
+
+/**
+ * The lightbox controller when one is mounted, or `null` outside a
+ * `LightboxProvider`. Lets a media primitive degrade to a non-interactive image
+ * (rather than a dead "Expand" button that announces an action it cannot do).
+ */
+export function useLightboxOptional(): LightboxController | null {
+  return useContext(LightboxContext);
+}
+
+const NOOP: LightboxController = { open: () => {} };
+
+/**
+ * The app-level screenshot lightbox. Render once near the timeline; renderers
+ * call `useLightbox().open(src)`.
+ *
+ * Idempotent by design: when an ancestor `LightboxProvider` already exists (e.g.
+ * a `MessageTimeline` mounted inside an app that already wraps its shell), this
+ * one becomes a pass-through and does NOT mount a second focus-trapping Dialog.
+ * That keeps `MessageTimeline` self-sufficient (it owns its own provider) while
+ * composing cleanly when nested.
+ */
+export function LightboxProvider({ children }: { children: ReactNode }) {
+  const ancestor = useContext(LightboxContext);
+  if (ancestor) {
+    return <>{children}</>;
+  }
+  return <LightboxRoot>{children}</LightboxRoot>;
+}
+
+function LightboxRoot({ children }: { children: ReactNode }) {
+  const [state, setState] = useState<{ src: string; caption?: string } | null>(null);
+
+  const open = useCallback((src: string, caption?: string) => {
+    setState(caption ? { src, caption } : { src });
+  }, []);
+
+  const controller = useMemo<LightboxController>(() => ({ open }), [open]);
+
+  return (
+    <LightboxContext.Provider value={controller}>
+      {children}
+      <Dialog.Root open={state !== null} onOpenChange={(next) => !next && setState(null)}>
+        <AnimatePresence>
+          {state !== null ? (
+            <Dialog.Portal forceMount>
+              <Dialog.Overlay asChild forceMount>
+                <motion.div
+                  initial={{ opacity: 0 }}
+                  animate={{ opacity: 1 }}
+                  exit={{ opacity: 0 }}
+                  transition={{ duration: 0.15 }}
+                  className="og-root fixed inset-0 z-50 bg-black/90 backdrop-blur-md"
+                />
+              </Dialog.Overlay>
+              <Dialog.Content
+                asChild
+                forceMount
+                aria-label="Screenshot"
+                onOpenAutoFocus={(event) => event.preventDefault()}
+              >
+                <motion.div
+                  initial={{ opacity: 0, scale: 0.98 }}
+                  animate={{ opacity: 1, scale: 1 }}
+                  exit={{ opacity: 0, scale: 0.98 }}
+                  transition={{ duration: 0.18, ease: [0.16, 1, 0.3, 1] }}
+                  // Content is a full-inset centering wrapper layered above the
+                  // Overlay, so Radix's own click-outside (which fires on the
+                  // Overlay) can never see a backdrop click — every click lands on
+                  // Content. We make Content's own backdrop dismiss: a click whose
+                  // target is the wrapper itself (not the figure) closes it, so the
+                  // figcaption's "click outside to close" affordance is real.
+                  onClick={(event) => {
+                    if (event.target === event.currentTarget) {
+                      setState(null);
+                    }
+                  }}
+                  className="og-root fixed inset-0 z-50 flex items-center justify-center p-6 sm:p-12"
+                >
+                  <Dialog.Title className="sr-only">Screenshot</Dialog.Title>
+                  {/* The figure is one self-contained object: image, caption, and
+                      its own close control. The close button anchors to a wrapper
+                      sized to the IMAGE (w-fit), so it hugs the real top-right
+                      corner regardless of aspect ratio — never floating into the
+                      empty space of a wide figure column. */}
+                  <figure className="m-0 flex max-h-full max-w-5xl flex-col items-center gap-3">
+                    <div className="relative flex min-h-0 w-fit max-w-full">
+                      {/* A plain <img>: this SDK is framework-agnostic, with no host Image component. */}
+                      <img
+                        src={state.src}
+                        alt={state.caption ?? "Screenshot"}
+                        className="min-h-0 max-h-[82vh] w-auto max-w-full rounded-og-md border border-white/10 object-contain shadow-og-lg"
+                      />
+                      <Dialog.Close
+                        className={cn(
+                          "absolute -right-3 -top-3 inline-flex size-9 items-center justify-center rounded-full",
+                          "border border-white/15 bg-black/60 text-white/70 backdrop-blur",
+                          "transition-colors hover:border-white/30 hover:text-white",
+                        )}
+                        aria-label="Close"
+                      >
+                        <XIcon className="size-4" />
+                      </Dialog.Close>
+                    </div>
+                    {state.caption ? (
+                      <figcaption className="max-w-2xl text-center font-og-mono text-og-xs text-white/55">
+                        {state.caption}
+                      </figcaption>
+                    ) : (
+                      <figcaption className="font-og-mono text-[10px] uppercase tracking-[0.1em] text-white/35">
+                        Esc or click outside to close
+                      </figcaption>
+                    )}
+                  </figure>
+                </motion.div>
+              </Dialog.Content>
+            </Dialog.Portal>
+          ) : null}
+        </AnimatePresence>
+      </Dialog.Root>
+    </LightboxContext.Provider>
+  );
+}