@opengeni/react 0.6.2 → 0.8.0

package/src/hooks/use-session-events.ts

@@ -1,13 +1,16 @@
 import type { SessionEvent, SessionStatus, StreamConnectionState } from "@opengeni/sdk";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
-import { buildTimeline, sessionStatusFromEvents, type TimelineItem } from "../timeline";
+import { buildTimeline, groupTimeline, sessionStatusFromEvents, type TimelineItem } from "../timeline";
+import type { SessionClientLike } from "../client";
 
 export type SessionEventsConnectionState = StreamConnectionState | "idle" | "ended" | "error";
 
 export type UseSessionEventsOptions = ClientOverride & {
-  /** Resume after this sequence (exclusive). Defaults to 0 = full replay. */
+  /** Resume after this sequence (exclusive). Nonzero keeps full replay/resume semantics. */
   after?: number | undefined;
+  /** Load a bounded tail by default, or opt back into full replay from `after`. */
+  replay?: "windowed" | "full" | undefined;
   /** Pause the stream without unmounting (e.g. hidden tab). Defaults to true. */
   enabled?: boolean | undefined;
 };
@@ -22,34 +25,61 @@ export type UseSessionEventsResult = {
   connectionState: SessionEventsConnectionState;
   /** Highest sequence seen so far (0 before the first event). */
   lastSequence: number;
+  /** Whether older durable events are available before the current window. */
+  hasOlder: boolean;
+  /** True while an older window is being fetched. */
+  loadingOlder: boolean;
+  /** Prepend an older density-bounded window; resolves true when more remain. */
+  loadOlder: () => Promise<boolean>;
   error: Error | null;
 };
 
+const TAIL_PAGE_SIZE = 5000;
+const INITIAL_GROUP_TARGET = 48;
+const INITIAL_FETCH_CAP = 3;
+const OLDER_GROUP_TARGET = 32;
+const OLDER_FETCH_CAP = 2;
+const BOUNDARY_PAGE_CAP = 4;
+
 /**
  * Live-stream a session's event log with replay-by-sequence, reconnect, and
- * batched React updates. The SDK guarantees ordered, gap-free, exactly-once
- * delivery; this hook accumulates the log and projects it into a timeline.
+ * batched React updates. Fresh loads default to a bounded tail window; pass
+ * `replay: "full"` or a nonzero `after` for the previous full replay path.
  */
 export function useSessionEvents(sessionId: string | null | undefined, options: UseSessionEventsOptions = {}): UseSessionEventsResult {
   const { client, workspaceId } = useOpenGeni(options);
   const enabled = options.enabled ?? true;
   const after = options.after ?? 0;
+  const replay = options.replay ?? "windowed";
+  const fullReplay = replay === "full" || after !== 0;
 
   const [events, setEvents] = useState<SessionEvent[]>([]);
   const [connectionState, setConnectionState] = useState<SessionEventsConnectionState>("idle");
   const [error, setError] = useState<Error | null>(null);
+  const [hasOlder, setHasOlder] = useState(false);
+  const [loadingOlder, setLoadingOlder] = useState(false);
   const lastSequenceRef = useRef(after);
+  const oldestSequenceRef = useRef<number | null>(null);
+  const hasOlderRef = useRef(false);
+  const loadingOlderRef = useRef(false);
   const streamKeyRef = useRef<string | null>(null);
+  const generationRef = useRef(0);
 
   useEffect(() => {
     // Reset the accumulated log only when the stream identity changes —
     // pausing via `enabled: false` keeps the timeline visible.
-    const streamKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${after}`;
+    const streamKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${after}\u0000${fullReplay ? "full" : "windowed"}`;
     if (streamKeyRef.current !== streamKey) {
       streamKeyRef.current = streamKey;
+      generationRef.current += 1;
       setEvents([]);
       setError(null);
+      setHasOlder(false);
+      setLoadingOlder(false);
       lastSequenceRef.current = after;
+      oldestSequenceRef.current = null;
+      hasOlderRef.current = false;
+      loadingOlderRef.current = false;
     }
     if (!sessionId || !enabled) {
       setConnectionState("idle");
@@ -72,7 +102,7 @@ export function useSessionEvents(sessionId: string | null | undefined, options:
       // the next connect instead of being skipped.
       const lastInBatch = batch[batch.length - 1];
       if (lastInBatch) {
-        lastSequenceRef.current = lastInBatch.sequence;
+        lastSequenceRef.current = Math.max(lastSequenceRef.current, ...batch.map(eventResumeSequence));
       }
       setEvents((existing) => [...existing, ...batch]);
     };
@@ -82,6 +112,24 @@ export function useSessionEvents(sessionId: string | null | undefined, options:
 
     void (async () => {
       try {
+        if (!fullReplay) {
+          setConnectionState("connecting");
+          const window = await loadEventWindow(client, workspaceId, sessionId, {
+            before: Number.MAX_SAFE_INTEGER,
+            pageSize: TAIL_PAGE_SIZE,
+            targetGroups: INITIAL_GROUP_TARGET,
+            maxFetches: INITIAL_FETCH_CAP,
+            signal: controller.signal,
+          });
+          if (controller.signal.aborted) {
+            return;
+          }
+          oldestSequenceRef.current = window.oldestSequence;
+          hasOlderRef.current = window.hasOlder;
+          lastSequenceRef.current = window.newestSequence;
+          setHasOlder(window.hasOlder);
+          setEvents(window.events);
+        }
         const stream = client.streamEvents(workspaceId, sessionId, {
           after: lastSequenceRef.current,
           signal: controller.signal,
@@ -114,7 +162,52 @@ export function useSessionEvents(sessionId: string | null | undefined, options:
         clearTimeout(flushTimer);
       }
     };
-  }, [client, workspaceId, sessionId, after, enabled]);
+  }, [client, workspaceId, sessionId, after, enabled, fullReplay]);
+
+  const loadOlder = useCallback(async (): Promise<boolean> => {
+    if (!sessionId || fullReplay || loadingOlderRef.current || !hasOlderRef.current) {
+      return false;
+    }
+    const before = oldestSequenceRef.current;
+    if (before === null) {
+      hasOlderRef.current = false;
+      setHasOlder(false);
+      return false;
+    }
+    const generation = generationRef.current;
+    loadingOlderRef.current = true;
+    setLoadingOlder(true);
+    try {
+      const window = await loadEventWindow(client, workspaceId, sessionId, {
+        before,
+        pageSize: TAIL_PAGE_SIZE,
+        targetGroups: OLDER_GROUP_TARGET,
+        maxFetches: OLDER_FETCH_CAP,
+      });
+      if (generationRef.current !== generation) {
+        return false;
+      }
+      if (window.events.length === 0) {
+        oldestSequenceRef.current = null;
+        hasOlderRef.current = false;
+        setHasOlder(false);
+        return false;
+      }
+      oldestSequenceRef.current = window.oldestSequence;
+      hasOlderRef.current = window.hasOlder;
+      setHasOlder(window.hasOlder);
+      setEvents((existing) => {
+        assertPrependOrder(existing, window.events);
+        return [...window.events, ...existing];
+      });
+      return window.hasOlder;
+    } finally {
+      if (generationRef.current === generation) {
+        loadingOlderRef.current = false;
+        setLoadingOlder(false);
+      }
+    }
+  }, [client, workspaceId, sessionId, fullReplay]);
 
   const timeline = useMemo(() => buildTimeline(events), [events]);
   const sessionStatus = useMemo(() => sessionStatusFromEvents(events), [events]);
@@ -125,6 +218,188 @@ export function useSessionEvents(sessionId: string | null | undefined, options:
     sessionStatus,
     connectionState,
     lastSequence: lastSequenceRef.current,
+    hasOlder: fullReplay ? false : hasOlder,
+    loadingOlder: fullReplay ? false : loadingOlder,
+    loadOlder,
     error,
   };
 }
+
+type LoadedEventWindow = {
+  events: SessionEvent[];
+  oldestSequence: number | null;
+  newestSequence: number;
+  hasOlder: boolean;
+};
+
+async function loadEventWindow(
+  client: SessionClientLike,
+  workspaceId: string,
+  sessionId: string,
+  options: {
+    before: number;
+    pageSize: number;
+    targetGroups: number;
+    maxFetches: number;
+    signal?: AbortSignal;
+  },
+): Promise<LoadedEventWindow> {
+  let cursor = options.before;
+  let buffer: SessionEvent[] = [];
+  let reachedStart = false;
+  let fetches = 0;
+
+  while (fetches < options.maxFetches) {
+    if (buffer.length > 0 && groupCount(buffer) >= options.targetGroups) {
+      break;
+    }
+    const page = await loadPreviousPage(client, workspaceId, sessionId, cursor, {
+      pageSize: options.pageSize,
+      ...(options.signal ? { signal: options.signal } : {}),
+    });
+    fetches += 1;
+    if (page.length === 0) {
+      reachedStart = true;
+      break;
+    }
+    assertAscending(page);
+    buffer = [...page, ...buffer];
+    cursor = page[0]!.sequence;
+    if (isLogStart(page[0]!)) {
+      reachedStart = true;
+      break;
+    }
+  }
+
+  // Boundary snap: a window that starts mid-turn TRIMS its head to the oldest
+  // turn boundary already in the buffer — the dropped fragment is refetched by
+  // the next loadOlder (everything below the new oldest sequence), whose own
+  // window snaps the same way, so every seam lands on a turn start. Extra
+  // pages are fetched only when the buffer holds no boundary at all (one
+  // monster turn); past the cap a mid-turn top is accepted.
+  let snapPages = 0;
+  while (!reachedStart && findBoundaryIndex(buffer) === -1 && snapPages < BOUNDARY_PAGE_CAP && fetches < options.maxFetches) {
+    const page = await loadPreviousPage(client, workspaceId, sessionId, cursor, {
+      pageSize: options.pageSize,
+      ...(options.signal ? { signal: options.signal } : {}),
+    });
+    fetches += 1;
+    snapPages += 1;
+    if (page.length === 0) {
+      reachedStart = true;
+      break;
+    }
+    assertAscending(page);
+    buffer = [...page, ...buffer];
+    cursor = page[0]!.sequence;
+    if (isLogStart(page[0]!)) {
+      reachedStart = true;
+      break;
+    }
+  }
+  if (!reachedStart) {
+    const boundary = findBoundaryIndex(buffer);
+    if (boundary > 0) {
+      buffer = buffer.slice(boundary);
+    }
+  }
+
+  const oldest = buffer[0] ?? null;
+  const newest = buffer[buffer.length - 1] ?? null;
+  return {
+    events: buffer,
+    oldestSequence: oldest?.sequence ?? null,
+    newestSequence: newest ? maxResumeSequence(buffer) : 0,
+    hasOlder: buffer.length > 0 && !reachedStart && oldest?.type !== "session.created",
+  };
+}
+
+/** Index of the oldest clean turn start in the buffer, or -1. */
+function findBoundaryIndex(events: SessionEvent[]): number {
+  for (let index = 0; index < events.length; index += 1) {
+    const type = events[index]!.type;
+    if (type === "session.created" || type === "user.message") {
+      return index;
+    }
+  }
+  return -1;
+}
+
+type PreviousPage = SessionEvent[] & { requested: number };
+
+async function loadPreviousPage(
+  client: SessionClientLike,
+  workspaceId: string,
+  sessionId: string,
+  before: number,
+  options: {
+    pageSize: number;
+    signal?: AbortSignal;
+  },
+): Promise<PreviousPage> {
+  if (options.signal?.aborted) {
+    throw abortError();
+  }
+  const requested = options.pageSize;
+  if (requested === 0) {
+    return Object.assign([], { requested });
+  }
+  const page = await client.listEvents(workspaceId, sessionId, { before, limit: requested, compact: true });
+  if (options.signal?.aborted) {
+    throw abortError();
+  }
+  return Object.assign(page, { requested });
+}
+
+function groupCount(events: SessionEvent[]): number {
+  if (events.length === 0) {
+    return 0;
+  }
+  return groupTimeline(buildTimeline(events)).length;
+}
+
+function isLogStart(event: SessionEvent): boolean {
+  return event.type === "session.created" || event.sequence <= 1;
+}
+
+function maxResumeSequence(events: SessionEvent[]): number {
+  return events.reduce((max, event) => Math.max(max, eventResumeSequence(event)), 0);
+}
+
+function eventResumeSequence(event: SessionEvent): number {
+  const payload = asRecord(event.payload);
+  const coalescedUntil = Number(payload.coalescedUntil);
+  return Math.max(event.sequence, Number.isFinite(coalescedUntil) ? Math.floor(coalescedUntil) : 0);
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" ? value as Record<string, unknown> : {};
+}
+
+function assertAscending(events: SessionEvent[]): void {
+  for (let index = 1; index < events.length; index += 1) {
+    if (events[index - 1]!.sequence >= events[index]!.sequence) {
+      throw new Error("@opengeni/react: session events must be ordered by ascending sequence");
+    }
+  }
+}
+
+function assertPrependOrder(existing: SessionEvent[], older: SessionEvent[]): void {
+  if (!shouldAssertDevelopment() || existing.length === 0 || older.length === 0) {
+    return;
+  }
+  if (older[older.length - 1]!.sequence >= existing[0]!.sequence) {
+    throw new Error("@opengeni/react: loadOlder returned overlapping session events");
+  }
+}
+
+function shouldAssertDevelopment(): boolean {
+  const processEnv = (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process?.env;
+  return processEnv !== undefined && processEnv.NODE_ENV !== "production";
+}
+
+function abortError(): Error {
+  const error = new Error("The operation was aborted.");
+  error.name = "AbortError";
+  return error;
+}

package/src/index.ts

@@ -13,7 +13,7 @@ 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";
-export { useComposer, composeSendInput, shouldSubmitOnKey } from "./hooks/use-composer";
+export { useComposer, composeSendInput, shouldSubmitOnKey, FILE_ONLY_MESSAGE_TEXT } from "./hooks/use-composer";
 export type { ComposerMode, ComposerSendExtras, ComposerState, UseComposerOptions } from "./hooks/use-composer";
 export { useFileAttachments } from "./hooks/use-file-attachments";
 export type { FileAttachment, UseFileAttachmentsOptions, UseFileAttachmentsResult } from "./hooks/use-file-attachments";
@@ -242,4 +242,4 @@ export { xtermThemeFromTokens } from "./lib/xterm-theme";
 
 // Utilities
 export { cn } from "./lib/cn";
-export { formatBytes, formatRelativeTime, stringifyPayload, truncate, tryParseJson } from "./lib/format";
+export { formatBytes, formatRelativeTime, humanizeFailureReason, stringifyPayload, truncate, tryParseJson } from "./lib/format";

package/src/lib/format.ts

@@ -82,3 +82,35 @@ export function tryParseJson(text: string): unknown {
     return undefined;
   }
 }
+
+/**
+ * Humanize engine/provider failure text before it reaches the timeline or a
+ * failure banner. Raw provider errors leak the wrong audience's instructions —
+ * "Incorrect API key … find your API key at platform.openai.com" tells a
+ * managed-deployment USER to fix credentials only an OPERATOR controls (and is
+ * flatly wrong for Azure or subscription-backed engines). Auth and quota
+ * failures collapse to one neutral, honest sentence; every other reason passes
+ * through untouched. Raw payloads stay available in the debug surfaces.
+ */
+export function humanizeFailureReason(reason: string | null): string | null {
+  if (!reason) {
+    return reason;
+  }
+  const normalized = reason.toLowerCase();
+  const authFailure =
+    normalized.includes("incorrect api key") ||
+    normalized.includes("invalid api key") ||
+    normalized.includes("invalid_api_key") ||
+    normalized.includes("platform.openai.com/account/api-keys") ||
+    (normalized.includes("401") && (normalized.includes("api key") || normalized.includes("unauthorized")));
+  if (authFailure) {
+    return "The model provider rejected this deployment's engine credentials. Sending messages won't help until the deployment's engine configuration is fixed.";
+  }
+  const quotaFailure =
+    normalized.includes("insufficient_quota") ||
+    normalized.includes("exceeded your current quota");
+  if (quotaFailure) {
+    return "The model provider refused the request: this deployment's provider quota is exhausted.";
+  }
+  return reason;
+}

package/src/lib/xterm-theme.ts

@@ -1,8 +1,8 @@
 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
+ * Derive an xterm `ITheme` subset from the live OKLCH `--og-*` token system.
+ * 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.
  *
@@ -12,16 +12,13 @@ export function xtermThemeFromTokens(root?: HTMLElement | null): XtermTheme | un
   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 read = (name: string): string | undefined => {
+    const value = style.getPropertyValue(name).trim();
+    return value || 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 bg = read("--og-color-bg");
+  const fg = read("--og-color-fg");
+  const accent = read("--og-color-accent");
   const theme: XtermTheme = {};
   if (bg) theme.background = bg;
   if (fg) theme.foreground = fg;

package/src/timeline/activity-rail.tsx

@@ -2,6 +2,7 @@ import { BotIcon, 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 { toolDisplayName } from "./projection";
@@ -42,6 +43,7 @@ function familyOf(item: ActivityItem): string {
 }
 
 export function ActivityRail({ items, toolRegistry = defaultToolRegistry, onOpenSession, bare, className }: ActivityRailProps) {
+  const enter = useEntranceAnimation();
   return (
     <div
       className={cn(
@@ -49,7 +51,8 @@ export function ActivityRail({ items, toolRegistry = defaultToolRegistry, onOpen
         // 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",
+        !bare && "border-l-2 border-og-border pl-3 sm:pl-4",
+        !bare && enter && "animate-og-enter",
         className,
       )}
     >
@@ -200,7 +203,7 @@ function WorkerRow({ item, onOpenSession }: { item: WorkerItem; onOpenSession?:
           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",
+            "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",
           )}

package/src/timeline/entrance.tsx

@@ -0,0 +1,30 @@
+import { createContext, useContext, useRef } from "react";
+
+/* ----------------------------------------------------------------------------
+   Entrance animation gating
+
+   Bulk paints (the initial tail window, a prepended older window) must not run
+   per-row entrance animations — hundreds of rows fading in at once reads as a
+   full-timeline flash. Toggling `animation: none` on and off is NOT an option:
+   removing the override restarts every animation, which is itself the flash.
+
+   Instead each animated element decides ONCE, at its own mount, whether it was
+   born in a bulk paint — and keeps that decision forever. Rows born in a bulk
+   paint never animate; rows appended live animate exactly as before. Nothing
+   is ever toggled on existing DOM, so nothing can replay.
+   -------------------------------------------------------------------------- */
+
+const EntranceAnimationContext = createContext(true);
+
+export const EntranceAnimationProvider = EntranceAnimationContext.Provider;
+
+/**
+ * Whether this element should wear the entrance animation. Captured at mount
+ * from the nearest provider (true outside any provider) and stable for the
+ * element's lifetime — see the module doctrine above.
+ */
+export function useEntranceAnimation(): boolean {
+  const enabled = useContext(EntranceAnimationContext);
+  const captured = useRef(enabled);
+  return captured.current;
+}

package/src/timeline/parsers.ts

@@ -251,3 +251,107 @@ export function unwrapMcpOutput(output: unknown): { text: string; isError: boole
   }
   return { text: typeof output === "string" ? output : output == null ? "" : JSON.stringify(output), isError: false };
 }
+
+/* --- computer-use screenshot extraction ------------------------------------- */
+
+/**
+ * Extract a renderable `data:` URL from a computer-use screenshot output,
+ * whatever transport produced it. The hosted `computer_call` and the
+ * function-text mode persist a plain `data:image/...` string; the
+ * function-image mode (codex-backed sessions) persists the STRUCTURED image
+ * output — `{type:"image", image:{data, mediaType}}` with `data` arriving as a
+ * number array / index map / Buffer-JSON / base64 string after event
+ * serialization — or the agents-core normalized `input_image` content item.
+ * Returns null when the output carries no image (so callers fall back to their
+ * text/empty presentation).
+ */
+export function screenshotDataUrl(out: unknown): string | null {
+  if (typeof out === "string") {
+    if (out.startsWith("data:image")) {
+      return out;
+    }
+    // A JSON-encoded structured output (some transports stringify tool results).
+    if (out.startsWith("{") || out.startsWith("[")) {
+      const parsed = tryParseJson(out);
+      if (parsed !== undefined && parsed !== out) {
+        return screenshotDataUrl(parsed);
+      }
+    }
+    return null;
+  }
+  if (Array.isArray(out)) {
+    for (const entry of out) {
+      const url = screenshotDataUrl(entry);
+      if (url) {
+        return url;
+      }
+    }
+    return null;
+  }
+  if (out === null || typeof out !== "object") {
+    return null;
+  }
+  const record = out as Record<string, unknown>;
+  // agents-core normalized content item: {type:"input_image", image_url: "data:…" | {url}}
+  const imageUrl = record.image_url ?? record.imageUrl;
+  if (typeof imageUrl === "string" && imageUrl.startsWith("data:image")) {
+    return imageUrl;
+  }
+  if (imageUrl && typeof imageUrl === "object") {
+    const url = (imageUrl as Record<string, unknown>).url;
+    if (typeof url === "string" && url.startsWith("data:image")) {
+      return url;
+    }
+  }
+  // Structured tool output: {type:"image", image:{data, mediaType}}
+  const image = record.image as Record<string, unknown> | undefined;
+  if (image && typeof image === "object") {
+    const mediaType = typeof image.mediaType === "string" ? image.mediaType : "image/png";
+    const base64 = bytesToBase64(image.data);
+    if (base64) {
+      return `data:${mediaType};base64,${base64}`;
+    }
+    if (typeof image.data === "string" && image.data.length > 0) {
+      // Already base64 text.
+      return `data:${mediaType};base64,${image.data}`;
+    }
+  }
+  return 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;
+  let bytes: number[] | null = null;
+  if (Array.isArray(data) && data.every(isByte)) {
+    bytes = data;
+  } else if (data && typeof data === "object") {
+    const record = data as Record<string, unknown>;
+    if (record.type === "Buffer" && Array.isArray(record.data) && record.data.every(isByte)) {
+      bytes = record.data;
+    } else {
+      const keys = Object.keys(record);
+      if (keys.length > 0 && keys.every((key) => /^\d+$/.test(key))) {
+        const values = keys.sort((a, b) => Number(a) - Number(b)).map((key) => record[key]);
+        if (values.every(isByte)) {
+          bytes = values;
+        }
+      }
+    }
+  }
+  if (!bytes || bytes.length === 0) {
+    return null;
+  }
+  try {
+    let binary = "";
+    const CHUNK = 0x8000;
+    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");
+  } catch {
+    // A hostile/absurd payload must degrade to "no image", never crash a render.
+    return null;
+  }
+}

package/src/timeline/projection.ts

@@ -1,5 +1,5 @@
 import type { SessionEvent, SessionStatus } from "@opengeni/sdk";
-import { tryParseJson } from "../lib/format";
+import { humanizeFailureReason, tryParseJson } from "../lib/format";
 import type {
   AgentMessageItem,
   ActivityItem,
@@ -319,7 +319,11 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
       case "turn.failed": {
         const hadActivity = hasTurnActivity(items, turnId);
         const failureText = failureMessage(payload);
-        finalizeOpen(turnId, "failed");
+        // The TURN failed — the in-flight items did not. Chip doctrine: red is
+        // spent once, on the turn-level outcome. Items caught mid-flight read
+        // as calm "interrupted" (same as turn.cancelled); an item that itself
+        // failed keeps its own failed status from its output event.
+        finalizeOpen(turnId, "cancelled");
         items.push(turnEndItem(event, "failed", failureText));
         if (!hadActivity) {
           items.push({
@@ -613,8 +617,19 @@ function stampTurnOutcome(groups: TimelineGroup[], turnEnd: TurnEndItem): void {
 }
 
 function applyTurnOutcome(group: Extract<TimelineGroup, { kind: "activity" }>, turnEnd: TurnEndItem): void {
-  group.outcome = turnEnd.outcome;
-  if (turnEnd.failureText) {
+  // A sub-cluster reports ITS OWN outcome, not the turn's. When a turn fails
+  // at step 7, clusters 1–6 completed — painting them all red says "everything
+  // broke" when one thing did. The turn-level fold carries the turn outcome;
+  // a cluster goes red only if an item inside it actually failed, and reads
+  // "cancelled" (interrupted) only when it holds the items cut off mid-flight.
+  if (turnEnd.outcome === "complete") {
+    group.outcome = "complete";
+    return;
+  }
+  const hasFailed = group.items.some((item) => "status" in item && item.status === "failed");
+  const hasInterrupted = group.items.some((item) => "status" in item && item.status === "cancelled");
+  group.outcome = hasFailed ? "failed" : hasInterrupted ? "cancelled" : "complete";
+  if (turnEnd.failureText && hasFailed) {
     group.failureText = turnEnd.failureText;
   }
 }
@@ -775,7 +790,9 @@ function failureMessage(payload: Record<string, unknown>): string | null {
   for (const key of ["error", "message"] as const) {
     const value = payload[key];
     if (typeof value === "string" && value.trim().length > 0) {
-      return value;
+      // Auth/quota provider errors are rewritten for the right audience
+      // (raw text remains in the event payload for debug surfaces).
+      return humanizeFailureReason(value);
     }
   }
   return null;