@opengeni/react 0.3.1 → 0.5.0

package/src/timeline/activity-rail.tsx

@@ -0,0 +1,207 @@
+import { BotIcon, BrainIcon, SquareTerminalIcon } from "lucide-react";
+import { cn } from "../lib/cn";
+import { truncate } from "../lib/format";
+import { defaultToolRegistry } from "./tool-renderers";
+import type { ToolRegistry } from "./registry";
+import { PayloadBlock, ActivityDisclosure } from "./shared";
+import { toolDisplayName } from "./projection";
+import type { ActivityItem, ReasoningItem, SandboxItem, WorkerItem } from "./types";
+
+/* ----------------------------------------------------------------------------
+   Activity rail
+
+   Renders a run of clustered activity items (reasoning, tool calls, workers,
+   sandbox ops) as the left-bordered column between chat messages. Tool calls
+   resolve through the renderer registry; everything else has a first-class row.
+
+   Shared by `MessageTimeline` and the component demo so both draw the exact
+   same rail — no divergence.
+   -------------------------------------------------------------------------- */
+
+export type ActivityRailProps = {
+  items: ActivityItem[];
+  /** Renderer registry for tool calls. Defaults to {@link defaultToolRegistry}. */
+  toolRegistry?: ToolRegistry | undefined;
+  /** Drill into a spawned worker session. */
+  onOpenSession?: ((sessionId: string) => void) | undefined;
+  /** Drop the left rule + indent (used inside a folded turn summary). */
+  bare?: boolean | undefined;
+  className?: string | undefined;
+};
+
+/**
+ * The "family" a row belongs to, for light intra-rail grouping. Consecutive
+ * rows of the same family sit tight; a family change gets a little extra top
+ * margin so a long run reads as clusters rather than one undifferentiated wall.
+ */
+function familyOf(item: ActivityItem): string {
+  if (item.kind === "tool-call") {
+    return item.name === "exec_command" || item.name === "write_stdin" ? "terminal" : item.name;
+  }
+  return item.kind;
+}
+
+export function ActivityRail({ items, toolRegistry = defaultToolRegistry, onOpenSession, bare, className }: ActivityRailProps) {
+  return (
+    <div
+      className={cn(
+        // Rows sit TIGHT by default (gap-0.5) so a same-family run reads as one
+        // calm cluster; a family change opens real breathing room (mt-3) below,
+        // so a long rail reads as a few clusters, not a metronome of rows.
+        "flex flex-col gap-0.5",
+        !bare && "animate-og-enter border-l-2 border-og-border pl-3 sm:pl-4",
+        className,
+      )}
+    >
+      {items.map((item, index) => {
+        const newFamily = index > 0 && familyOf(item) !== familyOf(items[index - 1]!);
+        const row = renderActivity(item, toolRegistry, onOpenSession);
+        return (
+          <div key={item.id} className={cn(newFamily && "mt-3")}>
+            {row}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+/** A never-reachable guard: adding an `ActivityItem` kind is now a compile error. */
+function assertNever(item: never): never {
+  throw new Error(`ActivityRail: unhandled activity item ${JSON.stringify(item)}`);
+}
+
+function renderActivity(
+  item: ActivityItem,
+  toolRegistry: ToolRegistry,
+  onOpenSession: ((sessionId: string) => void) | undefined,
+) {
+  switch (item.kind) {
+    case "reasoning":
+      return <ReasoningRow item={item} />;
+    case "tool-call": {
+      const Renderer = toolRegistry.resolve(item);
+      return <Renderer item={item} />;
+    }
+    case "worker":
+      return <WorkerRow item={item} onOpenSession={onOpenSession} />;
+    case "sandbox":
+      return <SandboxRow item={item} />;
+    default:
+      return assertNever(item);
+  }
+}
+
+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.
+  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)}
+    >
+      <p className="whitespace-pre-wrap text-og-base leading-6 text-og-fg-muted">{item.text}</p>
+    </ActivityDisclosure>
+  );
+}
+
+function SandboxRow({ item }: { item: SandboxItem }) {
+  return (
+    <ActivityDisclosure
+      icon={<SquareTerminalIcon className="size-3.5" />}
+      iconTone={item.status === "failed" ? "failed" : item.status === "running" ? "running" : "muted"}
+      title={toolDisplayName(item.name)}
+      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, onOpenSession }: { item: WorkerItem; onOpenSession?: ((sessionId: string) => void) | undefined }) {
+  const running = item.status === "running";
+  const failed = item.status === "failed";
+  const cancelled = item.status === "cancelled";
+  const title =
+    item.action === "spawn"
+      ? running
+        ? "Spawning worker"
+        : failed
+          ? "Worker spawn failed"
+          : cancelled
+            ? "Worker interrupted"
+            : "Worker spawned"
+      : running
+        ? "Messaging worker"
+        : failed
+          ? "Worker message failed"
+          : cancelled
+            ? "Worker interrupted"
+            : "Worker messaged";
+  return (
+    <div
+      className={cn(
+        "my-0.5 flex items-start gap-3 rounded-og-md border bg-og-surface-1 p-3",
+        failed ? "border-og-status-failed/40" : "border-og-border",
+      )}
+    >
+      <span
+        className={cn(
+          "mt-0.5 inline-flex size-7 shrink-0 items-center justify-center",
+          failed ? "text-og-status-failed" : "text-og-accent",
+        )}
+      >
+        <BotIcon className="size-4" />
+      </span>
+      <div className="min-w-0 flex-1">
+        {/* In-flight state is carried ONLY by the shimmering title (no detached
+            pulse badge), matching every other running row in the rail. */}
+        <span className={cn("text-og-base font-medium", running ? "og-shimmer-text" : failed ? "text-og-status-failed" : "text-og-fg")}>
+          {title}
+        </span>
+        {item.prompt ? <p className="mt-0.5 truncate text-og-sm text-og-fg-muted">{truncate(item.prompt, 140)}</p> : null}
+        {item.workerSessionId ? (
+          <p className="mt-1 font-og-mono text-og-xs text-og-fg-subtle">{item.workerSessionId.slice(0, 8)}</p>
+        ) : null}
+      </div>
+      {/* Right gutter: failed gets a red chip; cancelled gets a calm "interrupted"
+          chip (no dot, no red); a live complete worker shows an "Open session" button. */}
+      {failed ? (
+        <span className="inline-flex shrink-0 self-center items-center gap-1.5 font-og-mono text-og-xs leading-none text-og-status-failed">
+          <span className="size-1.5 rounded-full bg-og-status-failed" />
+          failed
+        </span>
+      ) : cancelled ? (
+        <span className="og-cancelled-chip shrink-0 self-center font-og-mono text-og-xs leading-none text-og-fg-subtle">
+          interrupted
+        </span>
+      ) : item.workerSessionId && onOpenSession ? (
+        <button
+          type="button"
+          onClick={() => item.workerSessionId && onOpenSession(item.workerSessionId)}
+          className={cn(
+            "shrink-0 self-center rounded-og-sm border border-og-border px-2.5 py-1 text-og-sm font-medium text-og-fg-muted",
+            "outline-none transition-colors duration-150 hover:border-og-border-strong hover:text-og-fg",
+            "focus-visible:ring-2 focus-visible:ring-og-accent",
+          )}
+        >
+          Open session
+        </button>
+      ) : null}
+    </div>
+  );
+}

package/src/timeline/disclosure-context.tsx

@@ -0,0 +1,34 @@
+import { createContext, useContext, type ReactNode } from "react";
+
+/* ----------------------------------------------------------------------------
+   Disclosure defaults context
+
+   A tiny, opt-in context that lets an ancestor seed the INITIAL open state of
+   every collapsible in the timeline (ActivityDisclosure rows and TurnSummary
+   chips). Its sole intended use is deterministic screenshot capture: a tool can
+   force every card open so a headless render shows expanded bodies.
+
+   It is fully inert in normal app usage. With no provider, the hook returns
+   `undefined`, every collapsible keeps its own author-chosen default, and there
+   is zero change to how the components look or animate. Mounting the provider
+   only changes the SEED of the initial `open` state — Radix still owns the
+   open/close transition, so animations are untouched.
+   -------------------------------------------------------------------------- */
+
+const DisclosureDefaultsContext = createContext<boolean | undefined>(undefined);
+
+/**
+ * Seed the initial open state of every timeline collapsible below this node.
+ * Intended for screenshot/test instrumentation only; absent by default.
+ */
+export function DisclosureDefaultsProvider({ defaultOpen, children }: { defaultOpen: boolean; children: ReactNode }) {
+  return <DisclosureDefaultsContext.Provider value={defaultOpen}>{children}</DisclosureDefaultsContext.Provider>;
+}
+
+/**
+ * The forced initial-open seed from an ancestor {@link DisclosureDefaultsProvider},
+ * or `undefined` when none is mounted (the inert, app-default case).
+ */
+export function useForcedDefaultOpen(): boolean | undefined {
+  return useContext(DisclosureDefaultsContext);
+}

package/src/timeline/index.ts

@@ -0,0 +1,85 @@
+/* ----------------------------------------------------------------------------
+   @opengeni/react — timeline module
+
+   The session timeline's data + rendering layer:
+     - projection.ts   raw SessionEvents -> renderable TimelineItems (pure)
+     - types.ts        the projected item shapes (the data contract)
+     - registry.ts     the extensible, typed tool-renderer registry
+     - tool-renderers  per-tool React renderers + the default registry
+     - parsers.ts      pure provider-shape parsers (exec banner, V4A diff, …)
+     - shared.tsx      the restraint primitives (ActivityDisclosure, TermBlock, …)
+     - tool-diff.tsx   V4A GitFileDiff -> the real DiffView/PierreDiff stack
+     - screenshot-lightbox.tsx  the app-level screenshot lightbox
+
+   This barrel is the module's public surface. The components here are the
+   single source of truth used by both the live app and the component demo.
+   -------------------------------------------------------------------------- */
+
+// projection
+export { buildTimeline, extractSessionRef, groupTimeline, sessionStatusFromEvents, toolDisplayName } from "./projection";
+
+// item types
+export type {
+  ActivityItem,
+  AgentMessageItem,
+  GoalItem,
+  NoticeItem,
+  ReasoningItem,
+  SandboxItem,
+  SessionStatusItem,
+  TimelineGroup,
+  TimelineItem,
+  ToolCallItem,
+  UserMessageItem,
+  WorkerItem,
+} from "./types";
+
+// renderer registry
+export { createToolRegistry, rawTypeOf } from "./registry";
+export type {
+  CreateToolRegistryOptions,
+  ToolRegistry,
+  ToolRegistryEntry,
+  ToolRenderer,
+  ToolRendererProps,
+} from "./registry";
+
+// default renderers + registry
+export { createDefaultToolRegistry, defaultToolRegistry } from "./tool-renderers";
+
+// the activity rail (the clustered reasoning/tool/worker/sandbox column)
+export { ActivityRail } from "./activity-rail";
+export type { ActivityRailProps } from "./activity-rail";
+
+// shared primitives (extension authors compose these)
+export { ActivityDisclosure, BodyNote, MediaEmpty, MediaSkeleton, PayloadBlock, ScreenshotFigure, TermBlock, Thumbnail } from "./shared";
+export type { ActivityDisclosureProps, DisclosureChip } from "./shared";
+
+// screenshot lightbox
+export { LightboxProvider, useLightbox, useLightboxOptional } from "./screenshot-lightbox";
+
+// disclosure defaults (opt-in initial-open seed; for screenshot/test instrumentation)
+export { DisclosureDefaultsProvider, useForcedDefaultOpen } from "./disclosure-context";
+
+// turn-collapse summary chip
+export { TurnSummary } from "./turn-summary";
+export type { TurnOutcome, TurnSummaryProps } from "./turn-summary";
+
+// parsers (pure, reusable by custom renderers)
+export {
+  applyPatchOps,
+  controlCaret,
+  execTruncated,
+  isApplyPatch,
+  isExecSessionLostBanner,
+  looksBinary,
+  parseExecBannerSessionId,
+  parseToolArgs,
+  redactSecrets,
+  sandboxCommandExitCode,
+  stripExecBanner,
+  tailPeek,
+  unwrapMcpOutput,
+  v4aToGitFileDiff,
+} from "./parsers";
+export type { ApplyPatchOperation } from "./parsers";

package/src/timeline/parsers.ts

@@ -0,0 +1,253 @@
+import type { GitFileDiff } from "@opengeni/sdk";
+import { tryParseJson } from "../lib/format";
+
+/* ----------------------------------------------------------------------------
+   Pure parsers for the provider-native tool shapes that the timeline renders.
+
+   These are intentionally browser-safe, dependency-free mirrors of the
+   server-side helpers in `@opengeni/runtime` (`sandboxCommandExitCode`,
+   `parseExecBannerSessionId`, `stripExecBanner`) plus the V4A diff parser the
+   apply-patch renderer needs. The SDK does not depend on `@opengeni/runtime` by
+   design (runtime is a heavy server package); these few regexes are cheap to
+   own here and keep the React surface free of a server dependency.
+
+   Every function is pure -- same input, same output -- so it can be
+   unit-tested and memoized.
+   -------------------------------------------------------------------------- */
+
+/** Recover the exit code from a sandbox exec banner (`Process exited with code N`). */
+export function sandboxCommandExitCode(out: unknown): number | null {
+  const match = String(out ?? "").match(/Process exited with code (-?\d+)/);
+  return match ? Number(match[1]) : null;
+}
+
+/**
+ * Recover the numeric exec-session id the sandbox embeds for a STILL-RUNNING
+ * (backgrounded) process (`Process running with session ID N`). A finished
+ * command emits `Process exited with code N` instead, which yields `null`.
+ */
+export function parseExecBannerSessionId(out: unknown): number | null {
+  const text = String(out ?? "");
+  const outputIdx = text.indexOf("\nOutput:\n");
+  const banner = outputIdx >= 0 ? text.slice(0, outputIdx) : text.startsWith("Output:\n") ? "" : text;
+  const match = banner.match(/Process running with session ID (\d+)/);
+  if (!match) {
+    return null;
+  }
+  const n = Number.parseInt(match[1]!, 10);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** Strip the exec banner (`Chunk ID ...\n...\nOutput:\n`) down to the command's stdout. */
+export function stripExecBanner(out: unknown): string {
+  const text = String(out ?? "");
+  const marker = text.indexOf("\nOutput:\n");
+  if (marker >= 0) {
+    return text.slice(marker + "\nOutput:\n".length);
+  }
+  if (text.startsWith("Output:\n")) {
+    return text.slice("Output:\n".length);
+  }
+  return text;
+}
+
+/** The sandbox clamped the output (token/line truncation markers in the banner). */
+export function execTruncated(out: unknown): boolean {
+  return /Total output lines:|\.{3}\d+ tokens truncated\.{3}|\[\.{3}\d+ characters truncated/.test(String(out ?? ""));
+}
+
+/** A `write_stdin` whose target PTY vanished (`write_stdin failed: session not found: N`). */
+export function isExecSessionLostBanner(out: unknown): boolean {
+  return /write_stdin failed: session not found: \d+/.test(String(out ?? ""));
+}
+
+/** True when the exec stdout looks binary/garbled (a NUL byte or ELF magic). */
+export function looksBinary(text: string): boolean {
+  return text.includes("\u0000") || text.startsWith("\u007fELF");
+}
+
+/**
+ * Render unprintable control characters as caret notation (0x03 -> `^C`) so a
+ * `write_stdin` keystroke payload reads cleanly in the row title.
+ */
+export function controlCaret(printable: string): string {
+  return String(printable).replace(/[\u0000-\u001f]/g, (c) => `^${String.fromCharCode(c.charCodeAt(0) + 64)}`);
+}
+
+/* --- V4A apply_patch diff -> GitFileDiff ------------------------------------ */
+
+/** One operation inside an `apply_patch_call` (a V4A file edit). */
+export type ApplyPatchOperation = {
+  /**
+   * The V4A op kind. The three canonical values are `create_file`,
+   * `update_file`, and `delete_file`; the open `string` tail tolerates a
+   * forward-compatible/unknown op kind from the provider without a type error
+   * (it falls through to the "Edited" treatment).
+   */
+  type: "create_file" | "update_file" | "delete_file" | (string & {});
+  path: string;
+  /** Rename target -- when present the op is a move/rename. */
+  moveTo?: string | null | undefined;
+  /** The V4A hunk string (`@@ ...` lines with `+`/`-`/context prefixes). */
+  diff?: string | undefined;
+};
+
+/**
+ * Parse a single V4A `apply_patch` operation into the SDK's `GitFileDiff` shape
+ * so it can flow into the SAME `DiffView` / `PierreDiff` the Files tab uses.
+ * Throws on a hunk string it cannot structure (no `@@` anchor on an update); the
+ * renderer catches and falls back to a raw-patch view.
+ */
+export function v4aToGitFileDiff(op: ApplyPatchOperation): GitFileDiff {
+  const status: GitFileDiff["status"] =
+    op.type === "create_file" ? "added" : op.type === "delete_file" ? "deleted" : op.moveTo ? "renamed" : "modified";
+  const oldPath = op.moveTo ? op.path : null;
+  const path = op.moveTo || op.path;
+
+  const hunks: GitFileDiff["hunks"] = [];
+  let additions = 0;
+  let deletions = 0;
+  let sawHunkAnchor = false;
+
+  if (op.type !== "delete_file") {
+    const lines = (op.diff ?? "").split("\n");
+    let cur: GitFileDiff["hunks"][number] | null = null;
+    let oldNo = 1;
+    let newNo = 1;
+    for (const raw of lines) {
+      if (raw.startsWith("@@")) {
+        sawHunkAnchor = true;
+        const match = raw.match(/-(\d+)(?:,\d+)?\s+\+(\d+)/);
+        oldNo = match ? Number(match[1]) : 1;
+        newNo = match ? Number(match[2]) : 1;
+        cur = {
+          oldStart: oldNo,
+          oldLines: 0,
+          newStart: newNo,
+          newLines: 0,
+          header: raw,
+          lines: [{ type: "meta", oldNo: null, newNo: null, text: raw }],
+        };
+        hunks.push(cur);
+      } else if (cur || op.type === "create_file") {
+        if (!cur) {
+          // No `@@` anchor on a create_file body: synthesize an add-only hunk.
+          // Leave `header` empty so `gitFileDiffToPatch` regenerates a valid
+          // `@@ -0,0 +1,N @@` from the range fields once newLines is counted — a
+          // pre-baked partial header (e.g. `@@ +1 @@`) renders zero lines in a
+          // generic unified-diff parser.
+          cur = { oldStart: 0, oldLines: 0, newStart: 1, newLines: 0, header: "", lines: [] };
+          hunks.push(cur);
+          oldNo = 0;
+          newNo = 1;
+        }
+        if (raw.startsWith("+")) {
+          cur.lines.push({ type: "add", oldNo: null, newNo: newNo++, text: raw.slice(1) });
+          cur.newLines += 1;
+          additions += 1;
+        } else if (raw.startsWith("-")) {
+          cur.lines.push({ type: "del", oldNo: oldNo++, newNo: null, text: raw.slice(1) });
+          cur.oldLines += 1;
+          deletions += 1;
+        } else {
+          cur.lines.push({ type: "context", oldNo: oldNo++, newNo: newNo++, text: raw.replace(/^ /, "") });
+          cur.oldLines += 1;
+          cur.newLines += 1;
+        }
+      }
+    }
+    // An update with content but no recognizable hunk anchor is malformed V4A;
+    // the caller falls back to the raw-patch view instead of a structured diff.
+    if (op.type === "update_file" && !sawHunkAnchor && lines.some((l) => l.trim().length > 0)) {
+      throw new Error("malformed V4A: no @@ hunk anchor");
+    }
+  }
+
+  return { path, oldPath, status, isBinary: false, isImage: false, additions, deletions, hunks, truncated: false };
+}
+
+/**
+ * Extract the `apply_patch` operations from a provider-native tool item's `raw`
+ * payload, normalizing the two wire shapes (`raw.operations[]` for a multi-file
+ * patch, `raw.operation` for a single op). The single owner of this shape so the
+ * renderer and the turn-summary facet counter never drift.
+ */
+export function applyPatchOps(raw: unknown): ApplyPatchOperation[] {
+  const r = (raw ?? {}) as { operation?: ApplyPatchOperation; operations?: ApplyPatchOperation[] };
+  if (Array.isArray(r.operations)) {
+    return r.operations;
+  }
+  return r.operation ? [r.operation] : [];
+}
+
+/**
+ * True when a tool item is an `apply_patch_call` — by its provider-native
+ * `raw.type` (the live-wire source of truth) or by tool `name` (first-party
+ * replays that omit `raw`). Centralizes the rawType-or-name check.
+ */
+export function isApplyPatch(item: { name: string; raw: unknown }): boolean {
+  const type = item.raw && typeof item.raw === "object" ? (item.raw as { type?: unknown }).type : undefined;
+  return type === "apply_patch_call" || item.name === "apply_patch_call";
+}
+
+/* --- secret redaction ------------------------------------------------------- */
+
+const SECRET_KEY = /^(value|secret|token|password|api[_-]?key|signing[_-]?key)$/i;
+
+/** Deep-redact secret-looking values so arguments never leak a key into the UI. */
+export function redactSecrets(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(redactSecrets);
+  }
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      out[k] = SECRET_KEY.test(k) ? "••••" : redactSecrets(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+/** Parse tool arguments that may arrive as a JSON string or an object. */
+export function parseToolArgs(args: unknown): Record<string, unknown> {
+  if (args == null) {
+    return {};
+  }
+  if (typeof args === "string") {
+    const parsed = tryParseJson(args);
+    return parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : {};
+  }
+  return typeof args === "object" ? (args as Record<string, unknown>) : {};
+}
+
+/** The last non-empty line of a string -- the compact "what happened" peek. */
+export function tailPeek(text: string): string {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return "";
+  }
+  const lines = trimmed.split("\n");
+  return lines[lines.length - 1] ?? "";
+}
+
+/**
+ * Unwrap an MCP tool result (`{ content: [{ type: "text", text }], isError? }`)
+ * into a flat `{ text, isError }`. Non-MCP outputs pass through as their string
+ * form.
+ */
+export function unwrapMcpOutput(output: unknown): { text: string; isError: boolean } {
+  if (output && typeof output === "object" && "content" in output) {
+    const record = output as { content?: unknown; isError?: unknown };
+    const isError = Boolean(record.isError);
+    if (Array.isArray(record.content)) {
+      const textPart = record.content.find(
+        (part): part is { type: string; text: string } =>
+          !!part && typeof part === "object" && (part as { type?: unknown }).type === "text",
+      );
+      return { text: textPart ? String(textPart.text) : JSON.stringify(output), isError };
+    }
+    return { text: JSON.stringify(output), isError };
+  }
+  return { text: typeof output === "string" ? output : output == null ? "" : JSON.stringify(output), isError: false };
+}