@opengeni/react 3.1.0 → 3.1.2

package/src/timeline/genie-loading.tsx

@@ -0,0 +1,143 @@
+import { ThinkingOrb } from "thinking-orbs";
+import { useThemeType } from "../lib/use-theme-type";
+import { GENIE_PREPARING_PHRASES, GENIE_WAITING_PHRASES } from "./genie-copy";
+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);
+
+/**
+ * Neutral defaults for conversations embedded in another product
+ * (`SessionConversation`, `OpenGeniChat`), which should not carry Opengeni's
+ * own playful copy. The Opengeni app keeps the defaults above.
+ */
+export const EMBEDDED_GENIE_LOADING = {
+  phrases: ["Thinking…"],
+  messages: { showDetails: "Show details" },
+} as const satisfies GenieLoadingOptions;
+
+/** Decorative copy never substitutes for a failure or claims measurable progress. */
+export function GenieLoading({
+  startedAt,
+  phase = "preparing",
+  onShowDetails,
+  detailsOpen = false,
+  notice,
+}: {
+  startedAt: string;
+  phase?: GenieLoadingRenderProps["phase"];
+  onShowDetails: () => void;
+  detailsOpen?: boolean;
+  /** An actionable startup problem takes precedence over decorative copy. */
+  notice?: string | undefined;
+}) {
+  const options = useContext(GenieLoadingOptionsContext);
+  const waiting = phase === "waiting";
+  const phrases = options?.phrases?.length
+    ? options.phrases
+    : waiting
+      ? GENIE_WAITING_PHRASES
+      : GENIE_PREPARING_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) >= 30_000);
+      setSlow(Date.now() - Date.parse(startedAt) >= 60_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 && !notice)
+    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">
+          {notice ??
+            (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={notice ?? (slow ? "slow" : phrase)}
+          className="og-genie-phrase"
+          style={notice ? { animation: "none" } : undefined}
+          aria-hidden="true"
+        >
+          {notice ??
+            (slow
+              ? (options?.messages?.slowText ??
+                (waiting ? "Still waiting for a response…" : "A little longer than usual…"))
+              : phrases[phrase % phrases.length])}
+        </span>
+        {showDetails || detailsOpen || notice ? (
+          <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 {
@@ -41,7 +42,10 @@ export type {
   MachineInputBatchItem,
   MachineInputMember,
   MemoryItem,
+  MessageSender,
+  KnowledgeItem,
   NoticeItem,
+  SessionUsageLimitStop,
   ReasoningItem,
   SandboxItem,
   StartupPhase,
@@ -59,9 +63,20 @@ export type {
 
 // renderer registry
 export { createToolRegistry, rawTypeOf } from "./registry";
+export {
+  createSessionRetainedScreenshotLoader,
+  createWorkspaceRetainedArtifactLoader,
+  createWorkspaceRetainedVideoLoader,
+} from "./retained-loaders";
+export type {
+  RetainedArtifactLoaderClient,
+  RetainedScreenshotLoaderClient,
+  RetainedVideoLoaderClient,
+} from "./retained-loaders";
 export type {
   CreateToolRegistryOptions,
   RetainedArtifactLoader,
+  RetainedArtifactLoadOptions,
   RetainedScreenshotLoader,
   VideoArtifactPlaybackLoader,
   ToolRegistry,
@@ -91,8 +106,17 @@ export {
 export type { ActivityDisclosureProps, DisclosureChip } from "./shared";
 
 // screenshot lightbox
-export { LightboxProvider, useLightbox, useLightboxOptional } from "./screenshot-lightbox";
-export type { LightboxControlLabels } from "./screenshot-lightbox";
+export {
+  LightboxProvider,
+  useLightbox,
+  useLightboxGalleryItem,
+  useLightboxOptional,
+} from "./screenshot-lightbox";
+export type {
+  LightboxControlLabels,
+  LightboxGalleryEntry,
+  LightboxGalleryImage,
+} from "./screenshot-lightbox";
 
 // disclosure defaults (opt-in initial-open seed; for screenshot/test instrumentation)
 export { DisclosureDefaultsProvider, useForcedDefaultOpen } from "./disclosure-context";
@@ -118,6 +142,7 @@ export type {
   TurnSummaryFacetResult,
   TurnSummaryOptions,
   TurnSummaryProps,
+  TurnSummaryStatus,
 } from "./turn-summary";
 
 // parsers (pure, reusable by custom renderers)
@@ -139,3 +164,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/message-sender.tsx

@@ -0,0 +1,71 @@
+import { createContext, useContext, type ReactNode } from "react";
+
+import { cn } from "../lib/cn";
+import type { MessageSender, UserMessageItem } from "./types";
+
+/**
+ * Draws who sent a person's message. The host decides: return null for the
+ * viewer's own messages, or when it has no identity to show for a sender.
+ */
+export type RenderMessageSender = (sender: MessageSender, item: UserMessageItem) => ReactNode;
+
+export const MessageSenderContext = createContext<RenderMessageSender | undefined>(undefined);
+
+/** The sender line above a message bubble, when the host draws one. */
+export function MessageSenderSlot({ item }: { item: UserMessageItem }) {
+  const render = useContext(MessageSenderContext);
+  if (!render || !item.sender) return null;
+  const content = render(item.sender, item);
+  if (content === null || content === undefined || content === false) return null;
+  return <div className="flex max-w-full min-w-0 justify-end px-1">{content}</div>;
+}
+
+function initials(name: string): string {
+  const isEmail = name.includes("@");
+  const words = name
+    .replace(/@.*$/u, "")
+    .split(/[\s._-]+/u)
+    .filter(Boolean);
+  // "Kari Nordmann" → KN; "ola.normann.x@example.com" → ON.
+  const picked = words.length > 1 ? [words[0]!, isEmail ? words[1]! : words.at(-1)!] : words;
+  const letters = picked.map((word) => Array.from(word)[0] ?? "").join("");
+  return letters.toUpperCase() || "?";
+}
+
+/** A small avatar and a name, for {@link RenderMessageSender}. */
+export function MessageSenderLabel({
+  name,
+  avatarUrl,
+  className,
+}: {
+  name: string;
+  /** A same-origin or otherwise allowed image; initials are shown without one. */
+  avatarUrl?: string | null | undefined;
+  className?: string | undefined;
+}) {
+  return (
+    <span
+      className={cn(
+        "inline-flex max-w-full min-w-0 items-center gap-1.5 text-og-xs text-og-fg-muted",
+        className,
+      )}
+    >
+      {avatarUrl ? (
+        <img
+          src={avatarUrl}
+          alt=""
+          className="size-4 shrink-0 rounded-full object-cover"
+          referrerPolicy="no-referrer"
+        />
+      ) : (
+        <span
+          aria-hidden="true"
+          className="inline-flex size-4 shrink-0 items-center justify-center rounded-full bg-og-surface-2 text-[10px] leading-none font-semibold text-og-fg-muted"
+        >
+          {initials(name)}
+        </span>
+      )}
+      <span className="min-w-0 truncate font-medium">{name}</span>
+    </span>
+  );
+}

package/src/timeline/notice-presentation.ts

@@ -0,0 +1,48 @@
+import { formatClockTime } from "../lib/format";
+import { formatElapsed } from "./turn-summary-model";
+import type { NoticeItem } from "./types";
+import { durationBetween } from "./work-presentation";
+
+/** An approval notice the person has since answered. */
+export function noticeIsResolvedApproval(item: Pick<NoticeItem, "text" | "resolvedAt">): boolean {
+  return Boolean(item.resolvedAt && item.text.startsWith("Approval needed"));
+}
+
+/** A resolved approval notice reads as history. */
+export function noticeDisplayText(item: Pick<NoticeItem, "text" | "resolvedAt">): string {
+  return noticeIsResolvedApproval(item) ? "You responded to this approval." : item.text;
+}
+
+/** Notice pill tone: failures stay red, an open wait keeps the waiting hue. */
+export function noticeTone(
+  item: Pick<NoticeItem, "tone" | "resolvedAt">,
+): "failed" | "waiting" | "neutral" {
+  return item.tone === "failed"
+    ? "failed"
+    : item.tone === "waiting" && !item.resolvedAt
+      ? "waiting"
+      : "neutral";
+}
+
+/**
+ * Plain-text summary of a recorded agent wait, as web's quiet disclosure reads
+ * it: "Waited for 2 agents · 3m 5s" once later input ended the wait, otherwise
+ * "Waiting · since 10:32" (with the date on a later day).
+ */
+export function recordedWaitSummaryText(
+  item: Pick<NoticeItem, "occurredAt" | "waitingAgents" | "waitEndedAt">,
+  now: Date = new Date(),
+): string {
+  const agents = item.waitingAgents ?? 0;
+  const target = agents > 0 ? ` for ${agents} ${agents === 1 ? "agent" : "agents"}` : "";
+  const waitedMs = item.waitEndedAt
+    ? durationBetween(item.occurredAt, item.waitEndedAt)
+    : undefined;
+  if (waitedMs !== undefined) return `Waited${target} · ${formatElapsed(waitedMs)}`;
+  const started = new Date(item.occurredAt);
+  const since =
+    started.toDateString() === now.toDateString()
+      ? formatClockTime(item.occurredAt)
+      : started.toLocaleString(undefined, { dateStyle: "medium", timeStyle: "short" });
+  return `${item.waitEndedAt ? "Waited" : "Waiting"}${target} · since ${since}`;
+}

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 &&
@@ -584,6 +584,46 @@ export function generatedImageReceipt(out: unknown): GeneratedImageReceipt | nul
   return parseGeneratedImageReceipt(out);
 }
 
+/**
+ * Images a tool result returned that the platform retained, plus the result
+ * without them, so its text renders as usual. Any tool's result content can
+ * carry these receipts in place of its image blocks.
+ */
+export function retainedToolResultImages(out: unknown): {
+  images: Extract<RetainedArtifactMetadata, { available: true }>[];
+  output: unknown;
+} {
+  const parsed =
+    typeof out === "string" && (out.startsWith("{") || out.startsWith("["))
+      ? tryParseJson(out)
+      : out;
+  const split = (entries: unknown[]) => {
+    const images: Extract<RetainedArtifactMetadata, { available: true }>[] = [];
+    const rest = entries.filter((entry) => {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) return true;
+      const receipt = retainedScreenshotMetadata(entry);
+      if (!receipt?.available) return true;
+      images.push(receipt);
+      return false;
+    });
+    return { images, rest };
+  };
+  if (Array.isArray(parsed)) {
+    const { images, rest } = split(parsed);
+    return images.length ? { images, output: rest } : { images, output: out };
+  }
+  if (parsed && typeof parsed === "object") {
+    const record = parsed as Record<string, unknown>;
+    if (Array.isArray(record.content)) {
+      const { images, rest } = split(record.content);
+      return images.length
+        ? { images, output: { ...record, content: rest } }
+        : { images, output: out };
+    }
+  }
+  return { images: [], output: out };
+}
+
 export type TimelineMediaPreview = {
   type: "media_preview";
   mediaType: string;

package/src/timeline/patch-apply-command.tsx

@@ -0,0 +1,135 @@
+import type { RetainedArtifactReference } from "@opengeni/sdk";
+import { CheckIcon, TerminalIcon } from "lucide-react";
+import { useState } from "react";
+import { copyPendingTextToClipboard } from "../lib/clipboard";
+import type { RetainedArtifactLoader } from "./registry";
+
+export { isPatchFilename } from "./presented-image";
+
+/** POSIX single-quote one argument so the URL reaches curl unchanged. */
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+/** One command that downloads this patch and applies it in the current folder. */
+export function patchApplyCommand(url: string): string {
+  return `curl -fsSL ${shellQuote(url)} | git apply`;
+}
+
+/** "5 minutes" from the signed URL's expiry; the default download URL lifetime otherwise. */
+export function applyCommandLifetime(expiresAt: string | undefined, now = Date.now()): string {
+  const expires = expiresAt ? Date.parse(expiresAt) : Number.NaN;
+  const minutes = Number.isFinite(expires) ? Math.round((expires - now) / 60_000) : 5;
+  if (minutes <= 1) return "1 minute";
+  return `${minutes} minutes`;
+}
+
+type ApplyState =
+  | { kind: "idle" }
+  | { kind: "loading" }
+  | { kind: "copied"; lifetime: string }
+  | { kind: "manual"; command: string; lifetime: string }
+  | { kind: "unavailable" }
+  | { kind: "error" };
+
+const BUTTON_CLASS =
+  "inline-flex items-center gap-1.5 rounded-og-sm border border-og-border px-2.5 py-1.5 text-og-sm font-medium text-og-fg transition-colors hover:border-og-border-strong hover:bg-og-surface-2 disabled:cursor-wait disabled:opacity-60";
+
+/**
+ * "Copy command to apply these changes": mints the existing short-lived,
+ * authenticated download URL for this published patch (the same authority as
+ * Download) and copies `curl -fsSL '<url>' | git apply`. The URL is minted on
+ * click, so the copied command works for the URL's lifetime only.
+ */
+export function PatchApplyCommand({
+  artifact,
+  filename,
+  load,
+}: {
+  artifact: RetainedArtifactReference;
+  filename: string;
+  load: RetainedArtifactLoader | undefined;
+}) {
+  const [state, setState] = useState<ApplyState>({ kind: "idle" });
+
+  const copy = async () => {
+    if (!load) {
+      setState({ kind: "unavailable" });
+      return;
+    }
+    setState({ kind: "loading" });
+    let lifetime = "5 minutes";
+    // Start the URL request inside the click so the clipboard write may wait for it.
+    const command = load(artifact, new AbortController().signal, { prefer: "url" }).then(
+      (source) => {
+        if (!source || source instanceof Uint8Array) throw new UnavailableError();
+        lifetime = applyCommandLifetime(source.expiresAt);
+        return patchApplyCommand(source.url);
+      },
+    );
+    const copied = copyPendingTextToClipboard(command);
+    try {
+      const text = await command;
+      if (await copied) setState({ kind: "copied", lifetime });
+      else setState({ kind: "manual", command: text, lifetime });
+    } catch (failure) {
+      setState({ kind: failure instanceof UnavailableError ? "unavailable" : "error" });
+    }
+  };
+
+  const label =
+    state.kind === "loading"
+      ? "Preparing…"
+      : state.kind === "copied"
+        ? "Copied"
+        : state.kind === "error"
+          ? "Try again"
+          : "Copy command to apply these changes";
+
+  return (
+    <div className="flex min-w-0 flex-col gap-1.5">
+      <div>
+        <button
+          type="button"
+          onClick={() => void copy()}
+          disabled={state.kind === "loading"}
+          className={BUTTON_CLASS}
+        >
+          {state.kind === "copied" ? (
+            <CheckIcon className="size-3.5" aria-hidden />
+          ) : (
+            <TerminalIcon className="size-3.5" aria-hidden />
+          )}
+          {label}
+        </button>
+      </div>
+      <p className="m-0 text-og-xs leading-relaxed text-og-fg-muted" role="status">
+        {state.kind === "copied"
+          ? `Copied. Paste it in a terminal in your project folder and press Enter. The link in it expires in ${state.lifetime}.`
+          : state.kind === "manual"
+            ? `Copy this command, then run it in your project folder. The link in it expires in ${state.lifetime}.`
+            : state.kind === "unavailable"
+              ? `Download ${filename}, then run git apply ${filename} in your project folder.`
+              : state.kind === "error"
+                ? "Couldn't prepare the command. Try again, or download the file and run git apply."
+                : "Runs git apply in your project folder. Works on macOS, Linux and Git Bash."}
+      </p>
+      {state.kind === "manual" ? (
+        <input
+          readOnly
+          value={state.command}
+          aria-label="Command to apply these changes"
+          onFocus={(event) => event.currentTarget.select()}
+          className="w-full min-w-0 rounded-og-sm border border-og-border bg-og-surface-2 px-2 py-1.5 font-mono text-og-xs text-og-fg"
+        />
+      ) : null}
+    </div>
+  );
+}
+
+class UnavailableError extends Error {
+  constructor() {
+    super("A download URL is unavailable here");
+    this.name = "UnavailableError";
+  }
+}