@opengeni/react 0.11.0 → 0.13.0

package/src/timeline/activity-rail.tsx

@@ -1,12 +1,18 @@
-import { BotIcon, BrainIcon, SquareTerminalIcon } from "lucide-react";
+import {
+  ArrowRightIcon,
+  BotIcon,
+  BrainCircuitIcon,
+  BrainIcon,
+  SquareTerminalIcon,
+} from "lucide-react";
 import { cn } from "../lib/cn";
 import { truncate } from "../lib/format";
 import { defaultToolRegistry } from "./tool-renderers";
 import { useEntranceAnimation } from "./entrance";
 import type { ToolRegistry } from "./registry";
-import { PayloadBlock, ActivityDisclosure } from "./shared";
+import { BodyNote, PayloadBlock, ActivityDisclosure } from "./shared";
 import { toolDisplayName } from "./projection";
-import type { ActivityItem, ReasoningItem, SandboxItem, WorkerItem } from "./types";
+import type { ActivityItem, MemoryItem, ReasoningItem, SandboxItem, WorkerItem } from "./types";
 
 /* ----------------------------------------------------------------------------
    Activity rail
@@ -25,6 +31,12 @@ export type ActivityRailProps = {
   toolRegistry?: ToolRegistry | undefined;
   /** Drill into a spawned worker session. */
   onOpenSession?: ((sessionId: string) => void) | undefined;
+  /**
+   * Deep-link a memory row to its record in the host's memory pane. Opt-in: the
+   * library draws no "View in memory" affordance without a handler (the memory
+   * row is then non-interactive rich content). See {@link MessageTimelineProps}.
+   */
+  onMemoryClick?: ((memoryId: string) => void) | undefined;
   /** Drop the left rule + indent (used inside a folded turn summary). */
   bare?: boolean | undefined;
   className?: string | undefined;
@@ -42,7 +54,14 @@ function familyOf(item: ActivityItem): string {
   return item.kind;
 }
 
-export function ActivityRail({ items, toolRegistry = defaultToolRegistry, onOpenSession, bare, className }: ActivityRailProps) {
+export function ActivityRail({
+  items,
+  toolRegistry = defaultToolRegistry,
+  onOpenSession,
+  onMemoryClick,
+  bare,
+  className,
+}: ActivityRailProps) {
   const enter = useEntranceAnimation();
   return (
     <div
@@ -58,7 +77,7 @@ export function ActivityRail({ items, toolRegistry = defaultToolRegistry, onOpen
     >
       {items.map((item, index) => {
         const newFamily = index > 0 && familyOf(item) !== familyOf(items[index - 1]!);
-        const row = renderActivity(item, toolRegistry, onOpenSession);
+        const row = renderActivity(item, toolRegistry, onOpenSession, onMemoryClick);
         return (
           <div key={item.id} className={cn(newFamily && "mt-3")}>
             {row}
@@ -78,6 +97,7 @@ function renderActivity(
   item: ActivityItem,
   toolRegistry: ToolRegistry,
   onOpenSession: ((sessionId: string) => void) | undefined,
+  onMemoryClick: ((memoryId: string) => void) | undefined,
 ) {
   switch (item.kind) {
     case "reasoning":
@@ -90,6 +110,8 @@ function renderActivity(
       return <WorkerRow item={item} onOpenSession={onOpenSession} />;
     case "sandbox":
       return <SandboxRow item={item} />;
+    case "memory":
+      return <MemoryRow item={item} onMemoryClick={onMemoryClick} />;
     default:
       return assertNever(item);
   }
@@ -117,12 +139,131 @@ function ReasoningRow({ item }: { item: ReasoningItem }) {
   );
 }
 
+/**
+ * Human labels for the memory kinds, translated at the SDK boundary so a raw
+ * enum slug never renders as UI. Kept local to the library (the app has its own
+ * `KIND_LABEL`); an unknown kind simply omits the chip rather than showing a slug.
+ */
+const MEMORY_KIND_LABEL: Record<string, string> = {
+  preference: "Preference",
+  semantic: "Fact",
+  procedural: "Procedure",
+  decision: "Decision",
+  episodic: "History",
+};
+
+/**
+ * A memory write the agent made mid-turn. A calm, NEUTRAL step (a successful save
+ * is ordinary progress, never an exceptional state, so no accent/color): a brain-
+ * circuit glyph, "Saved to memory" / "Updated memory", a human kind chip, and the
+ * memory text. Expanding reveals the full text; a supersede shows the old text
+ * struck through above the new one. When the host opts in with `onMemoryClick`,
+ * a quiet "View in memory" affordance deep-links to the LIVE record.
+ */
+function MemoryRow({
+  item,
+  onMemoryClick,
+}: {
+  item: MemoryItem;
+  onMemoryClick?: ((memoryId: string) => void) | undefined;
+}) {
+  const corrected = item.variant === "corrected";
+  const kindLabel = MEMORY_KIND_LABEL[item.memoryKind];
+  // A supersede carries both the old text (`preview`) and the new (`replacementPreview`);
+  // an in-place update / archive carries only `preview`.
+  const superseded = corrected && Boolean(item.replacementPreview);
+  // Link to the LIVE record: a supersede's replacement when present, else the memory itself.
+  const targetId = corrected ? (item.replacementMemoryId ?? item.memoryId) : item.memoryId;
+  const deepLink = Boolean(onMemoryClick);
+  return (
+    <ActivityDisclosure
+      icon={<BrainCircuitIcon className="size-3.5" />}
+      iconTone="muted"
+      title={
+        <span className="inline-flex min-w-0 items-center gap-2">
+          <span className="shrink-0">{corrected ? "Updated memory" : "Saved to memory"}</span>
+          {kindLabel ? (
+            <span className="shrink-0 rounded-og-xs bg-og-surface-2 px-1.5 py-px text-og-xs font-normal leading-tight text-og-fg-subtle">
+              {kindLabel}
+            </span>
+          ) : null}
+        </span>
+      }
+      preview={superseded ? item.replacementPreview : item.preview}
+    >
+      {superseded ? (
+        // The correction as a before → after: the old memory struck through and
+        // dimmed, the new text in the ordinary body weight below it.
+        <div className="flex flex-col gap-1.5">
+          <p className="whitespace-pre-wrap text-og-sm leading-6 text-og-fg-subtle line-through">
+            {item.preview}
+          </p>
+          <p className="whitespace-pre-wrap text-og-base leading-6 text-og-fg-muted">
+            {item.replacementPreview}
+          </p>
+        </div>
+      ) : corrected && item.action === "updated" ? (
+        // Edited in place, no replacement record: the memory is still live, so
+        // show its current text — NOT the archived treatment.
+        <>
+          <p className="whitespace-pre-wrap text-og-base leading-6 text-og-fg-muted">
+            {item.preview}
+          </p>
+          <BodyNote tone="muted">Updated in place.</BodyNote>
+        </>
+      ) : corrected ? (
+        // A correction with no replacement (and not an in-place update) archived the record.
+        <BodyNote tone="muted">Archived.</BodyNote>
+      ) : (
+        <p className="whitespace-pre-wrap text-og-base leading-6 text-og-fg-muted">
+          {item.preview}
+        </p>
+      )}
+      {item.deduped ? <BodyNote tone="muted">Merged into an existing memory.</BodyNote> : null}
+      {deepLink ? (
+        <button
+          type="button"
+          onClick={() => onMemoryClick?.(targetId)}
+          className={cn(
+            "group/memlink -mx-1 inline-flex w-fit items-center gap-1 rounded-og-sm px-1 py-0.5 text-left text-og-sm text-og-fg-subtle",
+            "outline-none transition-colors duration-150 hover:text-og-fg focus-visible:ring-2 focus-visible:ring-og-accent",
+          )}
+        >
+          View in memory
+          <ArrowRightIcon className="size-3.5 transition-transform duration-150 group-hover/memlink:translate-x-0.5" />
+        </button>
+      ) : null}
+    </ActivityDisclosure>
+  );
+}
+
+/**
+ * A human title for a sandbox operation row. Named platform operations (the lazy
+ * `sandbox.provision` first-establish that now runs mid-turn) read as calm,
+ * status-aware English instead of a raw op id — the box coming up should look
+ * like "Starting sandbox", never an unexplained long-running command. Unnamed /
+ * unknown ops fall back to the generic id-to-words {@link toolDisplayName}.
+ */
+function sandboxRowTitle(item: SandboxItem): string {
+  if (item.name === "sandbox.provision") {
+    if (item.status === "failed") return "Sandbox didn’t start";
+    if (item.status === "running") return "Starting sandbox";
+    if (item.origin === "resumed") return "Sandbox reattached";
+    if (item.origin === "restored") return "Sandbox restored";
+    if (item.origin === "created") return "Sandbox created";
+    return "Sandbox ready";
+  }
+  return toolDisplayName(item.name);
+}
+
 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)}
+      iconTone={
+        item.status === "failed" ? "failed" : item.status === "running" ? "running" : "muted"
+      }
+      title={sandboxRowTitle(item)}
       running={item.status === "running"}
       failed={item.status === "failed"}
       cancelled={item.status === "cancelled"}
@@ -135,7 +276,13 @@ function SandboxRow({ item }: { item: SandboxItem }) {
 }
 
 /** Spawned/messaged worker sessions get a first-class card, not a tool row. */
-function WorkerRow({ item, onOpenSession }: { item: WorkerItem; onOpenSession?: ((sessionId: string) => void) | undefined }) {
+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";
@@ -148,47 +295,49 @@ function WorkerRow({ item, onOpenSession }: { item: WorkerItem; onOpenSession?:
           : cancelled
             ? "Worker interrupted"
             : "Worker spawned"
-      : item.action === "interrupt"
-        ? (() => {
-            const verb = item.mode === "steer" ? "Steering" : "Stopping";
-            const done = item.mode === "steer" ? "Worker steered" : "Worker stopped";
-            return running ? `${verb} worker` : failed ? "Worker interrupt failed" : cancelled ? "Worker interrupted" : done;
-          })()
-        : 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" />
+      : running
+        ? "Messaging worker"
+        : failed
+          ? "Worker message failed"
+          : cancelled
+            ? "Worker interrupted"
+            : "Worker messaged";
+  // A worker is a first-class actor but still a STEP on the rail — a borderless
+  // row (no card), aligned to its sibling tool rows: the chevron column is an
+  // empty spacer (a worker doesn't expand), then the bot glyph, then the title
+  // with a quiet prompt beneath, and one right-gutter affordance.
+  //
+  // Once the worker's session id is known, the WHOLE row is a clean, clickable
+  // deep-link into that child session (a trailing arrow brightens on hover) —
+  // the spawn moment itself is the affordance, not a small side button. A
+  // still-in-flight spawn (no id yet) or a failed/cancelled worker is inert, so
+  // there is never a dead click target. The gutter mirrors the worker-completion
+  // card's calm language: red chip on failure, "interrupted" on cancel.
+  const sessionId = item.workerSessionId;
+  const deepLink = Boolean(sessionId) && Boolean(onOpenSession) && !failed && !cancelled;
+  const inner = (
+    <>
+      <span className="size-3.5 shrink-0" aria-hidden />
+      <span className={cn("mt-px shrink-0", failed ? "text-og-status-failed" : "text-og-accent")}>
+        <BotIcon className="size-3.5" />
       </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")}>
+        <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>
+        {item.prompt ? (
+          <p className="mt-0.5 truncate text-og-sm text-og-fg-muted">
+            {truncate(item.prompt, 140)}
+          </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" />
@@ -198,19 +347,29 @@ function WorkerRow({ item, onOpenSession }: { item: WorkerItem; onOpenSession?:
         <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 pointer-coarse:py-2",
-            "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>
+      ) : deepLink ? (
+        <ArrowRightIcon
+          aria-hidden
+          className="mt-0.5 size-3.5 shrink-0 text-og-fg-subtle transition-[transform,color] duration-150 group-hover/worker:translate-x-0.5 group-hover/worker:text-og-fg"
+        />
       ) : null}
-    </div>
+    </>
   );
+
+  if (deepLink && sessionId && onOpenSession) {
+    return (
+      <button
+        type="button"
+        onClick={() => onOpenSession(sessionId)}
+        className={cn(
+          "group/worker -mx-1.5 flex w-full items-start gap-2 rounded-og-sm px-1.5 py-1.5 text-left",
+          "outline-none transition-colors duration-150 hover:bg-og-surface-1 focus-visible:ring-2 focus-visible:ring-og-accent",
+          "pointer-coarse:py-2.5",
+        )}
+      >
+        {inner}
+      </button>
+    );
+  }
+  return <div className="flex items-start gap-2 px-1.5 py-1.5">{inner}</div>;
 }

package/src/timeline/disclosure-context.tsx

@@ -21,8 +21,18 @@ 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>;
+export function DisclosureDefaultsProvider({
+  defaultOpen,
+  children,
+}: {
+  defaultOpen: boolean;
+  children: ReactNode;
+}) {
+  return (
+    <DisclosureDefaultsContext.Provider value={defaultOpen}>
+      {children}
+    </DisclosureDefaultsContext.Provider>
+  );
 }
 
 /**

package/src/timeline/index.ts

@@ -16,13 +16,22 @@
    -------------------------------------------------------------------------- */
 
 // projection
-export { buildTimeline, extractSessionRef, groupTimeline, sessionStatusFromEvents, toolDisplayName } from "./projection";
+export {
+  buildTimeline,
+  creditExhaustedFromEvents,
+  extractSessionRef,
+  groupTimeline,
+  sessionStatusFromEvents,
+  toolDisplayName,
+} from "./projection";
 
 // item types
 export type {
   ActivityItem,
   AgentMessageItem,
+  AuthNeededItem,
   GoalItem,
+  MemoryItem,
   NoticeItem,
   ReasoningItem,
   SandboxItem,
@@ -32,6 +41,7 @@ export type {
   TurnEndItem,
   ToolCallItem,
   UserMessageItem,
+  WorkerCompletionItem,
   WorkerItem,
 } from "./types";
 
@@ -53,7 +63,16 @@ 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 {
+  ActivityDisclosure,
+  BodyNote,
+  MediaEmpty,
+  MediaSkeleton,
+  PayloadBlock,
+  ScreenshotFigure,
+  TermBlock,
+  Thumbnail,
+} from "./shared";
 export type { ActivityDisclosureProps, DisclosureChip } from "./shared";
 
 // screenshot lightbox

package/src/timeline/parsers.ts

@@ -29,7 +29,8 @@ export function sandboxCommandExitCode(out: unknown): number | 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 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;
@@ -53,7 +54,9 @@ export function stripExecBanner(out: unknown): string {
 
 /** 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 ?? ""));
+  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`). */
@@ -71,7 +74,10 @@ export function looksBinary(text: string): boolean {
  * `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)}`);
+  return String(printable).replace(
+    /[\u0000-\u001f]/g,
+    (c) => `^${String.fromCharCode(c.charCodeAt(0) + 64)}`,
+  );
 }
 
 /* --- V4A apply_patch diff -> GitFileDiff ------------------------------------ */
@@ -100,7 +106,13 @@ export type ApplyPatchOperation = {
  */
 export function v4aToGitFileDiff(op: ApplyPatchOperation): GitFileDiff {
   const status: GitFileDiff["status"] =
-    op.type === "create_file" ? "added" : op.type === "delete_file" ? "deleted" : op.moveTo ? "renamed" : "modified";
+    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;
 
@@ -150,7 +162,12 @@ export function v4aToGitFileDiff(op: ApplyPatchOperation): GitFileDiff {
           cur.oldLines += 1;
           deletions += 1;
         } else {
-          cur.lines.push({ type: "context", oldNo: oldNo++, newNo: newNo++, text: raw.replace(/^ /, "") });
+          cur.lines.push({
+            type: "context",
+            oldNo: oldNo++,
+            newNo: newNo++,
+            text: raw.replace(/^ /, ""),
+          });
           cur.oldLines += 1;
           cur.newLines += 1;
         }
@@ -163,7 +180,17 @@ export function v4aToGitFileDiff(op: ApplyPatchOperation): GitFileDiff {
     }
   }
 
-  return { path, oldPath, status, isBinary: false, isImage: false, additions, deletions, hunks, truncated: false };
+  return {
+    path,
+    oldPath,
+    status,
+    isBinary: false,
+    isImage: false,
+    additions,
+    deletions,
+    hunks,
+    truncated: false,
+  };
 }
 
 /**
@@ -186,7 +213,8 @@ export function applyPatchOps(raw: unknown): ApplyPatchOperation[] {
  * 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;
+  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";
 }
 
@@ -249,7 +277,10 @@ export function unwrapMcpOutput(output: unknown): { text: string; isError: boole
     }
     return { text: JSON.stringify(output), isError };
   }
-  return { text: typeof output === "string" ? output : output == null ? "" : JSON.stringify(output), isError: false };
+  return {
+    text: typeof output === "string" ? output : output == null ? "" : JSON.stringify(output),
+    isError: false,
+  };
 }
 
 /* --- computer-use screenshot extraction ------------------------------------- */
@@ -322,7 +353,8 @@ export function screenshotDataUrl(out: unknown): string | null {
 /** Serialize whatever a Uint8Array became in JSON (number[], {"0":n,…} index
  *  map, or Buffer-JSON {type:"Buffer",data:[…]}) back into base64. */
 function bytesToBase64(data: unknown): string | null {
-  const isByte = (n: unknown): n is number => typeof n === "number" && Number.isInteger(n) && n >= 0 && n <= 255;
+  const isByte = (n: unknown): n is number =>
+    typeof n === "number" && Number.isInteger(n) && n >= 0 && n <= 255;
   let bytes: number[] | null = null;
   if (Array.isArray(data) && data.every(isByte)) {
     bytes = data;
@@ -349,7 +381,9 @@ function bytesToBase64(data: unknown): string | null {
     for (let i = 0; i < bytes.length; i += CHUNK) {
       binary += String.fromCharCode(...bytes.slice(i, i + CHUNK));
     }
-    return typeof btoa === "function" ? btoa(binary) : Buffer.from(binary, "binary").toString("base64");
+    return typeof btoa === "function"
+      ? btoa(binary)
+      : Buffer.from(binary, "binary").toString("base64");
   } catch {
     // A hostile/absurd payload must degrade to "no image", never crash a render.
     return null;