@agent-native/core 0.97.0 → 0.98.1

package/corpus/core/src/client/context-xray/ContextXRayPanel.tsx

@@ -121,8 +121,11 @@ export function ContextXRayPanel({
         </div>
         <div className="mt-2 h-1 overflow-hidden rounded-full bg-muted/70">
           <div
-            className="h-full rounded-full bg-foreground transition-[width] duration-200"
-            style={{ width: `${pct}%` }}
+            className="h-full rounded-full bg-foreground origin-left transition-transform duration-200"
+            style={{
+              transform: `scaleX(${Math.min(1, pct / 100)})`,
+              width: "100%",
+            }}
           />
         </div>
         <div className="mt-1.5 flex flex-wrap items-center gap-x-2 gap-y-1 text-[11px] text-muted-foreground">

package/corpus/core/src/client/extensions/ExtensionEditor.tsx

@@ -28,6 +28,7 @@ import {
   deleteOrHideExtension,
   invalidateExtensionRemoval,
 } from "./delete-extension.js";
+import { ExtensionQueryErrorState } from "./ExtensionQueryErrorState.js";
 
 interface SlotDeclaration {
   id: string;
@@ -61,19 +62,22 @@ export function ExtensionEditor({ extensionId }: ExtensionEditorProps) {
   const [menuOpen, setMenuOpen] = useState(false);
   const [confirmingDelete, setConfirmingDelete] = useState(false);
 
-  const { data: slots = [] } = useQuery<SlotDeclaration[]>({
+  const slotsQuery = useQuery<SlotDeclaration[]>({
     queryKey: ["extension-slots", extensionId],
     queryFn: async () => {
       const res = await fetch(
         agentNativePath(`/_agent-native/slots/extension/${extensionId}`),
       );
-      if (!res.ok) return [];
+      if (!res.ok) {
+        throw new Error(`Failed to load extension slots (${res.status})`);
+      }
       return res.json();
     },
     enabled: isEdit && menuOpen,
   });
+  const slots = slotsQuery.data ?? [];
 
-  const { data: existingTool } = useQuery<Extension>({
+  const existingToolQuery = useQuery<Extension>({
     queryKey: ["extension", extensionId],
     queryFn: async () => {
       const res = await fetch(
@@ -84,6 +88,7 @@ export function ExtensionEditor({ extensionId }: ExtensionEditorProps) {
     },
     enabled: isEdit,
   });
+  const existingTool = existingToolQuery.data;
 
   useEffect(() => {
     if (existingTool) {
@@ -175,6 +180,26 @@ export function ExtensionEditor({ extensionId }: ExtensionEditorProps) {
     }
   };
 
+  if (isEdit && existingToolQuery.isLoading) {
+    return (
+      <div className="flex h-full flex-col">
+        <div className="h-12 shrink-0 border-b" />
+        <div className="flex-1 bg-muted/20 animate-pulse" />
+      </div>
+    );
+  }
+
+  if (isEdit && existingToolQuery.isError) {
+    return (
+      <ExtensionQueryErrorState
+        className="h-full min-h-[20rem]"
+        message={t("extensions.loadError")}
+        onRetry={() => void existingToolQuery.refetch()}
+        retrying={existingToolQuery.isFetching}
+      />
+    );
+  }
+
   return (
     <TooltipProvider delayDuration={200}>
       <div className="flex h-full flex-col">
@@ -243,7 +268,15 @@ export function ExtensionEditor({ extensionId }: ExtensionEditorProps) {
                         <p className="text-[12px] font-medium">
                           {t("extensions.appearsIn")}
                         </p>
-                        {slots.length === 0 ? (
+                        {slotsQuery.isError ? (
+                          <ExtensionQueryErrorState
+                            compact
+                            className="px-0"
+                            message={t("extensions.widgetAreasLoadError")}
+                            onRetry={() => void slotsQuery.refetch()}
+                            retrying={slotsQuery.isFetching}
+                          />
+                        ) : slots.length === 0 ? (
                           <p className="text-[11px] text-muted-foreground/70 mt-0.5">
                             {t("extensions.noWidgetAreas")}
                           </p>

package/corpus/core/src/client/extensions/ExtensionQueryErrorState.tsx

@@ -0,0 +1,47 @@
+import { IconRefresh } from "@tabler/icons-react";
+
+import { useT } from "../i18n.js";
+import { cn } from "../utils.js";
+
+export function ExtensionQueryErrorState({
+  message,
+  onRetry,
+  retrying = false,
+  compact = false,
+  className,
+}: {
+  message: string;
+  onRetry: () => void;
+  retrying?: boolean;
+  compact?: boolean;
+  className?: string;
+}) {
+  const t = useT();
+
+  return (
+    <div
+      role="alert"
+      className={cn(
+        "flex items-center text-destructive",
+        compact
+          ? "gap-2 px-2 py-1.5 text-[11px]"
+          : "flex-col justify-center gap-3 px-4 py-8 text-center text-sm",
+        className,
+      )}
+    >
+      <span>{message}</span>
+      <button
+        type="button"
+        onClick={onRetry}
+        disabled={retrying}
+        className={cn(
+          "inline-flex shrink-0 items-center justify-center gap-1.5 rounded-md border border-border text-foreground hover:bg-accent disabled:pointer-events-none disabled:opacity-60",
+          compact ? "px-2 py-1 text-[11px]" : "px-3 py-1.5 text-xs",
+        )}
+      >
+        <IconRefresh className={cn("size-3.5", retrying && "animate-spin")} />
+        {t("extensions.retry")}
+      </button>
+    </div>
+  );
+}

package/corpus/core/src/client/extensions/ExtensionSlot.tsx

@@ -17,6 +17,7 @@ import {
 } from "../components/ui/tooltip.js";
 import { useT } from "../i18n.js";
 import { EmbeddedExtension } from "./EmbeddedExtension.js";
+import { ExtensionQueryErrorState } from "./ExtensionQueryErrorState.js";
 
 interface SlotInstall {
   installId: string;
@@ -70,7 +71,8 @@ export function ExtensionSlot({
   className,
   toolClassName,
 }: ExtensionSlotProps) {
-  const { data: installs = [], isLoading } = useQuery<SlotInstall[]>({
+  const t = useT();
+  const installsQuery = useQuery<SlotInstall[]>({
     queryKey: ["slot-installs", id],
     queryFn: async () => {
       const res = await fetch(
@@ -78,15 +80,29 @@ export function ExtensionSlot({
           `/_agent-native/slots/${encodeURIComponent(id)}/installs`,
         ),
       );
-      if (!res.ok) return [];
+      if (!res.ok)
+        throw new Error(`Failed to load slot installs (${res.status})`);
       return res.json();
     },
   });
+  const installs = installsQuery.data ?? [];
 
-  if (isLoading) {
+  if (installsQuery.isLoading) {
     return null;
   }
 
+  if (installsQuery.isError) {
+    return (
+      <ExtensionQueryErrorState
+        compact
+        className={className}
+        message={t("extensions.widgetsLoadError")}
+        onRetry={() => void installsQuery.refetch()}
+        retrying={installsQuery.isFetching}
+      />
+    );
+  }
+
   if (installs.length === 0) {
     if (!showEmptyAffordance) return null;
     return (
@@ -114,7 +130,7 @@ export function ExtensionSlot({
 function SlotEmptyAffordance({ slotId }: { slotId: string }) {
   const t = useT();
   const [open, setOpen] = useState(false);
-  const { data: available = [], isLoading } = useQuery<AvailableTool[]>({
+  const availableQuery = useQuery<AvailableTool[]>({
     queryKey: ["slot-available", slotId],
     queryFn: async () => {
       const res = await fetch(
@@ -122,11 +138,14 @@ function SlotEmptyAffordance({ slotId }: { slotId: string }) {
           `/_agent-native/slots/${encodeURIComponent(slotId)}/available`,
         ),
       );
-      if (!res.ok) return [];
+      if (!res.ok) {
+        throw new Error(`Failed to load available extensions (${res.status})`);
+      }
       return res.json();
     },
     enabled: open,
   });
+  const available = availableQuery.data ?? [];
   const queryClient = useQueryClient();
 
   const install = async (extensionId: string) => {
@@ -210,16 +229,26 @@ function SlotEmptyAffordance({ slotId }: { slotId: string }) {
           </p>
         </div>
         <div className="max-h-72 overflow-y-auto py-1">
-          {isLoading && (
+          {availableQuery.isLoading && (
             <div className="px-3 py-3 text-[12px] text-muted-foreground/60">
               {t("extensions.loading")}
             </div>
           )}
-          {!isLoading && available.length === 0 && (
-            <div className="px-3 py-3 text-[12px] text-muted-foreground/60">
-              {t("extensions.noWidgetsAvailable")}
-            </div>
+          {availableQuery.isError && (
+            <ExtensionQueryErrorState
+              compact
+              message={t("extensions.widgetsLoadError")}
+              onRetry={() => void availableQuery.refetch()}
+              retrying={availableQuery.isFetching}
+            />
           )}
+          {!availableQuery.isLoading &&
+            !availableQuery.isError &&
+            available.length === 0 && (
+              <div className="px-3 py-3 text-[12px] text-muted-foreground/60">
+                {t("extensions.noWidgetsAvailable")}
+              </div>
+            )}
           {available.map((extension) => (
             <button
               key={extension.extensionId}

package/corpus/core/src/client/extensions/ExtensionViewer.tsx

@@ -34,6 +34,7 @@ import {
 } from "../components/ui/tooltip.js";
 import { PromptComposer } from "../composer/PromptComposer.js";
 import { isEmbedMcpChatBridgeActive } from "../embed-auth.js";
+import { useT } from "../i18n.js";
 import { ShareButton } from "../sharing/ShareButton.js";
 import {
   deleteOrHideExtension,
@@ -44,6 +45,7 @@ import {
   extensionLoadErrorStatus,
   shouldRetryExtensionLoad,
 } from "./extension-load-error.js";
+import { ExtensionQueryErrorState } from "./ExtensionQueryErrorState.js";
 import {
   isAllowedExtensionPath,
   sanitizeExtensionRequestOptions,
@@ -577,6 +579,7 @@ function ExtensionHistoryPopover({
   onRestored?: () => void;
   onOpenChange?: (open: boolean) => void;
 }) {
+  const t = useT();
   const [open, setOpen] = useState(false);
   const [selectedVersion, setSelectedVersion] = useState<number | null>(null);
   const [restoringVersion, setRestoringVersion] = useState<number | null>(null);
@@ -698,6 +701,13 @@ function ExtensionHistoryPopover({
                   <IconLoader2 className="h-3.5 w-3.5 animate-spin" />
                   Loading history
                 </div>
+              ) : historyQuery.isError ? (
+                <ExtensionQueryErrorState
+                  compact
+                  message={t("extensions.historyLoadError")}
+                  onRetry={() => void historyQuery.refetch()}
+                  retrying={historyQuery.isFetching}
+                />
               ) : history.length === 0 ? (
                 <p className="px-2 py-3 text-xs text-muted-foreground">
                   No history yet.
@@ -767,9 +777,11 @@ function ExtensionHistoryPopover({
                   Loading diff
                 </div>
               ) : detailQuery.isError ? (
-                <div className="p-4 text-xs text-destructive">
-                  Could not load this version.
-                </div>
+                <ExtensionQueryErrorState
+                  message={t("extensions.versionLoadError")}
+                  onRetry={() => void detailQuery.refetch()}
+                  retrying={detailQuery.isFetching}
+                />
               ) : compactedDiff.length === 0 ? (
                 <div className="p-4 text-xs text-muted-foreground">
                   No content changes in this version.
@@ -802,6 +814,7 @@ function ExtensionHistoryPopover({
 }
 
 export function ExtensionViewer({ extensionId }: ExtensionViewerProps) {
+  const t = useT();
   const location = useLocation();
   const navigate = useNavigate();
   const [isDark, setIsDark] = useState(false);
@@ -1112,6 +1125,8 @@ export function ExtensionViewer({ extensionId }: ExtensionViewerProps) {
     failureReason: extensionFailureReason,
     isFetching,
     isLoading,
+    isError,
+    refetch,
   } = useQuery<Extension>({
     queryKey: ["extension", extensionId],
     queryFn: async () => {
@@ -1237,6 +1252,17 @@ export function ExtensionViewer({ extensionId }: ExtensionViewerProps) {
     );
   }
 
+  if (isError && !latestFetchDenied) {
+    return (
+      <ExtensionQueryErrorState
+        className="h-full min-h-[20rem]"
+        message={t("extensions.loadError")}
+        onRetry={() => void refetch()}
+        retrying={isFetching}
+      />
+    );
+  }
+
   if (latestFetchDenied || !extension) {
     return <ExtensionUnavailableState status={unavailableStatus} />;
   }
@@ -1414,6 +1440,7 @@ function ToolMoreMenu({
   sourceMode?: "database" | "local-files";
   onOpenChange?: (open: boolean) => void;
 }) {
+  const t = useT();
   const [open, setOpen] = useState(false);
   const [confirmingDelete, setConfirmingDelete] = useState(false);
   const queryClient = useQueryClient();
@@ -1423,17 +1450,20 @@ function ToolMoreMenu({
     onOpenChange?.(v);
   };
 
-  const { data: slots = [] } = useQuery<SlotDeclaration[]>({
+  const slotsQuery = useQuery<SlotDeclaration[]>({
     queryKey: ["extension-slots", extensionId],
     queryFn: async () => {
       const res = await fetch(
         agentNativePath(`/_agent-native/slots/extension/${extensionId}`),
       );
-      if (!res.ok) return [];
+      if (!res.ok) {
+        throw new Error(`Failed to load extension slots (${res.status})`);
+      }
       return res.json();
     },
     enabled: open,
   });
+  const slots = slotsQuery.data ?? [];
 
   const closeMenu = () => {
     setOpenAndNotify(false);
@@ -1497,7 +1527,15 @@ function ToolMoreMenu({
           <>
             <div className="px-3 py-2 border-b border-border/40">
               <p className="text-[12px] font-medium">Appears in</p>
-              {slots.length === 0 ? (
+              {slotsQuery.isError ? (
+                <ExtensionQueryErrorState
+                  compact
+                  className="px-0"
+                  message={t("extensions.widgetAreasLoadError")}
+                  onRetry={() => void slotsQuery.refetch()}
+                  retrying={slotsQuery.isFetching}
+                />
+              ) : slots.length === 0 ? (
                 <p className="text-[11px] text-muted-foreground/70 mt-0.5">
                   Not installed in any widget areas. Ask the agent to add it
                   somewhere.

package/corpus/core/src/client/extensions/ExtensionsListPage.tsx

@@ -37,6 +37,7 @@ import {
   applyToolsOrder,
   getToolsOrder,
 } from "./extension-order.js";
+import { ExtensionQueryErrorState } from "./ExtensionQueryErrorState.js";
 
 interface Extension {
   id: string;
@@ -128,7 +129,7 @@ export function ExtensionsListPage() {
     };
   }, []);
 
-  const { data: extensions, isLoading } = useQuery<Extension[]>({
+  const extensionsQuery = useQuery<Extension[]>({
     queryKey: ["extensions", { includeGloballyHidden: showGloballyHidden }],
     queryFn: async () => {
       const res = await fetch(
@@ -138,10 +139,11 @@ export function ExtensionsListPage() {
             : "/_agent-native/extensions",
         ),
       );
-      if (!res.ok) return [];
+      if (!res.ok) throw new Error(`Failed to load extensions (${res.status})`);
       return res.json();
     },
   });
+  const extensions = extensionsQuery.data;
 
   const toolList =
     toolOrderState.length > 0
@@ -247,7 +249,7 @@ export function ExtensionsListPage() {
       </header>
 
       <div className="flex-1 overflow-auto px-5 py-8 sm:px-8 sm:py-10">
-        {isLoading ? (
+        {extensionsQuery.isLoading ? (
           <div className="grid grid-cols-1 gap-5 sm:grid-cols-2 lg:grid-cols-3">
             {Array.from({ length: 6 }).map((_, i) => (
               <div
@@ -260,6 +262,13 @@ export function ExtensionsListPage() {
               </div>
             ))}
           </div>
+        ) : extensionsQuery.isError ? (
+          <ExtensionQueryErrorState
+            className="min-h-[calc(100vh-9rem)]"
+            message={t("extensions.loadError")}
+            onRetry={() => void extensionsQuery.refetch()}
+            retrying={extensionsQuery.isFetching}
+          />
         ) : toolList.length === 0 ? (
           <div className="flex min-h-[calc(100vh-9rem)] flex-col items-center justify-start px-2 pb-12 pt-[clamp(5rem,18vh,11rem)] sm:pb-16">
             <div className="mx-auto flex w-full max-w-[34rem] flex-col gap-7">

package/corpus/core/src/client/extensions/ExtensionsSidebarSection.tsx

@@ -11,6 +11,7 @@ import {
   IconTool,
   IconEye,
   IconEyeOff,
+  IconHelpCircle,
 } from "@tabler/icons-react";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { useState, useCallback, useMemo } from "react";
@@ -62,6 +63,7 @@ import {
   extensionPopularityOf,
   useExtensionPopularity,
 } from "./extension-popularity.js";
+import { ExtensionQueryErrorState } from "./ExtensionQueryErrorState.js";
 
 interface Extension {
   id: string;
@@ -114,6 +116,7 @@ type ExtensionsCopy = {
   delete: string;
   showLess: string;
   showMore: string;
+  loadError: string;
 };
 
 const EXTENSIONS_COPY: Record<LocaleCode, ExtensionsCopy> = {
@@ -149,6 +152,7 @@ const EXTENSIONS_COPY: Record<LocaleCode, ExtensionsCopy> = {
     delete: "Delete",
     showLess: "show less",
     showMore: "show more",
+    loadError: "Couldn't load extensions.",
   },
   "zh-CN": {
     title: "扩展",
@@ -181,6 +185,7 @@ const EXTENSIONS_COPY: Record<LocaleCode, ExtensionsCopy> = {
     delete: "删除",
     showLess: "收起",
     showMore: "显示更多",
+    loadError: "无法加载扩展。",
   },
   "zh-TW": {
     title: "擴充功能",
@@ -214,6 +219,7 @@ const EXTENSIONS_COPY: Record<LocaleCode, ExtensionsCopy> = {
     delete: "刪除",
     showLess: "顯示較少",
     showMore: "顯示更多",
+    loadError: "無法載入擴充功能。",
   },
   "es-ES": {
     title: "Extensiones",
@@ -247,6 +253,7 @@ const EXTENSIONS_COPY: Record<LocaleCode, ExtensionsCopy> = {
     delete: "Eliminar",
     showLess: "mostrar menos",
     showMore: "mostrar más",
+    loadError: "No se pudieron cargar las extensiones.",
   },
   "fr-FR": {
     title: "Extensions",
@@ -280,6 +287,7 @@ const EXTENSIONS_COPY: Record<LocaleCode, ExtensionsCopy> = {
     delete: "Supprimer",
     showLess: "afficher moins",
     showMore: "afficher plus",
+    loadError: "Impossible de charger les extensions.",
   },
   "de-DE": {
     title: "Erweiterungen",
@@ -313,6 +321,7 @@ const EXTENSIONS_COPY: Record<LocaleCode, ExtensionsCopy> = {
     delete: "Löschen",
     showLess: "weniger anzeigen",
     showMore: "mehr anzeigen",
+    loadError: "Erweiterungen konnten nicht geladen werden.",
   },
   "ja-JP": {
     title: "拡張機能",
@@ -346,6 +355,7 @@ const EXTENSIONS_COPY: Record<LocaleCode, ExtensionsCopy> = {
     delete: "削除",
     showLess: "少なく表示",
     showMore: "さらに表示",
+    loadError: "拡張機能を読み込めませんでした。",
   },
   "ko-KR": {
     title: "확장",
@@ -379,6 +389,7 @@ const EXTENSIONS_COPY: Record<LocaleCode, ExtensionsCopy> = {
     delete: "삭제",
     showLess: "덜 보기",
     showMore: "더 보기",
+    loadError: "확장 프로그램을 불러올 수 없습니다.",
   },
   "pt-BR": {
     title: "Extensões",
@@ -412,6 +423,7 @@ const EXTENSIONS_COPY: Record<LocaleCode, ExtensionsCopy> = {
     delete: "Excluir",
     showLess: "mostrar menos",
     showMore: "mostrar mais",
+    loadError: "Não foi possível carregar as extensões.",
   },
   "hi-IN": {
     title: "एक्सटेंशन",
@@ -445,6 +457,7 @@ const EXTENSIONS_COPY: Record<LocaleCode, ExtensionsCopy> = {
     delete: "हटाएं",
     showLess: "कम दिखाएं",
     showMore: "और दिखाएं",
+    loadError: "एक्सटेंशन लोड नहीं हो सके।",
   },
   "ar-SA": {
     title: "الإضافات",
@@ -478,6 +491,7 @@ const EXTENSIONS_COPY: Record<LocaleCode, ExtensionsCopy> = {
     delete: "حذف",
     showLess: "إظهار أقل",
     showMore: "إظهار المزيد",
+    loadError: "تعذر تحميل الإضافات.",
   },
 };
 
@@ -567,7 +581,7 @@ function ExtensionSortMenu({
           <DropdownMenuTrigger asChild>
             <button
               type="button"
-              className="inline-flex h-6 w-6 shrink-0 items-center justify-center rounded-md text-muted-foreground/45 opacity-0 transition-all hover:bg-accent hover:text-foreground focus:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring group-hover/extensions-section:opacity-100"
+              className="inline-flex h-6 w-6 shrink-0 items-center justify-center rounded-md text-muted-foreground/45 opacity-0 transition-[opacity,color,background-color] hover:bg-accent hover:text-foreground focus:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring group-hover/extensions-section:opacity-100"
               aria-label={copy.sortOptions}
             >
               <IconFilter className="h-3.5 w-3.5" />
@@ -638,7 +652,7 @@ export function ExtensionsSidebarSection() {
   const [showAllExtensions, setShowAllExtensions] = useState(false);
   const [showGloballyHidden, setShowGloballyHidden] = useState(false);
 
-  const { data: extensions, isLoading } = useQuery<Extension[]>({
+  const extensionsQuery = useQuery<Extension[]>({
     queryKey: ["extensions", { includeGloballyHidden: showGloballyHidden }],
     queryFn: async () => {
       const res = await fetch(
@@ -648,10 +662,11 @@ export function ExtensionsSidebarSection() {
             : "/_agent-native/extensions",
         ),
       );
-      if (!res.ok) return [];
+      if (!res.ok) throw new Error(`Failed to load extensions (${res.status})`);
       return res.json();
     },
   });
+  const extensions = extensionsQuery.data;
 
   const toggleFavorite = useCallback((id: string) => {
     setFavoriteIds((prev) => {
@@ -870,7 +885,7 @@ export function ExtensionsSidebarSection() {
       <div className="relative min-w-0 py-1">
         <div
           className={cn(
-            "group/extensions-section relative flex w-full min-w-0 items-center rounded-md text-sm font-medium transition-all hover:text-primary",
+            "group/extensions-section relative flex w-full min-w-0 items-center rounded-md text-sm font-medium transition-[opacity,color,background-color] hover:text-primary",
             location.pathname.startsWith("/extensions")
               ? "text-sidebar-accent-foreground"
               : "text-muted-foreground hover:bg-sidebar-accent/50",
@@ -940,7 +955,7 @@ export function ExtensionsSidebarSection() {
               <PopoverTrigger asChild>
                 <button
                   type="button"
-                  className="pointer-events-none inline-flex h-6 w-6 shrink-0 cursor-pointer items-center justify-center rounded-md text-muted-foreground/70 opacity-0 transition-all hover:bg-accent hover:text-accent-foreground focus-visible:pointer-events-auto focus-visible:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring group-hover/extensions-section:pointer-events-auto group-hover/extensions-section:opacity-100 group-focus-within/extensions-section:pointer-events-auto group-focus-within/extensions-section:opacity-100 data-[state=open]:pointer-events-auto data-[state=open]:opacity-100"
+                  className="pointer-events-none inline-flex h-6 w-6 shrink-0 cursor-pointer items-center justify-center rounded-md text-muted-foreground/70 opacity-0 transition-[opacity,color,background-color] hover:bg-accent hover:text-accent-foreground focus-visible:pointer-events-auto focus-visible:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring group-hover/extensions-section:pointer-events-auto group-hover/extensions-section:opacity-100 group-focus-within/extensions-section:pointer-events-auto group-focus-within/extensions-section:opacity-100 data-[state=open]:pointer-events-auto data-[state=open]:opacity-100"
                   aria-label={copy.newExtension}
                 >
                   <IconPlus className="h-3.5 w-3.5" />
@@ -950,11 +965,27 @@ export function ExtensionsSidebarSection() {
                 side="right"
                 align="start"
                 collisionPadding={8}
-                className="relative z-[360] w-[min(420px,calc(100vw-16px))] p-3"
+                className="relative z-[360] w-[min(420px,calc(100vw-16px))] px-2 pb-2 pt-3"
               >
-                <p className="px-1 pb-2 text-sm font-semibold text-foreground">
-                  {copy.newExtension}
-                </p>
+                <div className="flex items-center justify-between gap-2 ps-1 pb-2">
+                  <p className="text-sm font-semibold text-foreground">
+                    {copy.newExtension}
+                  </p>
+                  <Tooltip>
+                    <TooltipTrigger asChild>
+                      <a
+                        href="https://agent-native.com/docs/extensions"
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        className="inline-flex size-6 shrink-0 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                        aria-label={copy.learnMore}
+                      >
+                        <IconHelpCircle className="size-4" />
+                      </a>
+                    </TooltipTrigger>
+                    <TooltipContent>{copy.learnMore}</TooltipContent>
+                  </Tooltip>
+                </div>
                 <PromptComposer
                   autoFocus
                   placeholder={copy.createPlaceholder}
@@ -981,7 +1012,7 @@ export function ExtensionsSidebarSection() {
         </div>
 
         {extensionsOpen &&
-          (isLoading ? (
+          (extensionsQuery.isLoading ? (
             <div className="min-w-0 space-y-0.5 px-0.5">
               {[1, 2, 3].map((i) => (
                 <div
@@ -995,6 +1026,13 @@ export function ExtensionsSidebarSection() {
                 </div>
               ))}
             </div>
+          ) : extensionsQuery.isError ? (
+            <ExtensionQueryErrorState
+              compact
+              message={copy.loadError}
+              onRetry={() => void extensionsQuery.refetch()}
+              retrying={extensionsQuery.isFetching}
+            />
           ) : sortedTools.length === 0 ? null : (
             <div className="min-w-0 space-y-0.5 px-0.5">
               {visibleTools.map((extension) => {
@@ -1054,7 +1092,7 @@ export function ExtensionsSidebarSection() {
                             setDraggingId(null);
                             setDragOverId(null);
                           }}
-                          className="-ml-2 cursor-grab rounded p-0.5 text-muted-foreground/30 opacity-0 transition-colors hover:text-muted-foreground/70 active:cursor-grabbing group-hover/extension:opacity-100 group-focus-within/extension:opacity-100"
+                          className="-ml-2 cursor-grab rounded p-0.5 text-muted-foreground/30 opacity-0 transition-[opacity,color] hover:text-muted-foreground/70 active:cursor-grabbing group-hover/extension:opacity-100 group-focus-within/extension:opacity-100"
                           aria-label={copy.reorder(extension.name)}
                         >
                           <IconGripVertical className="h-3 w-3" />