@opengeni/react 1.0.1 → 1.0.2-canary.37191796234001

package/src/timeline/compaction-copy.ts

@@ -0,0 +1,42 @@
+import type { ContextCompactionItem } from "./types";
+
+/**
+ * Subtitle for a settled compaction landmark. A definitive provider rejection
+ * repeats deterministically for the same conversation, so it names the
+ * rejected field and withholds the generic retry promise; every other skip
+ * keeps its existing copy.
+ */
+export function compactionSkipSubtitle(
+  reason: string | null,
+  providerRejection: ContextCompactionItem["providerRejection"] = null,
+): string {
+  switch (reason) {
+    case "no_history":
+      return "No active history to compact";
+    case "replacement_not_smaller":
+      return "Checkpoint would not reduce memory size";
+    case "replacement_exceeds_model_budget":
+      return "Checkpoint exceeds this model's context budget. Chat history is unchanged.";
+    case "replacement_unchanged":
+      return "Checkpoint made no progress";
+    case "summarization_failed":
+      return providerRejection
+        ? `The model provider rejected the compaction request (${describeCompactionProviderRejection(providerRejection)}). Chat history is unchanged. Repeating it fails the same way until the conversation changes; if a new message fails again, start a new session.`
+        : "Request it again to retry. Chat history is unchanged.";
+    default:
+      return "Compaction was not needed. Chat history is unchanged.";
+  }
+}
+
+/** `HTTP 400 invalid_request_error, param input[3].encrypted_content`; identifiers only. */
+export function describeCompactionProviderRejection(
+  rejection: NonNullable<ContextCompactionItem["providerRejection"]>,
+): string {
+  const parts = [
+    `HTTP ${rejection.httpStatus}${rejection.type ? ` ${rejection.type}` : ""}${
+      rejection.code ? ` ${rejection.code}` : ""
+    }`,
+  ];
+  if (rejection.param) parts.push(`param ${rejection.param}`);
+  return parts.join(", ");
+}

package/src/timeline/entrance.tsx

@@ -1,4 +1,4 @@
-import { createContext, useContext, useRef } from "react";
+import { createContext, useContext, useRef, type ReactNode } from "react";
 
 /* ----------------------------------------------------------------------------
    Entrance animation gating
@@ -15,8 +15,33 @@ import { createContext, useContext, useRef } from "react";
    -------------------------------------------------------------------------- */
 
 const EntranceAnimationContext = createContext(true);
+const EntranceAnimationLiveContext = createContext(true);
 
-export const EntranceAnimationProvider = EntranceAnimationContext.Provider;
+/**
+ * Freeze the mount-time gate for this subtree while publishing a separate live
+ * gate to activity rails that need later appends to animate after a bulk paint.
+ * MessageTimeline mounts one provider per durable group, so existing groups do
+ * not receive a context invalidation when a prepend toggles bulk mode and new
+ * groups still capture the value from the commit that created them.
+ */
+export function EntranceAnimationProvider({
+  value,
+  liveValue = value,
+  children,
+}: {
+  value: boolean;
+  liveValue?: boolean | undefined;
+  children: ReactNode;
+}) {
+  const mountedValue = useRef(value).current;
+  return (
+    <EntranceAnimationContext.Provider value={mountedValue}>
+      <EntranceAnimationLiveContext.Provider value={liveValue}>
+        {children}
+      </EntranceAnimationLiveContext.Provider>
+    </EntranceAnimationContext.Provider>
+  );
+}
 
 /**
  * Live entrance gate from the nearest provider. Prefer
@@ -25,7 +50,7 @@ export const EntranceAnimationProvider = EntranceAnimationContext.Provider;
  * later appends after a bulk window clears.
  */
 export function useEntranceAnimationLive(): boolean {
-  return useContext(EntranceAnimationContext);
+  return useContext(EntranceAnimationLiveContext);
 }
 
 /**

package/src/timeline/fleet-decision-projection.ts

@@ -8,6 +8,7 @@ const FLEET_ACTUAL_REASONS = [
   "rotation",
   "active",
   "all_capped",
+  "allocator_disabled",
   "none",
 ] as const;
 const FLEET_SHADOW_OUTCOMES = ["selected", "paced", "none"] as const;
@@ -334,7 +335,7 @@ function fleetDecisionSemanticsAreConsistent(input: {
     input.actualOutcome === "selected"
       ? ["lease_reused", "pin", "rotation", "active"].includes(input.actualReason)
       : input.actualOutcome === "waiting"
-        ? input.actualReason === "all_capped"
+        ? ["all_capped", "allocator_disabled"].includes(input.actualReason)
         : input.actualReason === "none";
   const shadowConsistent =
     input.shadowOutcome === "selected"

package/src/timeline/fleet-decision-row.tsx

@@ -28,6 +28,7 @@ const FLEET_ACTUAL_REASON_LABEL: Record<FleetDecisionItem["actualReason"], strin
   rotation: "Rotated for capacity",
   active: "Used the active subscription",
   all_capped: "All observed subscriptions were capped",
+  allocator_disabled: "The policy-selected subscription was disabled for new allocations",
   none: "No production candidate was selected",
 };
 

package/src/timeline/genie-loading.tsx

@@ -0,0 +1,136 @@
+import { ThinkingOrb } from "thinking-orbs";
+import { useThemeType } from "../lib/use-theme-type";
+import { createContext, useContext, useEffect, useState, type ReactNode } from "react";
+
+export type GenieLoadingRenderProps = {
+  startedAt: string;
+  phase: "preparing" | "waiting";
+  detailsOpen: boolean;
+  onShowDetails: () => void;
+};
+
+export type GenieLoadingOptions = {
+  /** Replace the visual while preserving SDK loading visibility and transitions. */
+  render?: (props: GenieLoadingRenderProps) => ReactNode;
+  phrases?: readonly string[];
+  /** Native copy overrides. Omitted messages retain the default English copy. */
+  messages?: {
+    status?: string;
+    slowStatus?: string;
+    slowText?: string;
+    showDetails?: string;
+    hideDetails?: string;
+  };
+  /** Public adapter options; the renderer dependency's declarations stay private. */
+  orb?: {
+    state?:
+      | "working"
+      | "searching"
+      | "solving"
+      | "listening"
+      | "connecting"
+      | "weaving"
+      | "composing"
+      | "breathing"
+      | "shaping";
+    size?: 64 | 20;
+    speed?: number;
+  };
+};
+export const GenieLoadingOptionsContext = createContext<GenieLoadingOptions | undefined>(undefined);
+
+const PHRASES = [
+  "Polishing the lamp…",
+  "Consulting the carpet…",
+  "Untangling wishes…",
+  "Summoning a little cleverness…",
+  "Checking the fine print on infinity…",
+  "Warming up the abracadabra…",
+  "Rearranging the stars…",
+  "Negotiating with the lamp…",
+  "Dusting off a thousand years…",
+  "Wishful thinking…",
+  "Decanting a little magic…",
+  "Finding the good stardust…",
+  "Fluffing the magic carpet…",
+  "Putting a wish into motion…",
+  "A little hocus. A little pocus…",
+];
+const WAITING_PHRASES = ["Waiting for a response…"];
+
+/** Decorative copy never substitutes for a failure or claims measurable progress. */
+export function GenieLoading({
+  startedAt,
+  phase = "preparing",
+  onShowDetails,
+  detailsOpen = false,
+}: {
+  startedAt: string;
+  phase?: GenieLoadingRenderProps["phase"];
+  onShowDetails: () => void;
+  detailsOpen?: boolean;
+}) {
+  const options = useContext(GenieLoadingOptionsContext);
+  const waiting = phase === "waiting";
+  const phrases = options?.phrases?.length ? options.phrases : waiting ? WAITING_PHRASES : PHRASES;
+  const theme = useThemeType(undefined);
+  const [phrase, setPhrase] = useState(0);
+  const [showDetails, setShowDetails] = useState(false);
+  const [slow, setSlow] = useState(false);
+  useEffect(() => {
+    const update = () => {
+      setShowDetails(Date.now() - Date.parse(startedAt) >= 15_000);
+      setSlow(Date.now() - Date.parse(startedAt) >= 30_000);
+      if (!document.hidden) setPhrase(Math.floor(Math.random() * phrases.length));
+    };
+    update();
+    const timer = window.setInterval(update, 5_000);
+    return () => window.clearInterval(timer);
+  }, [startedAt, phrases]);
+  if (options?.render) return options.render({ startedAt, phase, detailsOpen, onShowDetails });
+  return (
+    <div className="og-genie-loading">
+      <div
+        className="og-genie-orb"
+        aria-hidden="true"
+        style={{
+          width: options?.orb?.size ?? 64,
+          height: options?.orb?.size ?? 64,
+          flexBasis: options?.orb?.size ?? 64,
+        }}
+      >
+        <ThinkingOrb state="searching" size={64} theme={theme} speed={0.8} {...options?.orb} />
+      </div>
+      <div className="og-genie-copy">
+        <span className="sr-only" role="status">
+          {slow
+            ? (options?.messages?.slowStatus ??
+              (waiting
+                ? "Waiting for a response. Taking longer than usual."
+                : "Preparing your task. Taking longer than usual."))
+            : (options?.messages?.status ??
+              (waiting ? "Waiting for a response." : "Preparing your task."))}
+        </span>
+        <span key={slow ? "slow" : phrase} className="og-genie-phrase" aria-hidden="true">
+          {slow
+            ? (options?.messages?.slowText ??
+              (waiting ? "Still waiting for a response…" : "A little longer than usual…"))
+            : phrases[phrase % phrases.length]}
+        </span>
+        {showDetails || detailsOpen ? (
+          <button
+            type="button"
+            className="og-genie-details"
+            aria-expanded={detailsOpen}
+            onClick={onShowDetails}
+          >
+            {detailsOpen
+              ? (options?.messages?.hideDetails ?? "Hide details")
+              : (options?.messages?.showDetails ?? (waiting ? "Show details" : "Behind the magic"))}
+            <span aria-hidden="true"> ↗</span>
+          </button>
+        ) : null}
+      </div>
+    </div>
+  );
+}

package/src/timeline/index.ts

@@ -26,6 +26,7 @@ export {
   toolDisplayName,
   toolMatchesLeaf,
 } from "./projection";
+export type { GroupTimelineOptions } from "./projection";
 
 // item types
 export type {
@@ -36,12 +37,17 @@ export type {
   FleetDecisionItem,
   FleetDecisionScoreItem,
   GoalItem,
+  HumanInputAnswerSummary,
+  HumanInputItem,
   MachineInputBatchItem,
   MachineInputMember,
   MemoryItem,
+  KnowledgeItem,
   NoticeItem,
   ReasoningItem,
   SandboxItem,
+  StartupPhase,
+  StartupPhaseItem,
   SessionStatusItem,
   TimelineGroup,
   TimelineItem,
@@ -88,6 +94,7 @@ export type { ActivityDisclosureProps, DisclosureChip } from "./shared";
 
 // screenshot lightbox
 export { LightboxProvider, useLightbox, useLightboxOptional } from "./screenshot-lightbox";
+export type { LightboxControlLabels } from "./screenshot-lightbox";
 
 // disclosure defaults (opt-in initial-open seed; for screenshot/test instrumentation)
 export { DisclosureDefaultsProvider, useForcedDefaultOpen } from "./disclosure-context";
@@ -113,6 +120,7 @@ export type {
   TurnSummaryFacetResult,
   TurnSummaryOptions,
   TurnSummaryProps,
+  TurnSummaryStatus,
 } from "./turn-summary";
 
 // parsers (pure, reusable by custom renderers)
@@ -134,3 +142,6 @@ export {
   v4aToGitFileDiff,
 } from "./parsers";
 export type { ApplyPatchOperation } from "./parsers";
+
+export { KnowledgeActivityProvider } from "./knowledge-receipt";
+export type { KnowledgeActivityActions } from "./knowledge-receipt";

package/src/timeline/knowledge-receipt.tsx

@@ -0,0 +1,100 @@
+import { createContext, useContext, useState, type ReactNode } from "react";
+import { BrainCircuitIcon } from "lucide-react";
+import { ActivityDisclosure, BodyNote } from "./shared";
+
+export type KnowledgeActivityActions = {
+  onInspect?: ((entryId: string) => void) | undefined;
+  onRetryFile?: ((fileId: string) => Promise<boolean | void>) | undefined;
+  retryDisabled?: boolean | undefined;
+};
+const KnowledgeActions = createContext<KnowledgeActivityActions>({});
+export function KnowledgeActivityProvider({
+  children,
+  ...actions
+}: KnowledgeActivityActions & { children: ReactNode }) {
+  return <KnowledgeActions.Provider value={actions}>{children}</KnowledgeActions.Provider>;
+}
+
+/** A saved/pending result never opens or blocks the human-input surface. */
+export function KnowledgeReceiptRow(props: {
+  outcome: "published" | "pending" | "rejected" | "archived" | "failed";
+  entryId?: string | undefined;
+  fileId?: string | undefined;
+  title?: string | undefined;
+  source?: boolean | undefined;
+}) {
+  const actions = useContext(KnowledgeActions);
+  const [retrying, setRetrying] = useState(false);
+  const [retrySent, setRetrySent] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const label =
+    props.outcome === "pending"
+      ? "Knowledge saved for review"
+      : props.outcome === "failed"
+        ? "Source preparation failed"
+        : props.outcome === "rejected"
+          ? "Source remains rejected"
+          : props.outcome === "archived"
+            ? "Knowledge archived"
+            : props.source
+              ? "Source saved to Knowledge"
+              : "Saved to Knowledge";
+  const actionClass =
+    "rounded-og-sm px-1 py-0.5 text-og-sm text-og-fg-muted hover:text-og-fg focus-visible:outline-2 focus-visible:outline-og-accent disabled:opacity-50";
+  return (
+    <ActivityDisclosure
+      icon={<BrainCircuitIcon className="size-3.5" />}
+      iconTone="muted"
+      title={label}
+      preview={props.title}
+    >
+      {props.outcome === "pending" ? (
+        <BodyNote>
+          Saved in Needs review. This task continues; future tasks can use it after approval.
+        </BodyNote>
+      ) : null}
+      {props.outcome === "failed" ? (
+        <BodyNote>
+          The original file remains attached. Searchable text has not been retained.
+        </BodyNote>
+      ) : null}
+      {props.outcome === "rejected" ? (
+        <BodyNote>Processing the file again leaves the review decision unchanged.</BodyNote>
+      ) : null}
+      {props.entryId && actions.onInspect ? (
+        <button
+          className={actionClass}
+          type="button"
+          onClick={() => actions.onInspect?.(props.entryId!)}
+        >
+          {props.outcome === "pending" ? "Review in Knowledge" : "View in Knowledge"}
+        </button>
+      ) : null}
+      {props.outcome === "failed" && props.fileId && actions.onRetryFile ? (
+        <button
+          className={actionClass}
+          type="button"
+          disabled={retrying || retrySent || actions.retryDisabled}
+          onClick={() => {
+            setRetrying(true);
+            setError(null);
+            void actions.onRetryFile!(props.fileId!)
+              .then((sent) => {
+                if (sent !== false) setRetrySent(true);
+                else setError("Could not start the retry. Try again when the chat is ready.");
+              })
+              .catch(() => setError("Could not start the retry. Please try again."))
+              .finally(() => setRetrying(false));
+          }}
+        >
+          {retrying ? "Starting retry…" : retrySent ? "Retry requested" : "Retry preparation"}
+        </button>
+      ) : null}
+      {error ? (
+        <p role="alert" className="text-og-sm">
+          {error}
+        </p>
+      ) : null}
+    </ActivityDisclosure>
+  );
+}

package/src/timeline/parsers.ts

@@ -566,8 +566,8 @@ export function retainedScreenshotMetadata(out: unknown): RetainedArtifactMetada
   if (!value.available) {
     return typeof value.reason === "string" ? (value as unknown as RetainedArtifactMetadata) : null;
   }
-  return value.kind === "computer_screenshot" &&
-    value.contentType === "image/png" &&
+  return (value.kind === "computer_screenshot" || value.kind === "browser_screenshot") &&
+    ["image/png", "image/jpeg", "image/webp"].includes(String(value.contentType)) &&
     typeof value.originalBytes === "number" &&
     typeof value.sha256 === "string" &&
     value.dimensions !== null &&

package/src/timeline/platform-activity-row.tsx

@@ -0,0 +1,216 @@
+import type { ReasoningItem, SandboxItem, StartupPhaseItem } from "./types";
+
+type RowJsx = typeof import("react/jsx-runtime").jsx;
+type RowJsxs = typeof import("react/jsx-runtime").jsxs;
+
+export default function PlatformActivityRow({
+  item,
+  d: ActivityDisclosure,
+  p: PayloadBlock,
+  t: displayName,
+  b: BotIcon,
+  m: Markdown,
+  j,
+  s,
+}: {
+  item: ReasoningItem | SandboxItem | StartupPhaseItem;
+  d: typeof import("./shared").ActivityDisclosure;
+  p: typeof import("./shared").PayloadBlock;
+  t: (name: string) => string;
+  b: typeof import("lucide-react").BotIcon;
+  m: typeof import("../components/markdown").Markdown;
+  j: RowJsx;
+  s: RowJsxs;
+}) {
+  if (item.kind === "reasoning") {
+    return j(ActivityDisclosure, {
+      icon: brainIcon(j, s),
+      iconTone: "muted",
+      title: item.streaming
+        ? "Thinking"
+        : j("span", {
+            className: "font-normal italic text-og-fg-subtle",
+            children: "Thought",
+          }),
+      running: item.streaming,
+      compactPreview: item.text.replace(/\*\*|__|`/g, "").replace(/\s+/g, " "),
+      preview: j("span", {
+        className: "og-reasoning-preview",
+        children: j(Markdown, { streaming: item.streaming, children: item.text }),
+      }),
+      children: j("div", {
+        className: "text-og-base leading-6 text-og-fg-muted [&_strong]:text-og-fg-muted",
+        children: j(Markdown, { streaming: item.streaming, children: item.text }),
+      }),
+    });
+  }
+  if (item.kind === "sandbox") {
+    return s(ActivityDisclosure, {
+      icon: terminalIcon(j, s),
+      iconTone:
+        item.status === "failed" ? "failed" : item.status === "running" ? "running" : "muted",
+      title: sandboxRowTitle(item, displayName),
+      running: item.status === "running",
+      failed: item.status === "failed",
+      cancelled: item.status === "cancelled",
+      preview: item.command ?? undefined,
+      children: [
+        item.command ? j(PayloadBlock, { label: "Command", value: item.command }, "command") : null,
+        item.output ? j(PayloadBlock, { label: "Output", value: item.output }, "output") : null,
+      ],
+    });
+  }
+
+  const failed = item.status === "failed";
+  const running = item.status === "running";
+  const duration = startupDuration(item.durationMs);
+  return j(ActivityDisclosure, {
+    icon: j(BotIcon, { className: "size-3.5" }),
+    iconTone: failed ? "failed" : running ? "running" : "muted",
+    title: item.blockedReason
+      ? STARTUP_WAIT_TITLES[item.blockedReason]
+      : startupPhaseTitle(item.phase, item.status, item.outcome),
+    preview:
+      item.phase === "model_preparation"
+        ? "Includes overlapping sandbox startup, custom environment setup, repository preparation, and runtime setup shown below."
+        : undefined,
+    running,
+    failed,
+    cancelled: item.status === "cancelled",
+    chip: duration ? { tone: failed ? "bad" : "muted", text: duration } : undefined,
+    expandable: false,
+  });
+}
+
+function brainIcon(j: RowJsx, s: RowJsxs) {
+  return lucideIcon(j, s, "brain", [
+    j("path", { d: "M 12 18V5" }, "spine"),
+    j("path", { d: "M15 13a4.17 4.17 0 0 1-3-4 4.17 4.17 0 0 1-3 4" }, "center"),
+    j("path", { d: "M17.598 6.5A3 3 0 1 0 12 5a3 3 0 1 0-5.598 1.5" }, "top"),
+    j("path", { d: "M17.997 5.125a4 4 0 0 1 2.526 5.77" }, "upper-right"),
+    j("path", { d: "M18 18a4 4 0 0 0 2-7.464" }, "right"),
+    j("path", { d: "M19.967 17.483A4 4 0 1 1 12 18a4 4 0 1 1-7.967-.517" }, "base"),
+    j("path", { d: "M6 18a4 4 0 0 1-2-7.464" }, "left"),
+    j("path", { d: "M6.003 5.125a4 4 0 0 0-2.526 5.77" }, "upper-left"),
+  ]);
+}
+
+function terminalIcon(j: RowJsx, s: RowJsxs) {
+  return lucideIcon(j, s, "square-terminal", [
+    j("path", { d: "m7 11 2-2-2-2" }, "prompt"),
+    j("path", { d: "M11 13h4" }, "cursor"),
+    j("rect", { width: 18, height: 18, x: 3, y: 3, rx: 2, ry: 2 }, "frame"),
+  ]);
+}
+
+function lucideIcon(j: RowJsx, s: RowJsxs, name: string, children: ReturnType<RowJsx>[]) {
+  return s("svg", {
+    "aria-hidden": "true",
+    className: `lucide lucide-${name} size-3.5`,
+    fill: "none",
+    height: 24,
+    stroke: "currentColor",
+    strokeLinecap: "round",
+    strokeLinejoin: "round",
+    strokeWidth: 2,
+    viewBox: "0 0 24 24",
+    width: 24,
+    children,
+  });
+}
+
+function sandboxRowTitle(item: SandboxItem, displayName: (name: string) => string): string {
+  if (item.name === "sandbox.provision") {
+    return startupPhaseTitle(
+      "sandbox",
+      item.status === "cancelled" ? "complete" : item.status,
+      item.origin ?? null,
+    );
+  }
+  return displayName(item.name);
+}
+
+function startupPhaseTitle(
+  phase: StartupPhaseItem["phase"],
+  status: StartupPhaseItem["status"],
+  outcome: StartupPhaseItem["outcome"],
+): string {
+  if (status === "complete" && phase === "sandbox" && outcome && outcome !== "skipped") {
+    return `Sandbox ${outcome === "resumed" ? "reattached" : outcome}`;
+  }
+  if (status === "complete" && phase === "rig" && outcome === "skipped") {
+    return "Sandbox Environment already ready";
+  }
+  const statusIndex =
+    status === "running" ? 0 : status === "failed" ? 1 : status === "cancelled" ? 2 : 3;
+  return STARTUP_PHASE_TITLES[phase][statusIndex];
+}
+
+const STARTUP_WAIT_TITLES: Record<NonNullable<StartupPhaseItem["blockedReason"]>, string> = {
+  capture_in_progress: "Waiting for sandbox checkpoint",
+  rotation_in_progress: "Waiting for sandbox rotation",
+  provider_recovery_in_progress: "Waiting for sandbox recovery",
+};
+
+const STARTUP_PHASE_TITLES: Record<
+  StartupPhaseItem["phase"],
+  readonly [string, string, string, string]
+> = {
+  queue: [
+    "Waiting for a worker",
+    "Worker startup failed",
+    "Worker wait interrupted",
+    "Worker started",
+  ],
+  sandbox: [
+    "Starting sandbox",
+    "Sandbox didn’t start",
+    "Sandbox startup interrupted",
+    "Sandbox ready",
+  ],
+  rig: [
+    "Setting up sandbox environment",
+    "Sandbox Environment setup failed",
+    "Sandbox Environment setup interrupted",
+    "Sandbox Environment ready",
+  ],
+  repository: [
+    "Preparing repository",
+    "Repository preparation failed",
+    "Repository preparation interrupted",
+    "Repository ready",
+  ],
+  files: [
+    "Preparing files",
+    "File preparation failed",
+    "File preparation interrupted",
+    "Files ready",
+  ],
+  tools: [
+    "Connecting tools",
+    "Tool connection failed",
+    "Tool connection interrupted",
+    "Tools ready",
+  ],
+  model_preparation: [
+    "Preparing runtime and model request",
+    "Runtime/model preparation failed",
+    "Runtime/model preparation interrupted",
+    "Model request dispatched",
+  ],
+  provider_first_byte: [
+    "Waiting for model",
+    "Model didn’t respond",
+    "Model wait interrupted",
+    "Model started responding",
+  ],
+};
+
+function startupDuration(durationMs: number | null): string | null {
+  if (durationMs === null || !Number.isFinite(durationMs) || durationMs < 0) return null;
+  if (durationMs < 1_000) return `${Math.round(durationMs)}ms`;
+  if (durationMs < 60_000) return `${(durationMs / 1_000).toFixed(1)}s`;
+  const minutes = Math.floor(durationMs / 60_000);
+  const seconds = Math.round((durationMs % 60_000) / 1_000);
+  return `${minutes}m ${String(seconds).padStart(2, "0")}s`;
+}

package/src/timeline/presented-image.ts

@@ -0,0 +1,49 @@
+import { normalizeMcpOutput, parseSandboxFileArtifactReceipt } from "@opengeni/sdk";
+import { mcpToolLeaf } from "./tool-display-name";
+import type { ActivityItem, TimelineGroup } from "./types";
+
+/*
+ * Pure presentation facts shared by the projection and the renderers. Kept
+ * free of React so the session-only entry can inspect primary output without pulling
+ * in rendering code.
+ */
+
+/** Shared browser preview allowlist; other published files remain downloads. */
+export function isRetainedImageContentType(contentType: string): boolean {
+  return [
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+    "image/avif",
+    "image/svg+xml",
+  ].includes(contentType);
+}
+
+/** Deliberately published images are primary output, not incidental screenshots. */
+export function activityPresentsImage(items: readonly ActivityItem[]): boolean {
+  return items.some((item) => {
+    if (item.kind !== "tool-call") return false;
+    const name = mcpToolLeaf(item.name);
+    if (name === "generate_image" || name === "image_generation_call") return true;
+    if (item.status !== "complete" || name !== "sandbox_file_publish") return false;
+    const output = normalizeMcpOutput(item.output);
+    if (output.isError) return false;
+    const receipt = parseSandboxFileArtifactReceipt(output.text);
+    return receipt !== null && isRetainedImageContentType(receipt.artifact.contentType);
+  });
+}
+
+export function timelineGroupContainsPresentedImage(group: TimelineGroup): boolean {
+  switch (group.kind) {
+    case "item":
+      return false;
+    case "activity":
+      return (
+        activityPresentsImage(group.items) ||
+        (group.work?.details?.some(timelineGroupContainsPresentedImage) ?? false)
+      );
+    case "turn":
+      return group.groups.some(timelineGroupContainsPresentedImage);
+  }
+}