@opengeni/react 3.3.2 → 3.7.0-canary.0

package/src/components/composer.tsx

@@ -137,6 +137,7 @@ export type ChatComposerMessages = {
   uploading: string;
   uploadFailed: string;
   previewAttachment: (name: string) => string;
+  previewUnavailable?: string | undefined;
   attachmentPreviewLabel: string;
   downloadAttachment: (name: string) => string;
   closeAttachmentPreview: string;
@@ -204,6 +205,7 @@ export const defaultChatComposerMessages: ChatComposerMessages = {
   uploading: "Uploading",
   uploadFailed: "Upload failed",
   previewAttachment: (name) => `Preview ${name}`,
+  previewUnavailable: "Preview unavailable",
   attachmentPreviewLabel: "Attachment preview",
   downloadAttachment: (name) => `Download ${name}`,
   closeAttachmentPreview: "Close",
@@ -947,6 +949,7 @@ export function Attachments() {
       onRemove={controller.attachments.remove}
       onRetry={controller.attachments.retry}
       onRetainPreview={controller.attachments.retainPreview}
+      onLoadPreview={controller.attachments.loadPreview}
     />
   );
 }
@@ -1638,20 +1641,83 @@ function AttachmentChips({
   onRemove,
   onRetry,
   onRetainPreview,
+  onLoadPreview,
 }: {
   attachments: UseFileAttachmentsResult["attachments"];
   messages: ChatComposerMessages;
   onRemove: (id: string) => void;
   onRetry?: ((id: string) => void) | undefined;
   onRetainPreview: UseFileAttachmentsResult["retainPreview"];
+  onLoadPreview: UseFileAttachmentsResult["loadPreview"];
 }) {
   const lightbox = useLightboxOptional();
+  const previewRequest = useRef<AbortController | null>(null);
+  const [previewLoadingId, setPreviewLoadingId] = useState<string | null>(null);
+  const [previewErrorId, setPreviewErrorId] = useState<string | null>(null);
+
+  useEffect(() => () => previewRequest.current?.abort(), [onLoadPreview]);
+
+  async function openPreview(
+    attachment: UseFileAttachmentsResult["attachments"][number],
+    source: HTMLButtonElement,
+    canLoadPreview: boolean,
+  ) {
+    previewRequest.current?.abort();
+    const attachmentId = attachment.id;
+    const releaseSource = onRetainPreview(attachmentId);
+    let src = attachment.previewUrl;
+    if (!releaseSource && canLoadPreview) {
+      const controller = new AbortController();
+      previewRequest.current = controller;
+      setPreviewLoadingId(attachmentId);
+      setPreviewErrorId(null);
+      try {
+        src = await onLoadPreview!(attachmentId, controller.signal);
+        if (controller.signal.aborted) return;
+        if (!src) {
+          setPreviewErrorId(attachmentId);
+          return;
+        }
+      } catch {
+        if (!controller.signal.aborted) setPreviewErrorId(attachmentId);
+        return;
+      } finally {
+        if (previewRequest.current === controller) {
+          setPreviewLoadingId(null);
+        }
+      }
+    }
+    lightbox!.open(
+      src!,
+      attachment.name,
+      source,
+      messages.attachmentPreviewLabel,
+      attachment.name,
+      {
+        download: messages.downloadAttachment(attachment.name),
+        close: messages.closeAttachmentPreview,
+      },
+      releaseSource,
+    );
+  }
+
   return (
     <div className="flex flex-wrap gap-2 px-3 py-2">
       {attachments.map((attachment) => {
         const failed = attachment.status === "failed";
-        const statusText =
-          attachment.status === "uploading"
+        const secureContextRequired = attachment.errorCode === "secure_context_required";
+        const previewFailed = previewErrorId === attachment.id;
+        const previewLoading = previewLoadingId === attachment.id;
+        const canLoadPreview = Boolean(
+          lightbox &&
+          onLoadPreview &&
+          attachment.status === "ready" &&
+          attachment.file &&
+          attachment.contentType.startsWith("image/"),
+        );
+        const statusText = previewFailed
+          ? (messages.previewUnavailable ?? "Preview unavailable")
+          : attachment.status === "uploading"
             ? messages.uploading
             : failed
               ? attachment.error || messages.uploadFailed
@@ -1660,38 +1726,42 @@ function AttachmentChips({
           <div
             key={attachment.id}
             className={cn(
-              "flex min-w-0 max-w-[240px] items-center gap-2 rounded-og-md border px-2 py-1.5 text-og-sm",
+              "flex min-w-0 items-center gap-2 rounded-og-md border px-2 py-1.5 text-og-sm",
               failed
-                ? "border-og-status-failed/40 bg-og-status-failed/10"
-                : "border-og-border bg-og-surface-2",
+                ? cn(
+                    "border-og-status-failed/40 bg-og-status-failed/10",
+                    secureContextRequired
+                      ? "max-w-full items-start sm:max-w-[32rem]"
+                      : "max-w-[240px]",
+                  )
+                : "max-w-[240px] border-og-border bg-og-surface-2",
             )}
           >
-            {attachment.previewUrl && lightbox ? (
+            {lightbox && (attachment.previewUrl || canLoadPreview) ? (
               <button
                 type="button"
-                className="size-8 shrink-0 overflow-hidden rounded outline-hidden focus-visible:ring-2 focus-visible:ring-og-accent"
+                className={cn(
+                  "size-8 shrink-0 overflow-hidden rounded outline-hidden focus-visible:ring-2 focus-visible:ring-og-accent",
+                  !attachment.previewUrl && "flex items-center justify-center disabled:cursor-wait",
+                )}
                 aria-label={messages.previewAttachment(attachment.name)}
-                onClick={(event) => {
-                  const releasePreview = onRetainPreview(attachment.id);
-                  lightbox.open(
-                    attachment.previewUrl!,
-                    attachment.name,
-                    event.currentTarget,
-                    messages.attachmentPreviewLabel,
-                    attachment.name,
-                    {
-                      download: messages.downloadAttachment(attachment.name),
-                      close: messages.closeAttachmentPreview,
-                    },
-                    releasePreview,
-                  );
-                }}
+                aria-busy={previewLoading || undefined}
+                disabled={previewLoading}
+                onClick={(event) =>
+                  void openPreview(attachment, event.currentTarget, canLoadPreview)
+                }
               >
-                <img
-                  src={attachment.previewUrl}
-                  alt=""
-                  className="h-full w-full object-cover transition-opacity hover:opacity-80"
-                />
+                {attachment.previewUrl ? (
+                  <img
+                    src={attachment.previewUrl}
+                    alt=""
+                    className="h-full w-full object-cover transition-opacity hover:opacity-80"
+                  />
+                ) : previewLoading ? (
+                  <LoaderCircleIcon className="size-4 animate-og-spin text-og-fg-muted" />
+                ) : (
+                  <ImageIcon className="size-4 text-og-fg-muted" />
+                )}
               </button>
             ) : attachment.previewUrl ? (
               <img
@@ -1706,7 +1776,11 @@ function AttachmentChips({
             )}
             <div className="min-w-0 flex-1">
               <div className="truncate font-medium text-og-fg">{attachment.name}</div>
-              {failed ? (
+              {secureContextRequired ? (
+                <div className="break-words text-og-xs leading-4 text-og-status-failed">
+                  {statusText}
+                </div>
+              ) : failed || previewFailed ? (
                 <ComposerTip tip={statusText}>
                   <div className="truncate text-og-xs text-og-status-failed">{statusText}</div>
                 </ComposerTip>
@@ -1717,7 +1791,7 @@ function AttachmentChips({
             {attachment.status === "uploading" ? (
               <LoaderCircleIcon className="size-3.5 shrink-0 animate-og-spin" />
             ) : null}
-            {failed && onRetry ? (
+            {failed && !secureContextRequired && onRetry ? (
               <ComposerTip tip={messages.retryUpload}>
                 <button
                   type="button"

package/src/components/message-timeline.tsx

@@ -1183,17 +1183,23 @@ export function MessageTimeline({
         applyPinned(false);
       }
     } else if (prepended) {
+      const olderAttemptState = olderLoadAttemptRef.current?.[1];
+      const underfillOwned =
+        !!olderLoadAttemptRef.current &&
+        olderAttemptState !== 1 &&
+        olderAttemptState !== 2 &&
+        olderAttemptState !== 3;
       if (
         autoFollow &&
         pinnedRef.current &&
         !hasNewer &&
         !pendingReaderLeaveRef.current &&
-        (wasAtLiveTailBeforeCommit || olderLoadAttemptRef.current)
+        (wasAtLiveTailBeforeCommit || underfillOwned)
       ) {
-        // A pending short-window load owns the prepend even when live growth
-        // has left its still-pinned camera with raw geometry debt. Unrelated
-        // prepends retain the prior-tip fallback so a stale pin after an
-        // extension/programmatic history jump still restores its row anchor.
+        // Still following the live tip: underfill, or a prefetch the reader
+        // started and then returned from. Park at the new tip. A stale pin
+        // while they are actually up in a short window (gap is not inside
+        // PIN_THRESHOLD of maxScroll, so wasAtLiveTail is false) restores.
         clearPendingReaderLeave();
         snapToBottom(node);
       } else {
@@ -1598,6 +1604,19 @@ export function MessageTimeline({
       return;
     }
 
+    if (programmatic && !pinnedRef.current) {
+      // Restore/camera writes while reading history are not a return to the tip.
+      // Still expire a pending Jump-to-latest latch: the in-window jump itself
+      // is a programmatic snap, and a later reader scroll-away can arrive
+      // before that echo is consumed. Skipping this left the latch armed and
+      // snapped the reader when hasNewer later flipped false.
+      syncScrollBaseline(node);
+      if (wantPinRef.current && !isNearBottom(node)) {
+        wantPinRef.current = false;
+      }
+      return;
+    }
+
     if (autoFollow && pinnedRef.current && !hasNewer) {
       // Fold / composer / SessionChrome: viewport shrink raises maxScroll without
       // growing content. Must hit tipFollow before we adopt the new clientHeight
@@ -1659,10 +1678,15 @@ export function MessageTimeline({
     syncScrollBaseline(node);
     const nearBottom = isNearBottom(node);
 
-    // Re-pin only when the reader moved toward/at the tip — not when a fold
-    // clamp dragged scrollTop down onto nearBottom.
+    // Re-pin only when the reader moved toward/at the tip without a content
+    // insertion. Prepend restore and overflow-anchor raise scrollTop by
+    // roughly the same amount as maxScroll; treating that as a scroll-down
+    // re-pinned a compact-tail history reader (their preserved gap falls
+    // inside PIN_THRESHOLD once the window is tall) and snapped them back.
+    const inserted = Math.max(0, nextMaxScroll - previousMaxScroll);
+    const towardTip = nextTop - previousTop - inserted;
     const nextPinned =
-      !hasNewer && nearBottom && nextTop >= previousTop - TIP_FOLLOW_READER_UP_EPS_PX;
+      !hasNewer && nearBottom && towardTip >= -TIP_FOLLOW_READER_UP_EPS_PX && inserted <= 1;
     if (!nextPinned) {
       stopFollow();
     }
@@ -3581,6 +3605,7 @@ function AuthNeededRow({
       ? `${provider} tools unavailable`
       : `${actionLabel} ${provider}`;
   const reasonLine = recommendation?.rationale ?? authReasonLine(item.reason);
+  const hostAuthorizationUrl = item.authoritySource === "host" ? item.authorizationUrl : null;
 
   const start = async () => {
     if (!onReconnect || busy) {
@@ -3623,7 +3648,20 @@ function AuthNeededRow({
             ) : null}
           </div>
         </div>
-        {!unavailable && onReconnect ? (
+        {hostAuthorizationUrl ? (
+          <a
+            href={hostAuthorizationUrl}
+            rel="noreferrer"
+            target="_blank"
+            className={cn(
+              PRIMARY_ACTION_CLASS,
+              "transition-colors hover:bg-og-accent-strong pointer-coarse:min-h-9",
+            )}
+          >
+            <RefreshCwIcon className="size-3.5" aria-hidden />
+            {actionLabel}
+          </a>
+        ) : item.authoritySource !== "host" && !unavailable && onReconnect ? (
           <button
             type="button"
             onClick={() => void start()}
@@ -3636,7 +3674,7 @@ function AuthNeededRow({
             <RefreshCwIcon className={cn("size-3.5", busy && "animate-og-spin")} aria-hidden />
             {busy ? "Opening…" : actionLabel}
           </button>
-        ) : !unavailable && item.authorizationUrl ? (
+        ) : item.authoritySource !== "host" && !unavailable && item.authorizationUrl ? (
           <a
             href={item.authorizationUrl}
             rel="noreferrer"

package/src/components/model-policy-picker.tsx

@@ -26,6 +26,7 @@ import {
   findPickerRow,
   groupPickerRowsByBillingClass,
   labelReasoningEffort,
+  payerSummaryForModel,
   projectClientModelRows,
   runnableLatencyModesForModel,
   type PickerBillingClass,
@@ -68,7 +69,8 @@ export const defaultModelPolicyPickerMessages: ModelPolicyPickerMessages = {
     external: "Provider terms and limits apply",
     codex_subscription: "ChatGPT / Codex plan",
     supergrok_subscription: "SuperGrok / xAI plan",
-    byok: "Billed to your AI Gateway",
+    byok: "Billed to the workspace provider account",
+    organization_byok: "Billed to the organization provider account",
   },
 };
 
@@ -158,7 +160,8 @@ export function BillingClassMark(props: {
     external: "External provider",
     codex_subscription: "Codex",
     supergrok_subscription: "SuperGrok",
-    byok: "Bring your own key",
+    byok: "Workspace provider account",
+    organization_byok: "Organization provider account",
   };
   const label = props["aria-label"] ?? labels[props.billingClass];
   const accessibility =
@@ -195,6 +198,18 @@ function isCodexModel(model: ClientModel): boolean {
   return model.id.startsWith("codex/") || model.source === "codex";
 }
 
+function billingClassForMissingSelection(modelId: string): PickerBillingClass {
+  if (modelId.startsWith("workspace-gateway/")) return "byok";
+  if (modelId.startsWith("workspace-openrouter/")) return "byok";
+  // A deployment OpenRouter ID does not encode its workspace-facing cost.
+  // Missing rows therefore use the credits-safe rail instead of falsely
+  // claiming that an unknown former selection was externally funded.
+  if (modelId.startsWith("openrouter/")) return "opengeni_credits";
+  if (modelId.startsWith("codex/")) return "codex_subscription";
+  if (modelId.startsWith("supergrok/")) return "supergrok_subscription";
+  return "opengeni_credits";
+}
+
 function applyCodexOnly(
   rows: ClientPickerModelRow[],
   codexOnly: boolean,
@@ -227,7 +242,11 @@ function defaultNavState(rows: ClientPickerModelRow[], modelId: string): PickerN
       ? { level: "models", rail: onlyRail, modelId: null }
       : { level: "providers", rail: null, modelId: null };
   }
-  return { level: "thinking", rail: selected.billingClass, modelId: selected.id };
+  return {
+    level: "thinking",
+    rail: selected.billingClass,
+    modelId: selected.id,
+  };
 }
 
 function usePickerNavState(
@@ -352,7 +371,11 @@ export function ModelPolicyPickerMenu(
 
   const effectiveNav =
     nav.level === "providers" && groups.length === 1
-      ? { level: "models" as const, rail: groups[0]!.billingClass, modelId: null }
+      ? {
+          level: "models" as const,
+          rail: groups[0]!.billingClass,
+          modelId: null,
+        }
       : nav;
   const activeGroup =
     effectiveNav.rail === null
@@ -416,14 +439,21 @@ export function ModelPolicyPickerMenu(
             <PickerNavRow
               key={`${row.billingClass}:${row.id}`}
               label={row.label}
-              hint={row.unavailableReason ?? undefined}
+              hint={row.unavailableReason ?? payerSummaryForModel(row.catalog)}
               disabled={!row.selectable}
               title={row.unavailableReason ?? undefined}
               active={row.id === props.model}
               testId={`model-picker-choice-${row.id}`}
               onClick={() => {
                 if (row.selectable) {
-                  go({ level: "thinking", rail: row.billingClass, modelId: row.id }, 1);
+                  go(
+                    {
+                      level: "thinking",
+                      rail: row.billingClass,
+                      modelId: row.id,
+                    },
+                    1,
+                  );
                 }
               }}
             />
@@ -605,10 +635,7 @@ export function ModelPolicyPicker(props: ModelPolicyPickerProps) {
           )}
         >
           <BillingClassMark
-            billingClass={
-              selected?.billingClass ??
-              (props.model.startsWith("codex/") ? "codex_subscription" : "opengeni_credits")
-            }
+            billingClass={selected?.billingClass ?? billingClassForMissingSelection(props.model)}
             className="text-og-fg"
           />
           <span className="og-model-policy-label-full min-w-0 truncate font-medium text-og-fg max-sm:hidden">

package/src/components/sandbox-workspace.tsx

@@ -102,6 +102,12 @@ function isWorkbenchSurface(value: string): value is SandboxWorkspaceSurface {
   return (WORKBENCH_SURFACES as readonly string[]).includes(value);
 }
 
+function isCanonicalAbsoluteSandboxPath(value: string | null | undefined): boolean {
+  if (!value) return false;
+  const portable = value.replaceAll("\\", "/");
+  return portable.startsWith("/") || /^[A-Za-z]:\//u.test(portable);
+}
+
 function sourceDrivenDefaultTab(
   hasChanges: boolean,
   changesEnabled: boolean,
@@ -424,6 +430,11 @@ export function useSandboxWorkspaceTabs(
   const warmIntents =
     storedWarmIntents.sessionId === sessionId ? storedWarmIntents : emptyWarmIntents(sessionId);
   const { warmTerminal, warmFiles } = warmIntents;
+  // A host-requested file is itself explicit live-file intent. Derive the wake
+  // directly from the request instead of relying on a follow-up effect to copy
+  // it into local state; otherwise a missing or delayed effect leaves the file
+  // waiting for a sandbox that this hook never asks to start.
+  const filesWarmRequested = warmFiles || Boolean(requestedFilePath);
   const requestWarmIntent = useCallback(
     (intent: Exclude<keyof SessionWarmIntents, "sessionId">) => {
       setStoredWarmIntents((previous) => {
@@ -433,10 +444,6 @@ export function useSandboxWorkspaceTabs(
     },
     [sessionId],
   );
-  useEffect(() => {
-    if (requestedFilePath) requestWarmIntent("warmFiles");
-  }, [requestWarmIntent, requestedFilePath, requestedFileRequestId]);
-
   // The session's machine fleet + the active-sandbox pointer. Drives the header
   // chip (which machine + its connection state). Shares the session list poll.
   const machines = useMachines({
@@ -457,7 +464,7 @@ export function useSandboxWorkspaceTabs(
     attachTerminal: terminalEnabled && warmTerminal,
     // Explicit live-file intent only — NOT "the Files tab is open". A cold edit
     // or guarded-file open wakes the box; a glance at the tree/diff does not.
-    attachFiles: workspaceDataEnabled && warmFiles,
+    attachFiles: workspaceDataEnabled && filesWarmRequested,
   });
   const capabilities = caps.capabilities;
   const liveness = capabilities?.liveness;
@@ -467,6 +474,9 @@ export function useSandboxWorkspaceTabs(
   // is still pending.
   const liveIoLiveness = liveness ?? null;
   const fileSystemOn = capabilities?.FileSystem.available ?? false;
+  const fileSystemRoute = capabilities
+    ? { epoch: capabilities.leaseEpoch, root: capabilities.FileSystem.root }
+    : undefined;
   // The FS is writable only when it's live AND not read-only. A self-hosted box
   // that's offline (or any read-only advertisement) or a capture-served cold tree
   // must not offer create/rename/delete/edit affordances — you cannot mutate a
@@ -574,9 +584,10 @@ export function useSandboxWorkspaceTabs(
     active: filesActive && !turnInFlight,
     // A deliberate canonical absolute-path open browses in the selected target's
     // advertised namespace, so the authoritative tree and link share exact paths.
-    ...(requestedFilePath?.startsWith("/") && capabilities?.FileSystem.root
+    ...(isCanonicalAbsoluteSandboxPath(requestedFilePath) && capabilities?.FileSystem.root
       ? { rootPath: capabilities.FileSystem.root }
       : {}),
+    ...(fileSystemRoute ? { route: fileSystemRoute } : {}),
     repoPaths,
     liveness: liveIoLiveness,
     capture: captureState.capture,
@@ -665,7 +676,7 @@ export function useSandboxWorkspaceTabs(
     capabilitiesState: caps.state,
     activeMachineState: activeMachine?.state ?? null,
     activeIsSelfhosted: activeMachine?.kind === "selfhosted",
-    wantsWarm: (terminalEnabled && warmTerminal) || (workspaceDataEnabled && warmFiles),
+    wantsWarm: (terminalEnabled && warmTerminal) || (workspaceDataEnabled && filesWarmRequested),
     capturedAt: captureState.capturedAt,
   });
   const workspaceWaking = chip.state === "waking";

package/src/components/session-chrome.tsx

@@ -159,7 +159,7 @@ export function sessionChromeGoalPillLabel(
 
 /**
  * One human sentence explaining WHY the goal is not pursuing right now: the
- * pause reason, the agent's own `goal_wait` hold (reason + deadline), or the
+ * pause reason, the agent's own `wait_for_input` hold (reason + deadline), or the
  * next idle-backoff check time. Null when the state needs no explanation.
  */
 export function sessionChromeGoalPillExplanation(
@@ -182,7 +182,7 @@ export function sessionChromeGoalPillExplanation(
     const until = continuation.nextAttemptAt
       ? ` until ${formatClockTime(continuation.nextAttemptAt)}`
       : "";
-    return `Waiting for input${reason ? `: ${reason}` : ""}${until}. A child result, an agent message, or your prompt wakes it sooner.`;
+    return `Waiting for input${reason ? `: ${reason}` : ""}${until}. Relevant session input—including a child result, background-command result, agent message, schedule, or your prompt—wakes it sooner.`;
   }
   return null;
 }
@@ -228,7 +228,7 @@ export function sessionChromeGoalPillState(
   // next evaluation at `nextAttemptAt`) is an ordinary scheduled state.
   if (continuation.state === "scheduled") return "scheduled";
   if (continuation.state === "blocked") {
-    // `held_for_input` is the agent's own goal_wait hold (waiting for child
+    // `held_for_input` is the agent's own wait_for_input hold (waiting for child
     // results / external input until a deadline); it shares the Held pill.
     return continuation.reason === "workstream_paused" || continuation.reason === "held_for_input"
       ? "held"

package/src/hooks/use-file-attachments.ts

@@ -26,6 +26,8 @@ export type FileAttachment = {
   file?: FileAsset | undefined;
   /** Object-URL for an inline preview; minted for `image/*` files only. */
   previewUrl?: string | undefined;
+  /** Stable SDK failure code for UI behavior that must not parse error copy. */
+  errorCode?: "secure_context_required" | undefined;
   error?: string | undefined;
 };
 
@@ -50,6 +52,12 @@ export type UseFileAttachmentsResult = {
   addFromPaste: (event: { clipboardData: DataTransfer | null }) => void;
   /** Restore already-ready server assets without recreating browser-local bytes. */
   restoreReadyFiles: (files: Iterable<FileAsset>) => void;
+  /**
+   * Resolve a ready image's short-lived server preview URL on demand. Optional
+   * for upload-only embedded clients; local object-URL previews remain usable
+   * without it.
+   */
+  loadPreview?: ((id: string, signal?: AbortSignal) => Promise<string | undefined>) | undefined;
   /**
    * Re-run the upload for a `failed` attachment, in place (same id, same
    * source file). No-op for an id that isn't a known failed upload.
@@ -76,6 +84,27 @@ export type UseFileAttachmentsResult = {
 
 const isImage = (file: File): boolean => file.type.startsWith("image/");
 
+let fallbackAttachmentId = 0;
+
+function createAttachmentId(): string {
+  const cryptoSource = globalThis.crypto;
+  if (typeof cryptoSource?.randomUUID === "function") return cryptoSource.randomUUID();
+  fallbackAttachmentId += 1;
+  // This id is only a browser-local React key and retry lookup, never durable
+  // authority. Keep attachment tracking usable when HTTP withholds randomUUID
+  // or Web Crypto is unavailable so the SDK's typed failure reaches the card.
+  return `attachment:${Date.now().toString(36)}:${fallbackAttachmentId.toString(36)}`;
+}
+
+function secureContextRequiredErrorCode(error: unknown): "secure_context_required" | undefined {
+  return typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === "secure_context_required"
+    ? error.code
+    : undefined;
+}
+
 /**
  * Upload-and-track state for files attached to the next message. Owns the
  * full client-side upload layer: a per-file `uploading | ready | failed`
@@ -91,6 +120,8 @@ export function useFileAttachments(
   const { client, workspaceId } = useEmbeddedFileAttachments(options);
   const pasteFilter = options.pasteFilter ?? isImage;
   const [attachments, setAttachments] = useState<FileAttachment[]>([]);
+  const attachmentsRef = useRef(attachments);
+  attachmentsRef.current = attachments;
   // Keep the source File per attachment id so a failed upload can be retried
   // in place. Cleared on remove/clear so it never outlives its attachment.
   const sources = useRef<Map<string, File>>(new Map());
@@ -198,6 +229,7 @@ export function useFileAttachments(
                     name: asset.filename,
                     contentType: asset.contentType,
                     sizeBytes: asset.sizeBytes,
+                    errorCode: undefined,
                     error: undefined,
                   }
                 : attachment,
@@ -212,6 +244,7 @@ export function useFileAttachments(
                 ? {
                     ...attachment,
                     status: "failed",
+                    errorCode: secureContextRequiredErrorCode(error),
                     error: error instanceof Error ? error.message : String(error),
                   }
                 : attachment,
@@ -225,7 +258,7 @@ export function useFileAttachments(
   const addFiles = useCallback(
     (files: Iterable<File>) => {
       for (const file of files) {
-        const id = crypto.randomUUID();
+        const id = createAttachmentId();
         sources.current.set(id, file);
         const previewUrl = isImage(file) ? URL.createObjectURL(file) : undefined;
         if (previewUrl) previewUrls.current.set(id, previewUrl);
@@ -255,7 +288,7 @@ export function useFileAttachments(
       setAttachments((current) =>
         current.map((attachment) =>
           attachment.id === id
-            ? { ...attachment, status: "uploading", error: undefined }
+            ? { ...attachment, status: "uploading", errorCode: undefined, error: undefined }
             : attachment,
         ),
       );
@@ -305,6 +338,7 @@ export function useFileAttachments(
                 sizeBytes: file.sizeBytes,
                 status: "ready",
                 file,
+                errorCode: undefined,
                 error: undefined,
               }
             : {
@@ -327,6 +361,31 @@ export function useFileAttachments(
     [workspaceId],
   );
 
+  const loadPreview = useCallback(
+    async (id: string, signal?: AbortSignal): Promise<string | undefined> => {
+      const generation = scopeGeneration.current;
+      const attachment = attachmentsRef.current.find((candidate) => candidate.id === id);
+      const createDownloadUrl = client.createFileDownloadUrl;
+      if (
+        !attachment ||
+        attachment.status !== "ready" ||
+        !attachment.file ||
+        !attachment.contentType.startsWith("image/") ||
+        typeof createDownloadUrl !== "function" ||
+        signal?.aborted
+      ) {
+        return undefined;
+      }
+      const fileId = attachment.file.id;
+      const signed = await createDownloadUrl.call(client, workspaceId, fileId, { signal });
+      if (scopeGeneration.current !== generation || signal?.aborted) return undefined;
+      const current = attachmentsRef.current.find((candidate) => candidate.id === id);
+      if (current?.status !== "ready" || current.file?.id !== fileId) return undefined;
+      return signed.url;
+    },
+    [client, workspaceId],
+  );
+
   const remove = useCallback(
     (id: string) => {
       sources.current.delete(id);
@@ -368,6 +427,7 @@ export function useFileAttachments(
     addFiles,
     addFromPaste,
     restoreReadyFiles,
+    ...(typeof client.createFileDownloadUrl === "function" ? { loadPreview } : {}),
     retry,
     retainPreview,
     remove,