@opengeni/react 3.1.0 → 3.1.2

package/src/timeline/provider-logo.tsx

@@ -0,0 +1,53 @@
+import { createContext, useContext, useEffect, useState, type ReactNode } from "react";
+
+import type { ToolDisplayMetadata } from "@opengeni/sdk";
+
+/*
+ * Connector logos in tool rows. The host resolves a provider domain to a logo
+ * it serves itself (the same `resolveProviderLogo` MessageTimeline already
+ * takes). Rows from a connector draw that logo in place of their generic icon;
+ * without one they keep it.
+ */
+
+export type ResolveProviderLogo = (providerDomain: string) => string | null | undefined;
+
+const ProviderLogoContext = createContext<ResolveProviderLogo | undefined>(undefined);
+
+export const ProviderLogoProvider = ProviderLogoContext.Provider;
+
+/** The logo URL for a tool's connector, when the host has one. */
+export function useToolConnectorLogo(display: ToolDisplayMetadata | undefined): string | null {
+  const resolve = useContext(ProviderLogoContext);
+  if (!resolve || !display?.providerDomain) return null;
+  return resolve(display.providerDomain) ?? null;
+}
+
+/**
+ * A connector's logo at icon size, or `fallback` when there is none or it
+ * fails to load, so a row never shows a broken image.
+ */
+export function ConnectorLogoIcon({
+  src,
+  fallback,
+  className,
+}: {
+  src: string | null;
+  fallback: ReactNode;
+  className?: string;
+}) {
+  const [failed, setFailed] = useState(false);
+  useEffect(() => setFailed(false), [src]);
+  if (!src || failed) return <>{fallback}</>;
+  return (
+    <img
+      src={src}
+      alt=""
+      aria-hidden="true"
+      loading="lazy"
+      decoding="async"
+      data-og-connector-logo=""
+      className={className ?? "size-3.5 shrink-0 rounded-[3px] object-contain"}
+      onError={() => setFailed(true)}
+    />
+  );
+}

package/src/timeline/question-nav-model.ts

@@ -0,0 +1,28 @@
+/**
+ * "Back to your message": which prompt the reader is reading the answer to, and
+ * whether that prompt has scrolled out of view. Renderer-neutral geometry so
+ * the web timeline (DOM rects) and native timelines (layout offsets) agree.
+ */
+
+/** How far above the viewport a prompt must be before the pill appears. */
+export const QUESTION_NAV_HIDDEN_PX = 24;
+/** Breathing room above the question when the reader jumps back to it. */
+export const QUESTION_NAV_MARGIN_PX = 12;
+
+export type QuestionNavPrompt = { key: string; top: number; bottom: number };
+
+/**
+ * The last prompt before the reading position (the viewport's middle) owns the
+ * response in view; it is a target only once it has scrolled fully above the
+ * viewport. Prompts are in document order; coordinates share one axis.
+ */
+export function questionNavTarget(
+  prompts: readonly QuestionNavPrompt[],
+  view: { top: number; height: number },
+): string | null {
+  const middle = view.top + view.height / 2;
+  const prompt = [...prompts].reverse().find((candidate) => candidate.top <= middle);
+  if (!prompt) return null;
+  if (prompt.top >= view.top - QUESTION_NAV_HIDDEN_PX || prompt.bottom > view.top) return null;
+  return prompt.key;
+}

package/src/timeline/registry.ts

@@ -13,7 +13,7 @@ import type { ToolCallItem } from "./types";
    Resolution order (most → least specific):
      1. exact match on `raw.type`        (e.g. "apply_patch_call", "computer_call")
      2. exact match on the tool `name`   (e.g. "exec_command", "web_search_call")
-     3. leaf match after MCP `__` prefix (e.g. opengeni__environment_set_variable)
+     3. allowed leaf match after MCP `__` prefix (e.g. opengeni__environment_set_variable)
      4. the registry's generic fallback
 
    A consumer extends the defaults without forking by passing overrides to
@@ -35,7 +35,17 @@ export type RetainedScreenshotLoader = (
 export type RetainedArtifactLoader = (
   artifact: RetainedArtifactReference,
   signal: AbortSignal,
-) => Promise<Uint8Array | { url: string } | null>;
+  options?: RetainedArtifactLoadOptions,
+) => Promise<Uint8Array | { url: string; expiresAt?: string | undefined } | null>;
+
+export type RetainedArtifactLoadOptions = {
+  /**
+   * Ask for a short-lived download URL instead of bytes, for example to build a
+   * copyable `curl … | git apply` command. A loader that cannot mint one may
+   * still return bytes; callers must handle that.
+   */
+  prefer?: "url" | undefined;
+};
 
 /** Mint an expiring source for native browser playback without loading video bytes in JS. */
 export type VideoArtifactPlaybackLoader = (
@@ -48,7 +58,13 @@ export type ToolRenderer = ComponentType<ToolRendererProps>;
 /** A registry entry: which key it matches and the component that renders it. */
 export type ToolRegistryEntry =
   | { match: "rawType"; type: string; render: ToolRenderer }
-  | { match: "name"; name: string; render: ToolRenderer };
+  | {
+      match: "name";
+      name: string;
+      render: ToolRenderer;
+      /** Disable untrusted `<server>__${name}` leaf matching for identity-sensitive renderers. */
+      matchPrefixedLeaf?: boolean | undefined;
+    };
 
 export type ToolRegistry = {
   /** Resolve the renderer for a call (never null — falls back to generic). */
@@ -92,6 +108,7 @@ export function createToolRegistry(
 
   const byRawType = new Map<string, ToolRenderer>();
   const byName = new Map<string, ToolRenderer>();
+  const byPrefixedLeaf = new Map<string, ToolRenderer>();
   for (const entry of entries) {
     if (entry.match === "rawType") {
       if (!byRawType.has(entry.type)) {
@@ -100,6 +117,11 @@ export function createToolRegistry(
     } else if (!byName.has(entry.name)) {
       byName.set(entry.name, entry.render);
     }
+    if (entry.match === "name" && entry.matchPrefixedLeaf !== false) {
+      if (!byPrefixedLeaf.has(entry.name)) {
+        byPrefixedLeaf.set(entry.name, entry.render);
+      }
+    }
   }
 
   const resolve = (item: ToolCallItem): ToolRenderer => {
@@ -116,7 +138,7 @@ export function createToolRegistry(
     }
     const leaf = mcpToolLeaf(item.name);
     if (leaf !== item.name) {
-      const byLeaf = byName.get(leaf);
+      const byLeaf = byPrefixedLeaf.get(leaf);
       if (byLeaf) {
         return byLeaf;
       }

package/src/timeline/retained-image.ts

@@ -0,0 +1,97 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { RetainedArtifactReference } from "@opengeni/sdk";
+import type { ToolRendererProps } from "./registry";
+type RetainedImageState =
+  | { kind: "loading" }
+  | { kind: "ready"; url: string }
+  | { kind: "unavailable"; label: string }
+  | { kind: "error"; message: string };
+
+export { isRetainedImageContentType } from "./presented-image";
+
+export function useRetainedImageObjectUrl(
+  artifact: RetainedArtifactReference,
+  load: ToolRendererProps["loadRetainedArtifact"],
+): RetainedImageState & { retry: () => void } {
+  const [state, setState] = useState<RetainedImageState>({ kind: "loading" });
+  const [retrievalAttempt, setRetrievalAttempt] = useState(0);
+  // Retry only the immutable retained artifact; never issue a new capture or
+  // rewrite the tool receipt/model history to repair a human preview.
+  const retry = useCallback(() => setRetrievalAttempt((attempt) => attempt + 1), []);
+  // Function outputs are commonly serialized JSON. Parsing them creates a new
+  // object on every render, so depend on the immutable wire value rather than
+  // object identity; otherwise the loader can refetch after its own setState.
+  const artifactValue = retainedArtifactValue(artifact);
+  const stableArtifactRef = useRef({ value: artifactValue, artifact });
+  if (stableArtifactRef.current.value !== artifactValue) {
+    stableArtifactRef.current = { value: artifactValue, artifact };
+  }
+  const stableArtifact = stableArtifactRef.current.artifact;
+  useEffect(() => {
+    if (!load) {
+      setState({ kind: "unavailable", label: "retrieval is not configured" });
+      return;
+    }
+    const controller = new AbortController();
+    let objectUrl: string | null = null;
+    setState({ kind: "loading" });
+    void load(stableArtifact, controller.signal)
+      .then((source) => {
+        if (controller.signal.aborted) return;
+        if (!source) {
+          setState({ kind: "unavailable", label: "bytes are unavailable" });
+          return;
+        }
+        if (!(source instanceof Uint8Array)) {
+          if (!source.url.trim()) {
+            setState({ kind: "unavailable", label: "URL is unavailable" });
+            return;
+          }
+          setState({ kind: "ready", url: source.url });
+          return;
+        }
+        objectUrl = URL.createObjectURL(
+          new Blob([source as unknown as BlobPart], { type: stableArtifact.contentType }),
+        );
+        setState({ kind: "ready", url: objectUrl });
+      })
+      .catch((error: unknown) => {
+        if (controller.signal.aborted) return;
+        const status =
+          error && typeof error === "object" && "status" in error
+            ? Number((error as { status?: unknown }).status)
+            : null;
+        setState(
+          status === 404
+            ? { kind: "unavailable", label: "deleted" }
+            : status === 410
+              ? { kind: "unavailable", label: "expired or unavailable" }
+              : { kind: "error", message: "retrieval failed" },
+        );
+      });
+    return () => {
+      controller.abort();
+      if (objectUrl) URL.revokeObjectURL(objectUrl);
+    };
+  }, [stableArtifact, load, retrievalAttempt]);
+  return { ...state, retry };
+}
+
+function retainedArtifactValue(artifact: RetainedArtifactReference): string {
+  return [
+    artifact.artifactId,
+    artifact.kind,
+    artifact.contentType,
+    artifact.originalBytes,
+    artifact.sha256,
+    artifact.retainedAt,
+    artifact.dimensions?.width ?? "",
+    artifact.dimensions?.height ?? "",
+    artifact.retention.policy,
+    artifact.retention.expiresAt ?? "",
+    artifact.retrieval.method,
+    artifact.retrieval.path,
+    artifact.retrieval.acceptRanges,
+    artifact.retrieval.maxRangeBytes,
+  ].join("\0");
+}

package/src/timeline/retained-loaders.ts

@@ -0,0 +1,91 @@
+import type { OpenGeniClient, RetainedArtifactReference } from "@opengeni/sdk";
+import type {
+  RetainedArtifactLoadOptions,
+  RetainedArtifactLoader,
+  RetainedScreenshotLoader,
+  VideoArtifactPlaybackLoader,
+} from "./registry";
+
+/** SDK methods the workspace retained-artifact loader needs. */
+export type RetainedArtifactLoaderClient = Pick<
+  OpenGeniClient,
+  "createRetainedArtifactDownloadUrl" | "downloadRetainedArtifact"
+>;
+
+/** SDK method the session retained-screenshot loader needs. */
+export type RetainedScreenshotLoaderClient = Pick<OpenGeniClient, "downloadRetainedScreenshot">;
+
+/** SDK method the generated-video playback loader needs. */
+export type RetainedVideoLoaderClient = Pick<OpenGeniClient, "createVideoArtifactPlaybackSource">;
+
+/**
+ * Bind permanent retained-artifact retrieval (generated images, published
+ * files) to one authenticated workspace, for `MessageTimeline`'s
+ * `loadRetainedArtifact`. Images get a short-lived URL; files are assembled
+ * from verified byte ranges unless the caller asks for a URL.
+ */
+export function createWorkspaceRetainedArtifactLoader(
+  client: RetainedArtifactLoaderClient,
+  workspaceId: string,
+): RetainedArtifactLoader {
+  return async (
+    artifact: RetainedArtifactReference,
+    signal: AbortSignal,
+    options?: RetainedArtifactLoadOptions,
+  ) => {
+    if (artifact.kind === "file" && options?.prefer !== "url") {
+      const download = await client.downloadRetainedArtifact(workspaceId, artifact, { signal });
+      return download.bytes;
+    }
+    const download = await client.createRetainedArtifactDownloadUrl(workspaceId, artifact, {
+      signal,
+    });
+    return { url: download.url, expiresAt: download.expiresAt };
+  };
+}
+
+/**
+ * Bind the authenticated screenshot downloader to one workspace and session,
+ * for `MessageTimeline`'s `loadRetainedScreenshot`. Fetched metadata must match
+ * the timeline receipt before bytes are handed to React; errors deliberately
+ * contain no storage locator or content.
+ */
+export function createSessionRetainedScreenshotLoader(
+  client: RetainedScreenshotLoaderClient,
+  workspaceId: string,
+  sessionId: string,
+): RetainedScreenshotLoader {
+  return async (artifact: RetainedArtifactReference, signal: AbortSignal) => {
+    const download = await client.downloadRetainedScreenshot(
+      workspaceId,
+      sessionId,
+      artifact.artifactId,
+      { signal },
+    );
+    if (!download.metadata.available || !download.bytes) return null;
+    if (
+      download.metadata.artifactId !== artifact.artifactId ||
+      download.metadata.kind !== artifact.kind ||
+      download.metadata.contentType !== artifact.contentType ||
+      download.metadata.originalBytes !== artifact.originalBytes ||
+      download.metadata.sha256 !== artifact.sha256 ||
+      download.metadata.dimensions?.width !== artifact.dimensions?.width ||
+      download.metadata.dimensions?.height !== artifact.dimensions?.height
+    ) {
+      throw new Error("Retained screenshot receipt verification failed");
+    }
+    return download.bytes;
+  };
+}
+
+/**
+ * Bind expiring generated-video playback sources to one authenticated
+ * workspace, for `MessageTimeline`'s `loadVideoArtifactPlayback`.
+ */
+export function createWorkspaceRetainedVideoLoader(
+  client: RetainedVideoLoaderClient,
+  workspaceId: string,
+): VideoArtifactPlaybackLoader {
+  return async (artifactId: string, signal: AbortSignal) =>
+    await client.createVideoArtifactPlaybackSource(workspaceId, artifactId, { signal });
+}

package/src/timeline/rolling-activity.tsx

@@ -0,0 +1,80 @@
+import { renderActivity } from "./activity-rail";
+import { AnimatePresence, motion, useReducedMotion } from "motion/react";
+import { WrenchIcon } from "lucide-react";
+import { Suspense, useEffect, useState } from "react";
+import { CompactActivityContext } from "./shared";
+import { defaultToolRegistry } from "./tool-renderers";
+import type { ToolRegistry } from "./registry";
+import { toolDisplayName } from "./tool-display-name";
+import type { ActivityItem } from "./types";
+import { rollingActivityItem } from "./work-presentation";
+
+/** One stable viewport; updates replace its content without moving the conversation. */
+export function RollingActivity({
+  items,
+  toolRegistry = defaultToolRegistry,
+  previousItem,
+  showCount = true,
+}: {
+  items: ActivityItem[];
+  /** The standalone item visible immediately before this reel mounted. */
+  previousItem?: ActivityItem | undefined;
+  toolRegistry?: ToolRegistry;
+  /** Show "+N earlier"; off when an enclosing status line already counts steps. */
+  showCount?: boolean;
+}) {
+  const reduced = useReducedMotion();
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+  // Progress notes have their own line in the status row; the reel shows steps, advancing
+  // with the event order so finishing a parallel tool never replays an older one.
+  const selected = rollingActivityItem(items, previousItem, mounted);
+  if (!selected) return null;
+  const { item, earlierCount } = selected;
+  const fallback = (
+    <span className="og-rolling-label">
+      <WrenchIcon className="size-3.5" />
+      <span>
+        {item.kind === "tool-call" ? toolDisplayName(item.name, item.display) : "Working"}
+      </span>
+    </span>
+  );
+  return (
+    <span className="og-rolling-status" data-running={selected.running ? "true" : undefined}>
+      <span className="sr-only">
+        {item.kind === "tool-call"
+          ? toolDisplayName(item.name, item.display)
+          : item.kind === "reasoning"
+            ? "Thinking"
+            : "Working"}
+      </span>
+      <span className="og-rolling-window" aria-hidden="true">
+        <AnimatePresence initial={false} mode="sync">
+          <motion.span
+            key={item.id}
+            className="og-rolling-face"
+            initial={{
+              opacity: 0,
+              y: reduced ? 0 : 24,
+            }}
+            animate={{ opacity: 1, y: 0 }}
+            exit={{
+              opacity: 0,
+              y: reduced ? 0 : -24,
+            }}
+            transition={{ duration: reduced ? 0 : 0.4, ease: [0.22, 1, 0.36, 1] }}
+          >
+            <CompactActivityContext.Provider value={true}>
+              <Suspense fallback={fallback}>
+                {renderActivity(item, toolRegistry, undefined, undefined, undefined, undefined)}
+              </Suspense>
+            </CompactActivityContext.Provider>
+          </motion.span>
+        </AnimatePresence>
+      </span>
+      {showCount && earlierCount > 0 ? (
+        <span className="og-rolling-count">{`+${earlierCount} earlier`}</span>
+      ) : null}
+    </span>
+  );
+}