@opengeni/react 1.3.0 → 1.4.0

package/src/components/tool-review-history.tsx

@@ -1,7 +1,6 @@
 import { createContext, useContext, useEffect, useMemo, useState, type ReactNode } from "react";
 import type { SessionEvent, ToolActionReview } from "@opengeni/sdk";
 import { approvalsFromRequiresAction } from "../approvals";
-import { ToolActionReviewCard } from "./tool-action-review";
 
 type HistoryContext = {
   approvalIds: ReadonlySet<string>;
@@ -55,59 +54,35 @@ export function useHasToolReview(approvalId: string | null): boolean {
   return Boolean(approvalId && history?.approvalIds.has(approvalId));
 }
 
-/** Recorded calls have details, never another decision button. */
-export function ToolReviewHistoryReceipt({ approvalId }: { approvalId: string }) {
+/**
+ * The saved review for one recorded call, or null while it loads or when it is
+ * unavailable (callers then keep their ordinary tool row).
+ */
+export function useRecordedToolReview(approvalId: string | null): {
+  review: ToolActionReview | null;
+  onViewDetails: ((path: string) => void) | undefined;
+} {
   const history = useContext(History);
   const [review, setReview] = useState<ToolActionReview | null>(null);
-  const [failed, setFailed] = useState(false);
-  const [retry, setRetry] = useState(0);
   const load = history?.load;
   const revision = history?.revision;
   useEffect(() => {
-    if (!load) return;
+    if (!load || !approvalId) return;
     let active = true;
-    setFailed(false);
     void load(approvalId).then(
       (value) => {
-        if (active) {
-          if (value.id === approvalId) setReview(value);
-          else setFailed(true);
-        }
-      },
-      () => {
-        if (active) setFailed(true);
+        if (active && value.id === approvalId) setReview(value);
       },
+      () => undefined,
     );
     return () => {
       active = false;
     };
-  }, [approvalId, load, revision, retry]);
-  if (!history) return null;
-  if (failed)
-    return (
-      <p className="text-og-sm text-og-fg-muted" role="alert">
-        Review details unavailable.{" "}
-        <button
-          type="button"
-          className="min-h-11 underline"
-          onClick={() => setRetry((value) => value + 1)}
-        >
-          Try again
-        </button>
-      </p>
-    );
-  if (!review)
-    return (
-      <p role="status" className="text-og-sm text-og-fg-muted">
-        Loading reviewed action…
-      </p>
-    );
-  return (
-    <div data-approval-id={approvalId} data-review-origin="history">
-      <ToolActionReviewCard
-        review={{ ...review, availableActions: [] }}
-        onViewDetails={(path) => history.onViewDetails(review, path)}
-      />
-    </div>
-  );
+  }, [approvalId, load, revision]);
+  const onViewDetails = history?.onViewDetails;
+  return {
+    review: review && review.id === approvalId ? review : null,
+    onViewDetails:
+      review && onViewDetails ? (path: string) => onViewDetails(review, path) : undefined,
+  };
 }

package/src/hooks/use-client-config-flags.ts

@@ -0,0 +1,102 @@
+import type { ClientVoiceInputConfig, ReasoningEffort } from "@opengeni/sdk";
+import { useEffect, useState } from "react";
+
+/** The client-config fields the stock conversation and chat read. */
+export type ClientConfigFlagsSource = {
+  getClientConfig: () => Promise<{
+    fileUploads?: { enabled?: boolean };
+    modelSelection?: boolean | undefined;
+    sandboxFiles?: boolean | undefined;
+    defaultReasoningEffort?: ReasoningEffort | undefined;
+    artifacts?: unknown;
+    sessionCreation?: boolean | undefined;
+    archive?: boolean | undefined;
+    voiceInput?: ClientVoiceInputConfig | undefined;
+  }>;
+};
+
+export type ClientConfigFlags = {
+  /** Whether the config has loaded. Proxy capability flags stay `true` until it says otherwise. */
+  loaded: boolean;
+  uploads: boolean;
+  modelSelection: boolean;
+  sandboxFiles: boolean;
+  defaultReasoningEffort: ReasoningEffort | null;
+  /**
+   * Inline Site previews and the artifact viewer. `false` only when a session
+   * proxy says it does not serve them; native deployments omit the flag.
+   */
+  artifacts: boolean;
+  /** Browser chat creation. `false` only when a session proxy has no `createSession` hook. */
+  sessionCreation: boolean;
+  /** Chat archive/restore. `false` only when a session proxy disables it. */
+  archive: boolean;
+  /** Native voice input when the deployment can transcribe, else null. */
+  voiceInput: ClientVoiceInputConfig | null;
+};
+
+const INITIAL_FLAGS: ClientConfigFlags = {
+  loaded: false,
+  uploads: false,
+  modelSelection: false,
+  sandboxFiles: false,
+  defaultReasoningEffort: null,
+  artifacts: true,
+  sessionCreation: true,
+  archive: true,
+  voiceInput: null,
+};
+
+type ClientConfigFlagsInput = Awaited<ReturnType<ClientConfigFlagsSource["getClientConfig"]>>;
+
+// One read per client: the chat, its list, the new-chat composer and the
+// conversation all ask, and behind a session proxy each read is a round trip.
+const configReads = new WeakMap<object, Promise<ClientConfigFlagsInput>>();
+
+function readClientConfig(client: ClientConfigFlagsSource): Promise<ClientConfigFlagsInput> {
+  let read = configReads.get(client);
+  if (!read) {
+    read = client.getClientConfig();
+    configReads.set(client, read);
+    // A failed read is retried by the next mount rather than cached.
+    read.catch(() => {
+      if (configReads.get(client) === read) configReads.delete(client);
+    });
+  }
+  return read;
+}
+
+/** Deployment and session-proxy capabilities from the client config. */
+export function useClientConfigFlags(
+  client: Partial<ClientConfigFlagsSource> | ClientConfigFlagsSource,
+): ClientConfigFlags {
+  const [flags, setFlags] = useState<ClientConfigFlags>(INITIAL_FLAGS);
+  useEffect(() => {
+    // Custom clients without a config read keep the defaults.
+    if (typeof client.getClientConfig !== "function") return;
+    let live = true;
+    readClientConfig(client as ClientConfigFlagsSource).then(
+      (config) => {
+        if (live) {
+          setFlags({
+            loaded: true,
+            uploads: config.fileUploads?.enabled === true,
+            // Only an explicit offer shows end users the picker.
+            modelSelection: config.modelSelection === true,
+            sandboxFiles: config.sandboxFiles !== false,
+            defaultReasoningEffort: config.defaultReasoningEffort ?? null,
+            artifacts: config.artifacts !== false,
+            sessionCreation: config.sessionCreation !== false,
+            archive: config.archive !== false,
+            voiceInput: config.voiceInput?.available === true ? config.voiceInput : null,
+          });
+        }
+      },
+      () => undefined,
+    );
+    return () => {
+      live = false;
+    };
+  }, [client]);
+  return flags;
+}

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

@@ -225,8 +225,8 @@ export function useSessionEvents(
   // new stream identity cannot expose the previous session's event log.
   const [stateStreamKey, setStateStreamKey] = useState(streamKey);
 
-  // Reopening SSE after a prepend must not cancel the next history page.
-  // Navigation belongs to the session/client lifetime, not the transport.
+  // Navigation belongs to the session/client lifetime, not the transport: an
+  // SSE reconnect must never cancel an in-flight history page.
   useEffect(() => {
     navigationGenerationRef.current += 1;
     setNewerError(null);
@@ -621,9 +621,6 @@ export function useSessionEvents(
           }
           const current = eventWindowRef.current;
           assertPrependOrder(current.events, window.events);
-          // Freeze the live iterator before replacing its in-memory window. Rows
-          // pending in the aborted iterator were never cursor-committed and will
-          // be replayed from the retained high-water mark below.
           const next = boundBrowserSessionEventWindow([...window.events, ...current.events], {
             direction: "oldest",
           });
@@ -633,7 +630,6 @@ export function useSessionEvents(
             markTailPreserved();
             return false;
           }
-          streamAbortRef.current?.abort();
           const status = observeSessionStatus(window.events, sessionStatusRef);
           const retained = {
             ...next,
@@ -645,21 +641,28 @@ export function useSessionEvents(
           }
           const retainedNewest = maxResumeSequenceOrNull(retained.events);
           const previousNewest = maxResumeSequenceOrNull(current.events);
+          const evictedLiveTail =
+            previousNewest !== null && retainedNewest !== null && retainedNewest < previousNewest;
+          if (evictedLiveTail && viewModeRef.current === "live") {
+            // The prepend leaves the live tip. Freeze the iterator before the
+            // window is replaced so a late flush cannot append live rows onto
+            // (and newest-bound away) the history the reader just requested.
+            streamAbortRef.current?.abort();
+          }
           eventWindowRef.current = retained;
           markCommitted();
           oldestSequenceRef.current = retainedOldest;
           newestSequenceRef.current = retainedNewest;
-          streamResumeSequenceRef.current = maxResumeSequence(retained.events);
+          if (evictedLiveTail) {
+            streamResumeSequenceRef.current = maxResumeSequence(retained.events);
+          }
           // Oldest-directed eviction can discard newer in-memory rows. That fact
           // keeps windowTruncated true, but it does not imply older durable rows
           // exist; only the backward DB page can answer hasOlder truthfully.
           const olderStillAvailable = window.hasOlder;
           hasOlderRef.current = olderStillAvailable;
-          const evictedLiveTail =
-            previousNewest !== null && retainedNewest !== null && retainedNewest < previousNewest;
           let newer: boolean | null = null;
           let enterHistory = false;
-          let reconnectLive = false;
           if (viewModeRef.current === "history" || evictedLiveTail) {
             const highWater = lastSequenceRef.current;
             newer = retainedNewest !== null && (retainedNewest < highWater || retained.truncated);
@@ -672,11 +675,13 @@ export function useSessionEvents(
               viewModeRef.current = "history";
               enterHistory = true;
             }
-          } else {
-            // The retained merge is still one contiguous live suffix. Restart
-            // SSE from its cursor so events queued during the fetch are replayed.
-            reconnectLive = true;
           }
+          // Otherwise the merge is still one contiguous live suffix and the open
+          // SSE iterator keeps appending to it: every flush reads
+          // eventWindowRef, so rows delivered during or after this fetch land
+          // once, in order, on the prepended window. Reopening the stream here
+          // would flash a connecting state and re-run session reconciliation on
+          // every scroll-up for no data benefit.
           loadingOlderRef.current = false;
           startTransition(() => {
             if (status !== undefined) {
@@ -689,8 +694,6 @@ export function useSessionEvents(
             }
             if (enterHistory) {
               setViewMode("history");
-            } else if (reconnectLive) {
-              setStreamEpoch((epoch) => epoch + 1);
             }
             setLoadingOlder(false);
           });

package/src/hooks/use-transcription.ts

@@ -611,6 +611,12 @@ function classifyStartError(error: unknown): TranscriptionErrorCode {
 
 export function normalizeTranscriptionErrorCode(code: unknown): TranscriptionErrorCode {
   switch (code) {
+    case "insufficient_credits":
+    case "allowance_exhausted":
+    case "monthly_model_cost_limit":
+    case "unavailable":
+    case "too_large":
+    case "invalid_audio":
     case "permission_denied":
     case "not_supported":
     case "network":

package/src/hooks/use-voice-input.ts

@@ -1503,6 +1503,12 @@ function errorCode(error: unknown): string {
 }
 
 function isRetryableVoiceInputError(error: unknown): boolean {
+  if (
+    ["insufficient_credits", "allowance_exhausted", "monthly_model_cost_limit"].includes(
+      errorCode(error),
+    )
+  )
+    return false;
   if (error instanceof OpenGeniApiError) {
     return error.retryable && error.status !== 409;
   }

package/src/index.ts

@@ -16,6 +16,9 @@ export {
 export {
   attachSessionCapability,
   completeSessionCapabilityOAuth,
+  prepareSessionCapabilityAccess,
+  applySessionCapabilityAccess,
+  type SessionCapabilityAccessPlan,
 } from "./session-capability-policy";
 export { retainedImageId } from "./components/markdown";
 // oxlint-disable-next-line typescript/triple-slash-reference -- package consumers must load the ambient type for this optional untyped peer without emitting a runtime import.
@@ -388,14 +391,20 @@ export type {
 // Tool-renderer registry + the per-tool renderers (the timeline's extension API)
 export {
   createDefaultToolRegistry,
+  createSessionRetainedScreenshotLoader,
   createToolRegistry,
+  createWorkspaceRetainedArtifactLoader,
+  createWorkspaceRetainedVideoLoader,
   defaultToolRegistry,
   rawTypeOf,
 } from "./timeline";
 export type {
   CreateToolRegistryOptions,
   RetainedArtifactLoader,
+  RetainedArtifactLoaderClient,
   RetainedScreenshotLoader,
+  RetainedScreenshotLoaderClient,
+  RetainedVideoLoaderClient,
   VideoArtifactPlaybackLoader,
   ToolRegistry,
   ToolRegistryEntry,

package/src/realtime/realtime-control.tsx

@@ -63,9 +63,26 @@ export type RealtimeModelOption = {
   description: string;
   available: boolean;
   unavailableReason: string | null;
+  /** Machine-readable reason, e.g. `insufficient_credits` (same codes as voice input). */
+  unavailableCode?: string | null | undefined;
   recommended: boolean;
 };
 
+/** Short status label for a credit/availability refusal (shared with the model menu). */
+function realtimeRefusalLabel(code: string | null | undefined): string | null {
+  switch (code) {
+    case "insufficient_credits":
+      return "Out of credits";
+    case "allowance_exhausted":
+    case "monthly_model_cost_limit":
+      return "Usage limit reached";
+    case "realtime_voice_unavailable":
+      return "Voice unavailable";
+    default:
+      return null;
+  }
+}
+
 const CODEX_LIVE_MODEL: RealtimeModelOption = {
   id: "gpt-live-1-boulder-alpha",
   label: "Codex Live",
@@ -822,6 +839,7 @@ export function RealtimeVoiceControl(props: {
     props.canStart,
     props.admissionBlocker ?? null,
     selectedModel.label,
+    selectedModel.unavailableCode ?? null,
   );
   const modeOwned = props.snapshot.mode?.state === "active";
   const retryConnection =
@@ -1333,6 +1351,7 @@ function statusContent(
   canStart: boolean,
   admissionBlocker: string | null,
   modelLabel: string,
+  unavailableCode: string | null = null,
 ): { phase: RealtimeVisualPhase; label: string; detail: string } {
   if (snapshot.audibleOutput === "blocked" && !snapshot.outputMuted) {
     return {
@@ -1379,6 +1398,13 @@ function statusContent(
         detail: "Return to the browser that started it, or wait for that connection to expire.",
       };
     case "error":
+      if (snapshot.refusal) {
+        return {
+          phase: "unavailable",
+          label: realtimeRefusalLabel(snapshot.refusal.code) ?? "Voice unavailable",
+          detail: snapshot.refusal.message,
+        };
+      }
       return {
         phase: "error",
         label: "Voice unavailable",
@@ -1388,7 +1414,7 @@ function statusContent(
       if (!modelAvailable) {
         return {
           phase: "unavailable",
-          label: "Voice model unavailable",
+          label: realtimeRefusalLabel(unavailableCode) ?? "Voice model unavailable",
           detail: admissionBlocker ?? "Choose another voice model.",
         };
       }
@@ -1580,6 +1606,7 @@ function writeRealtimeModelPreference(workspaceId: string, model: SessionRealtim
 
 function isRealtimeModel(value: string | null): value is SessionRealtimeModel {
   return (
+    value === "opengeni-azure/gpt-live-1" ||
     value === "gpt-live-1-boulder-alpha" ||
     value === "opengeni-gateway/openai/gpt-realtime-2.1" ||
     value === "opengeni-gateway/openai/gpt-realtime-mini" ||

package/src/session-capability-policy.ts

@@ -1,4 +1,9 @@
-import type { FirstPartyMcpToolName, CapabilityCatalogItem } from "@opengeni/sdk";
+import type {
+  FirstPartyMcpToolName,
+  CapabilityCatalogItem,
+  Session,
+  UpdateSessionToolPolicyRequest,
+} from "@opengeni/sdk";
 import type { OpenGeniBrowserClient as OpenGeniClient } from "@opengeni/sdk/browser";
 
 /** Catalog tool discovery may be lazy; selecting the installed server does not
@@ -25,6 +30,16 @@ export async function attachSessionCapability(
   if (!stillCurrent()) throw new Error("Connection setup was interrupted.");
   const session = await client.getSession(workspaceId, sessionId);
   if (!stillCurrent()) throw new Error("Connection setup was interrupted.");
+  const request = capabilityToolPolicyUpdate(session, item);
+  if (request) await client.updateSessionToolPolicy(workspaceId, sessionId, request);
+}
+
+function capabilityToolPolicyUpdate(
+  session: Session,
+  item: CapabilityCatalogItem,
+): UpdateSessionToolPolicyRequest | null {
+  const tools = sessionCapabilityTools(item);
+  if (item.kind === "skill" || tools.length === 0) return null;
   // Session.tools includes mandatory runtime servers, which must never be
   // echoed into the human's explicit selection.
   let existing = session.tools.filter(
@@ -42,10 +57,19 @@ export async function attachSessionCapability(
     // automatic selection. Compare against the resolved defaults instead.
     existing = policy.effectiveIds
       .filter((id) => !policy.mandatoryIds.includes(id))
-      .map((id) => ({ kind: "mcp" as const, id }));
+      .map(
+        (id) =>
+          session.tools.find((tool) => tool.kind === "mcp" && tool.id === id) ?? {
+            kind: "mcp" as const,
+            id,
+            optional: true,
+          },
+      );
   }
   const additions = tools.filter(
-    (tool) => !existing.some((current) => current.kind === tool.kind && current.id === tool.id),
+    (tool) =>
+      !session.effectiveToolPolicy?.mandatoryIds.includes(tool.id) &&
+      !existing.some((current) => current.kind === tool.kind && current.id === tool.id),
   );
   const recommended = Array.isArray(item.metadata?.firstPartyMcpTools)
     ? (item.metadata.firstPartyMcpTools.filter(
@@ -53,13 +77,102 @@ export async function attachSessionCapability(
       ) as FirstPartyMcpToolName[])
     : [];
   const firstParty = [...new Set([...session.firstPartyMcpTools, ...recommended])];
-  if (additions.length === 0 && firstParty.length === session.firstPartyMcpTools.length) return;
-  await client.updateSessionToolPolicy(workspaceId, sessionId, {
+  if (additions.length === 0 && firstParty.length === session.firstPartyMcpTools.length)
+    return null;
+  return {
     mode: "explicit",
     tools: [...existing, ...additions],
     firstPartyMcpTools: firstParty,
     expectedVersion: session.toolPolicyVersion,
-  });
+  };
+}
+
+/** Read-only review. Hosts must show ancestor changes and obtain a separate
+ * explicit click before applying. This plan is never authorization. */
+export type SessionCapabilityAccessPlan = {
+  workspaceId: string;
+  sessionId: string;
+  capabilityId: string;
+  sessions: Array<{
+    id: string;
+    title: string | null;
+    parentSessionId: string | null;
+    toolPolicyVersion: number;
+    request: UpdateSessionToolPolicyRequest | null;
+  }>;
+};
+
+export async function prepareSessionCapabilityAccess(
+  client: OpenGeniClient,
+  workspaceId: string,
+  sessionId: string,
+  item: CapabilityCatalogItem,
+  stillCurrent: () => boolean = () => true,
+): Promise<SessionCapabilityAccessPlan> {
+  const sessions: SessionCapabilityAccessPlan["sessions"] = [];
+  if (item.kind === "skill" || sessionCapabilityTools(item).length === 0)
+    return { workspaceId, sessionId, capabilityId: item.id, sessions };
+  const visited = new Set<string>();
+  let id: string | null = sessionId;
+  while (id) {
+    if (!stillCurrent()) throw new Error("Connection setup was interrupted.");
+    if (visited.has(id)) throw new Error("The parent chat chain could not be verified.");
+    visited.add(id);
+    const session = await client.getSession(workspaceId, id);
+    if (!stillCurrent()) throw new Error("Connection setup was interrupted.");
+    const request = capabilityToolPolicyUpdate(session, item);
+    sessions.push({
+      id,
+      title: session.title ?? null,
+      parentSessionId: session.parentSessionId ?? null,
+      toolPolicyVersion: session.toolPolicyVersion,
+      request,
+    });
+    // An unchanged immediate parent already supplies this capability's ceiling.
+    // Do not read or broaden ancestors irrelevant to this addition.
+    if (!request) break;
+    id = session.parentSessionId ?? null;
+  }
+  return { workspaceId, sessionId, capabilityId: item.id, sessions: sessions.reverse() };
+}
+
+/** Preflight the entire review, then apply ordinary CAS-fenced API writes root
+ * first. A partial failure may leave approved ancestor changes committed; never
+ * claim success or roll back another person's edits. Prepare a new review. */
+export async function applySessionCapabilityAccess(
+  client: OpenGeniClient,
+  plan: SessionCapabilityAccessPlan,
+  stillCurrent: () => boolean = () => true,
+): Promise<void> {
+  for (const reviewed of plan.sessions) {
+    if (!stillCurrent()) throw new Error("Connection setup was interrupted.");
+    const current = await client.getSession(plan.workspaceId, reviewed.id);
+    if (!stillCurrent()) throw new Error("Connection setup was interrupted.");
+    if (
+      current.toolPolicyVersion !== reviewed.toolPolicyVersion ||
+      (current.parentSessionId ?? null) !== reviewed.parentSessionId
+    )
+      throw new Error("Chat access changed. Click Add tools to review the current choices again.");
+  }
+  for (const reviewed of plan.sessions) {
+    if (!stillCurrent()) throw new Error("Connection setup was interrupted.");
+    if (reviewed.request) {
+      const updated = await client.updateSessionToolPolicy(
+        plan.workspaceId,
+        reviewed.id,
+        reviewed.request,
+      );
+      if (
+        reviewed.request.mode === "explicit" &&
+        reviewed.request.firstPartyMcpTools.some(
+          (tool) => !updated.firstPartyMcpTools.includes(tool),
+        )
+      )
+        throw new Error(
+          "This chat's capabilities do not allow these tools. Review its capability settings before adding tools again.",
+        );
+    }
+  }
 }
 
 /** Native OAuth callbacks have already saved the provider connection. Finish

package/src/timeline/index.ts

@@ -61,6 +61,16 @@ 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,

package/src/timeline/retained-loaders.ts

@@ -0,0 +1,86 @@
+import type { OpenGeniClient, RetainedArtifactReference } from "@opengeni/sdk";
+import type {
+  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.
+ */
+export function createWorkspaceRetainedArtifactLoader(
+  client: RetainedArtifactLoaderClient,
+  workspaceId: string,
+): RetainedArtifactLoader {
+  return async (artifact: RetainedArtifactReference, signal: AbortSignal) => {
+    if (artifact.kind === "file") {
+      const download = await client.downloadRetainedArtifact(workspaceId, artifact, { signal });
+      return download.bytes;
+    }
+    const download = await client.createRetainedArtifactDownloadUrl(workspaceId, artifact, {
+      signal,
+    });
+    return { url: download.url };
+  };
+}
+
+/**
+ * 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/tool-display-name.ts

@@ -30,7 +30,11 @@ export function toolMatchesLeaf(wireName: string, leaf: string): boolean {
  */
 export function toolDisplayName(name: string, display?: ToolDisplayMetadata): string {
   if (!display && /^[a-f0-9]{64}$/.test(name)) return "Tool call";
-  const phrase = (display?.toolName ?? mcpToolLeaf(name)).replace(/[_-]+/g, " ").trim();
+  // "batch modify messages" → "Modify messages": batching is transport, not the action.
+  const phrase = (display?.toolName ?? mcpToolLeaf(name))
+    .replace(/[_-]+/g, " ")
+    .trim()
+    .replace(/^batch\s+(?=\S)/i, "");
   const title =
     display?.title ?? (phrase ? phrase.charAt(0).toUpperCase() + phrase.slice(1) : name);
   return display?.accountLabel ? `${title} — ${display.accountLabel}` : title;