@agent-native/core 0.117.2 → 0.118.0

package/src/client/settings/SettingsPanel.tsx

@@ -1,4 +1,9 @@
-import * as SelectPrimitive from "@radix-ui/react-select";
+import {
+  Checkbox,
+  Picker,
+  TextField,
+} from "@agent-native/toolkit/design-system";
+import { Button as ToolkitButton } from "@agent-native/toolkit/ui/button";
 import {
   IconChevronDown,
   IconChevronRight,
@@ -35,6 +40,7 @@ import React, {
   useMemo,
   useRef,
 } from "react";
+import { Link } from "react-router";
 
 import { PROVIDER_ENV_PLACEHOLDERS } from "../../agent/engine/provider-env-vars.js";
 import type { UserProfile } from "../../user-profile/shared.js";
@@ -62,7 +68,6 @@ import {
   AGENT_SETTINGS_SECTIONS,
   ALL_SETTINGS_SECTIONS,
   CONNECTION_SETTINGS_SECTIONS,
-  SETTINGS_SECTION_IDS,
   WORKSPACE_SETTINGS_SECTIONS,
   getAgentSettingsSearchTabs,
   type SettingsSectionId,
@@ -84,8 +89,28 @@ import {
   useBuilderConnectFlow,
   useBuilderStatus,
 } from "./useBuilderStatus.js";
+import {
+  settingsSectionDomId,
+  useSettingsPanelController,
+} from "./useSettingsPanelController.js";
 import { VoiceTranscriptionSection } from "./VoiceTranscriptionSection.js";
 
+const Button = React.forwardRef<
+  HTMLButtonElement,
+  React.ComponentPropsWithoutRef<typeof ToolkitButton>
+>(({ className, ...props }, ref) => (
+  <ToolkitButton
+    ref={ref}
+    variant="ghost"
+    className={cn(
+      "h-auto p-0 hover:bg-transparent hover:text-inherit active:scale-100 [&_svg]:!size-auto",
+      className,
+    )}
+    {...props}
+  />
+));
+Button.displayName = "SettingsPrimitiveButton";
+
 const IntegrationsPanel = lazy(() =>
   import("../integrations/IntegrationsPanel.js").then((m) => ({
     default: m.IntegrationsPanel,
@@ -189,7 +214,6 @@ function SettingsSelect({
 }) {
   const isPage = useSettingsSurface() === "page";
   const controlStyle = isPage ? CONTROL_STYLE_PAGE : CONTROL_STYLE;
-  const selected = options.find((option) => option.value === value);
 
   return (
     <div className="space-y-1.5">
@@ -197,69 +221,27 @@ function SettingsSelect({
         <p className={fieldLabelClass(isPage)}>{label}</p>
         {labelAdornment}
       </div>
-      <SelectPrimitive.Root
+      <Picker
+        mode="select"
+        options={options.map((option) => ({
+          value: option.value,
+          label: option.label,
+          description: option.description,
+          textValue: option.label,
+        }))}
         value={value}
-        onValueChange={onValueChange}
+        onChange={(next) => {
+          if (next != null) onValueChange(String(next));
+        }}
         disabled={disabled}
-      >
-        <SelectPrimitive.Trigger
-          className={cn(
-            "flex w-full items-center justify-between rounded-md border border-border bg-background px-3 text-start text-foreground outline-none transition-colors hover:bg-accent/40 data-[placeholder]:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-60",
-            isPage ? "h-10 text-sm" : "h-9 text-[12px]",
-          )}
-          aria-label={label}
-          style={controlStyle}
-        >
-          <SelectPrimitive.Value>
-            {selected?.label ?? value}
-          </SelectPrimitive.Value>
-          <SelectPrimitive.Icon asChild>
-            <IconChevronDown size={16} className="text-muted-foreground" />
-          </SelectPrimitive.Icon>
-        </SelectPrimitive.Trigger>
-        <SelectPrimitive.Portal>
-          <SelectPrimitive.Content
-            position="popper"
-            sideOffset={6}
-            className="z-[9999] w-[var(--radix-select-trigger-width)] overflow-hidden rounded-lg border border-border bg-popover shadow-lg"
-          >
-            <SelectPrimitive.Viewport className="p-1">
-              {options.map((option) => (
-                <SelectPrimitive.Item
-                  key={option.value}
-                  value={option.value}
-                  className={cn(
-                    "relative flex w-full cursor-pointer select-none items-start gap-2 rounded-md px-8 outline-none data-[highlighted]:bg-accent/60 data-[state=checked]:bg-accent/40",
-                    isPage ? "py-2.5 text-sm" : "py-2.5 text-[12px]",
-                  )}
-                  style={controlStyle}
-                >
-                  <span className="absolute start-2 top-2.5 flex h-4 w-4 items-center justify-center text-muted-foreground">
-                    <SelectPrimitive.ItemIndicator>
-                      <IconCheck size={14} />
-                    </SelectPrimitive.ItemIndicator>
-                  </span>
-                  <div className="flex min-w-0 flex-col">
-                    <SelectPrimitive.ItemText>
-                      <span className="text-foreground">{option.label}</span>
-                    </SelectPrimitive.ItemText>
-                    {option.description ? (
-                      <span
-                        className={cn(
-                          "mt-0.5 leading-relaxed text-muted-foreground",
-                          isPage ? "text-xs" : "text-[11px]",
-                        )}
-                      >
-                        {option.description}
-                      </span>
-                    ) : null}
-                  </div>
-                </SelectPrimitive.Item>
-              ))}
-            </SelectPrimitive.Viewport>
-          </SelectPrimitive.Content>
-        </SelectPrimitive.Portal>
-      </SelectPrimitive.Root>
+        aria-label={label}
+        placeholder={value}
+        style={controlStyle}
+        className={cn(
+          "w-full text-start text-foreground",
+          isPage ? "text-sm" : "text-[12px]",
+        )}
+      />
     </div>
   );
 }
@@ -375,28 +357,34 @@ function DisconnectBuilderButton() {
   if (phase === "armed") {
     return (
       <>
-        <button
+        <Button
           type="button"
+          intent="danger"
+          emphasis="solid"
           onClick={handleDisconnectClick}
           className="inline-flex items-center gap-1 rounded border border-destructive/40 bg-destructive/10 px-2 py-0.5 text-[10px] font-medium text-destructive hover:bg-destructive/20"
         >
           Confirm disconnect
-        </button>
-        <button
+        </Button>
+        <Button
           type="button"
+          intent="neutral"
+          emphasis="outline"
           onClick={handleCancel}
           className="inline-flex items-center gap-1 rounded border border-border px-2 py-0.5 text-[10px] text-muted-foreground hover:text-foreground hover:bg-accent/40"
         >
           Cancel
-        </button>
+        </Button>
       </>
     );
   }
 
   return (
     <>
-      <button
+      <Button
         type="button"
+        intent="danger"
+        emphasis="outline"
         onClick={handleDisconnectClick}
         disabled={phase === "busy"}
         className="inline-flex items-center gap-1 rounded border border-border px-2 py-0.5 text-[10px] text-muted-foreground hover:text-foreground hover:bg-accent/40 disabled:opacity-60 disabled:cursor-wait"
@@ -410,7 +398,7 @@ function DisconnectBuilderButton() {
         ) : (
           "Disconnect"
         )}
-      </button>
+      </Button>
       {err && <span className="text-[10px] text-destructive">{err}</span>}
     </>
   );
@@ -485,8 +473,10 @@ function UseBuilderCard({
         {connectUrl || credentialSource !== "env" ? (
           <div className="flex items-center gap-2 mt-2.5">
             {connectUrl && (
-              <button
+              <Button
                 type="button"
+                intent="neutral"
+                emphasis="ghost"
                 onClick={() =>
                   builderFlow.start({ trackingSource, trackingFlow })
                 }
@@ -499,7 +489,7 @@ function UseBuilderCard({
                     ? "Connect account"
                     : "Reconnect"}
                 <IconExternalLink size={isPage ? 14 : 10} />
-              </button>
+              </Button>
             )}
             {credentialSource !== "env" ? <DisconnectBuilderButton /> : null}
           </div>
@@ -511,13 +501,14 @@ function UseBuilderCard({
   if (!connectUrl) return null;
 
   return (
-    <button
+    <Button
       type="button"
       onClick={() => builderFlow.start({ trackingSource, trackingFlow })}
       disabled={builderFlow.connecting}
       className={cn(
         "block w-full rounded-md border border-border text-start no-underline bg-gradient-to-br from-teal-500/10 via-transparent to-transparent hover:border-foreground/30 transition-colors disabled:cursor-wait disabled:opacity-70",
         isPage ? "px-4 py-3.5" : "px-3 py-3",
+        isPage ? "[&_svg]:!size-4" : "[&_svg]:!size-3.5",
       )}
     >
       <div className="flex items-start gap-2.5">
@@ -565,7 +556,7 @@ function UseBuilderCard({
           className="shrink-0 text-muted-foreground mt-0.5"
         />
       </div>
-    </button>
+    </Button>
   );
 }
 
@@ -766,19 +757,21 @@ export function AppDefaultModelField({
   return (
     <div className="space-y-1.5">
       <p className={fieldLabelClass(isPage)}>Model</p>
-      <input
-        type="text"
-        list={`app-model-suggestions-${engine}`}
+      <TextField
         value={value}
+        onChange={onValueChange}
         disabled={disabled}
-        onChange={(event) => onValueChange(event.target.value)}
+        list={`app-model-suggestions-${engine}`}
         onKeyDown={(event) => {
           if (event.key === "Enter") onEnter?.();
         }}
         placeholder={defaultModel ?? "model-id"}
-        spellCheck={false}
         autoComplete="off"
-        className={cn(textInputClass(isPage), "disabled:opacity-60")}
+        aria-label="Model"
+        className={cn(
+          "w-full disabled:opacity-60",
+          isPage ? "text-sm" : "text-[12px]",
+        )}
         style={isPage ? CONTROL_STYLE_PAGE : CONTROL_STYLE}
       />
       {modelOptions.length > 0 && (
@@ -1180,7 +1173,7 @@ function LLMSectionInner({
 
                 {isOpenAiEngine && (
                   <div className="border-t border-border/70 pt-2">
-                    <button
+                    <Button
                       type="button"
                       onClick={() => setAdvancedOpen((v) => !v)}
                       className="flex w-full cursor-pointer items-center justify-between gap-2 rounded px-0.5 py-1 text-left hover:text-foreground"
@@ -1199,7 +1192,7 @@ function LLMSectionInner({
                       <span className="truncate text-[10px] text-muted-foreground">
                         OpenAI-compatible endpoint
                       </span>
-                    </button>
+                    </Button>
 
                     {advancedOpen && (
                       <div className="mt-1.5 space-y-1.5">
@@ -1238,21 +1231,23 @@ function LLMSectionInner({
                         </p>
                         {baseUrlConfigured && (
                           <label className="flex items-center gap-1.5 text-[10px] text-muted-foreground">
-                            <input
-                              type="checkbox"
+                            <Checkbox
                               checked={clearBaseUrl}
-                              onChange={(e) => {
-                                setClearBaseUrl(e.target.checked);
-                                if (e.target.checked) setBaseUrl("");
+                              onChange={(checked) => {
+                                setClearBaseUrl(checked);
+                                if (checked) setBaseUrl("");
                               }}
-                              className="h-3 w-3 accent-current"
+                              aria-label="Clear saved endpoint override"
+                              className="shrink-0"
                             />
                             Clear saved endpoint override
                           </label>
                         )}
                         {envVar && envConfigured && endpointChanged && (
-                          <button
+                          <Button
                             type="button"
+                            intent="neutral"
+                            emphasis="solid"
                             onClick={handleSave}
                             disabled={saving}
                             className="rounded bg-accent px-2.5 py-1 text-[10px] font-medium text-foreground hover:bg-accent/80 disabled:opacity-40"
@@ -1264,7 +1259,7 @@ function LLMSectionInner({
                             ) : (
                               "Save endpoint"
                             )}
-                          </button>
+                          </Button>
                         )}
                       </div>
                     )}
@@ -1294,7 +1289,9 @@ function LLMSectionInner({
                       className={cn(textInputClass(isPage), "flex-1")}
                       style={isPage ? CONTROL_STYLE_PAGE : undefined}
                     />
-                    <button
+                    <Button
+                      intent="primary"
+                      emphasis="solid"
                       onClick={handleSave}
                       disabled={!providerSettingsChanged || saving}
                       className={pillButtonClass(isPage, "solid")}
@@ -1309,12 +1306,14 @@ function LLMSectionInner({
                       ) : (
                         "Save"
                       )}
-                    </button>
+                    </Button>
                   </div>
                 ) : null}
 
                 <div className="flex items-center gap-2">
-                  <button
+                  <Button
+                    intent="neutral"
+                    emphasis="outline"
                     onClick={handleTest}
                     disabled={testing}
                     className={pillButtonClass(isPage, "outline")}
@@ -1330,19 +1329,23 @@ function LLMSectionInner({
                     ) : (
                       "Test"
                     )}
-                  </button>
+                  </Button>
                   {engineChanged && (
-                    <button
+                    <Button
+                      intent="primary"
+                      emphasis="solid"
                       onClick={handleApply}
                       className={pillButtonClass(isPage, "solid")}
                     >
                       Apply
-                    </button>
+                    </Button>
                   )}
                   {settingsStatus != null && (
                     <Tooltip>
                       <TooltipTrigger asChild>
-                        <button
+                        <Button
+                          intent="danger"
+                          emphasis="outline"
                           onClick={handleDisconnect}
                           className={cn(
                             pillButtonClass(isPage, "outline"),
@@ -1350,7 +1353,7 @@ function LLMSectionInner({
                           )}
                         >
                           Disconnect
-                        </button>
+                        </Button>
                       </TooltipTrigger>
                       <TooltipContent>
                         Clear the saved engine — the app will fall back to the
@@ -1663,8 +1666,10 @@ function AppModelDefaultsSectionInner({
               />
 
               <div className="flex items-center gap-1.5">
-                <button
+                <Button
                   type="button"
+                  intent="primary"
+                  emphasis="solid"
                   onClick={save}
                   disabled={!hasPendingChange || saving}
                   className={pillButtonClass(isPage, "solid")}
@@ -1679,15 +1684,17 @@ function AppModelDefaultsSectionInner({
                   ) : (
                     "Save"
                   )}
-                </button>
-                <button
+                </Button>
+                <Button
                   type="button"
+                  intent="neutral"
+                  emphasis="outline"
                   onClick={reset}
                   disabled={!settings.canUpdate || !hasAppDefault || saving}
                   className={pillButtonClass(isPage, "outline")}
                 >
                   Reset
-                </button>
+                </Button>
               </div>
             </div>
 
@@ -1839,27 +1846,17 @@ function EmailSectionInner({
         <SettingsSkeleton lines={2} />
       ) : (
         <div className="space-y-2">
-          <label className="block space-y-1">
-            <span
-              className={cn(
-                "uppercase tracking-wide text-muted-foreground",
-                noteTextClass(isPage),
-              )}
-            >
-              Provider
-            </span>
-            <select
-              value={emailProvider}
-              onChange={(e) =>
-                setEmailProvider(e.target.value as "resend" | "sendgrid")
-              }
-              className={cn(textInputClass(isPage), "w-full")}
-              style={isPage ? CONTROL_STYLE_PAGE : undefined}
-            >
-              <option value="resend">Resend</option>
-              <option value="sendgrid">SendGrid</option>
-            </select>
-          </label>
+          <SettingsSelect
+            label="Provider"
+            value={emailProvider}
+            options={[
+              { value: "resend", label: "Resend" },
+              { value: "sendgrid", label: "SendGrid" },
+            ]}
+            onValueChange={(value) =>
+              setEmailProvider(value as "resend" | "sendgrid")
+            }
+          />
 
           {emailProvider === "resend" ? (
             <ManualSetupCard
@@ -1889,7 +1886,9 @@ function EmailSectionInner({
                     placeholder="re_..."
                     className={emailInputCls}
                   />
-                  <button
+                  <Button
+                    intent="primary"
+                    emphasis="solid"
                     onClick={saveResend}
                     disabled={!resendKey.trim() || saving}
                     className={emailBtnCls}
@@ -1901,7 +1900,7 @@ function EmailSectionInner({
                     ) : (
                       "Save"
                     )}
-                  </button>
+                  </Button>
                 </div>
               )}
               {fromConfigured ? (
@@ -1927,7 +1926,9 @@ function EmailSectionInner({
                     className={emailInputCls}
                   />
                   {!resendConfigured ? null : (
-                    <button
+                    <Button
+                      intent="primary"
+                      emphasis="solid"
                       onClick={saveResend}
                       disabled={!fromAddr.trim() || saving}
                       className={emailBtnCls}
@@ -1939,7 +1940,7 @@ function EmailSectionInner({
                       ) : (
                         "Save"
                       )}
-                    </button>
+                    </Button>
                   )}
                 </div>
               )}
@@ -1972,7 +1973,9 @@ function EmailSectionInner({
                     placeholder="SG...."
                     className={emailInputCls}
                   />
-                  <button
+                  <Button
+                    intent="primary"
+                    emphasis="solid"
                     onClick={saveSendgrid}
                     disabled={!sendgridKey.trim() || saving}
                     className={emailBtnCls}
@@ -1984,7 +1987,7 @@ function EmailSectionInner({
                     ) : (
                       "Save"
                     )}
-                  </button>
+                  </Button>
                 </div>
               )}
               {fromConfigured ? (
@@ -2010,7 +2013,9 @@ function EmailSectionInner({
                     className={emailInputCls}
                   />
                   {!sendgridConfigured ? null : (
-                    <button
+                    <Button
+                      intent="primary"
+                      emphasis="solid"
                       onClick={saveSendgrid}
                       disabled={!fromAddr.trim() || saving}
                       className={emailBtnCls}
@@ -2022,7 +2027,7 @@ function EmailSectionInner({
                       ) : (
                         "Save"
                       )}
-                    </button>
+                    </Button>
                   )}
                 </div>
               )}
@@ -2246,8 +2251,10 @@ function AgentLimitsSectionInner({
                 )}
                 style={isPage ? CONTROL_STYLE_PAGE : undefined}
               />
-              <button
+              <Button
                 type="button"
+                intent="primary"
+                emphasis="solid"
                 onClick={save}
                 disabled={!hasPendingChange || saving}
                 className={pillButtonClass(isPage, "solid")}
@@ -2262,9 +2269,11 @@ function AgentLimitsSectionInner({
                 ) : (
                   "Save"
                 )}
-              </button>
-              <button
+              </Button>
+              <Button
                 type="button"
+                intent="neutral"
+                emphasis="outline"
                 onClick={reset}
                 disabled={
                   !settings.canUpdate ||
@@ -2274,7 +2283,7 @@ function AgentLimitsSectionInner({
                 className={pillButtonClass(isPage, "outline")}
               >
                 Reset
-              </button>
+              </Button>
             </div>
             {!settings.canUpdate && (
               <p
@@ -2313,51 +2322,6 @@ export interface SettingsPanelProps {
   sectionRequestKey?: number;
 }
 
-function normalizeSettingsSection(
-  value?: string | null,
-): SettingsSectionId | null {
-  const normalized = value?.replace(/^#/, "").toLowerCase() ?? "";
-  if (!normalized) return null;
-  if (normalized.startsWith("secrets")) return "secrets";
-  if (
-    normalized === "workspace" ||
-    normalized === "workspace-settings" ||
-    normalized === "organization" ||
-    normalized === "org"
-  ) {
-    return "secrets";
-  }
-  if (normalized === "agent-engine") return "llm";
-  if (
-    normalized === "agent-model-defaults" ||
-    normalized === "app-model-defaults" ||
-    normalized === "models"
-  ) {
-    return "app-models";
-  }
-  if (normalized === "agent-limits" || normalized === "loop-settings") {
-    return "limits";
-  }
-  return SETTINGS_SECTION_IDS.has(normalized as SettingsSectionId)
-    ? (normalized as SettingsSectionId)
-    : null;
-}
-
-function settingsSectionDomId(section: SettingsSectionId): string {
-  return `agent-settings-section-${section}`;
-}
-
-function initialOpenSection(): SettingsSectionId {
-  if (typeof window === "undefined") return "llm";
-  return normalizeSettingsSection(window.location.hash) ?? "llm";
-}
-
-function firstVisibleSection(
-  sections: readonly SettingsSectionId[],
-): SettingsSectionId {
-  return sections[0] ?? "llm";
-}
-
 // Agent capability modes. The internal values ("production"/"development") are
 // kept for back-compat with the AGENT_MODE wiring; only the visible labels
 // changed to "App mode" / "Code mode" so this control reads as the agent
@@ -2441,13 +2405,15 @@ function CapabilityStatusStrip({
             ) : builderConnected ? (
               "Connected"
             ) : (
-              <button
+              <Button
                 type="button"
+                intent="neutral"
+                emphasis="outline"
                 onClick={onOpenLlm}
                 className="rounded border border-border px-1.5 py-0.5 text-[10px] text-muted-foreground transition-colors hover:bg-accent/40 hover:text-foreground"
               >
                 Connect
-              </button>
+              </Button>
             )
           }
         />
@@ -2590,8 +2556,10 @@ function AccountSectionInner({
           className="hidden"
           onChange={handleAvatarChange}
         />
-        <button
+        <Button
           type="button"
+          intent="neutral"
+          emphasis="outline"
           disabled={!email || uploading}
           onClick={() => fileInputRef.current?.click()}
           className={cn(
@@ -2602,7 +2570,7 @@ function AccountSectionInner({
           {uploading
             ? t("settings.profileUploading")
             : t("settings.profileChangePhoto")}
-        </button>
+        </Button>
       </div>
       <form
         className="space-y-1.5"
@@ -2646,8 +2614,10 @@ function AccountSectionInner({
               </p>
             )}
           </div>
-          <button
+          <Button
             type="submit"
+            intent="primary"
+            emphasis="solid"
             disabled={
               !email ||
               profileQuery.isLoading ||
@@ -2660,7 +2630,7 @@ function AccountSectionInner({
             {updateProfile.isPending
               ? t("settings.profileSaving")
               : t("settings.profileSave")}
-          </button>
+          </Button>
         </div>
       </form>
     </SettingsSection>
@@ -2703,27 +2673,6 @@ function SettingsPanelContent({
     trackingSource: "settings_panel_builder_card",
   });
 
-  // When opened via a `#secrets:<KEY>` hash, focus that specific secret input
-  // inside the "API Keys & Connections" section.
-  const [focusSecretKey, setFocusSecretKey] = useState<string | undefined>(
-    undefined,
-  );
-  const visibleSections = useMemo(() => new Set(sections), [sections]);
-  const shouldShowSection = useCallback(
-    (section: SettingsSectionId) => visibleSections.has(section),
-    [visibleSections],
-  );
-
-  // Accordion: only one section open at a time (null = all closed)
-  const [openSection, setOpenSection] = useState<string | null>(() => {
-    const initial = initialOpenSection();
-    return visibleSections.has(initial)
-      ? initial
-      : firstVisibleSection(sections);
-  });
-  const toggle = (id: string) =>
-    setOpenSection((prev) => (prev === id ? null : id));
-
   const scrollSectionIntoView = useCallback((section: SettingsSectionId) => {
     window.requestAnimationFrame(() => {
       document.getElementById(settingsSectionDomId(section))?.scrollIntoView({
@@ -2732,47 +2681,23 @@ function SettingsPanelContent({
       });
     });
   }, []);
-
-  const openSettingsSection = useCallback(
-    (section: SettingsSectionId, scroll = false) => {
-      setOpenSection(section);
-      if (scroll) scrollSectionIntoView(section);
-    },
-    [scrollSectionIntoView],
-  );
-
-  useEffect(() => {
-    const section = normalizeSettingsSection(initialSection);
-    if (!section || !shouldShowSection(section)) return;
-    if (section !== "secrets") setFocusSecretKey(undefined);
-    openSettingsSection(section, true);
-  }, [
+  const {
+    focusSecretKey,
+    isSectionVisible: shouldShowSection,
+    openSection,
+    toggleSection: toggle,
+    openSettingsSection: openControllerSection,
+  } = useSettingsPanelController({
+    sections,
     initialSection,
     sectionRequestKey,
-    openSettingsSection,
-    shouldShowSection,
-  ]);
-
-  // Support `#secrets:<KEY>` hash fragments from the onboarding CTA — opens
-  // the section and focuses the matching input.
-  useEffect(() => {
-    if (typeof window === "undefined") return;
-    const handleHash = () => {
-      const hash = window.location.hash?.replace(/^#/, "") ?? "";
-      const section = normalizeSettingsSection(hash);
-      if (!section || !shouldShowSection(section)) return;
-      if (hash.startsWith("secrets:") || hash === "secrets") {
-        const key = hash.slice("secrets:".length);
-        setFocusSecretKey(key || undefined);
-      } else {
-        setFocusSecretKey(undefined);
-      }
-      openSettingsSection(section, true);
-    };
-    handleHash();
-    window.addEventListener("hashchange", handleHash);
-    return () => window.removeEventListener("hashchange", handleHash);
-  }, [openSettingsSection, shouldShowSection]);
+    onScrollToSection: scrollSectionIntoView,
+  });
+  const openSettingsSection = useCallback(
+    (section: SettingsSectionId, scroll = false) =>
+      openControllerSection(section, { scroll }),
+    [openControllerSection],
+  );
 
   const isPage = surface === "page";
 
@@ -3158,6 +3083,36 @@ export function SettingsPanel(props: SettingsPanelProps) {
   return <SettingsPanelContent {...props} />;
 }
 
+function McpConnectionsCard() {
+  const t = useT();
+
+  return (
+    <section className="rounded-lg border border-border bg-muted/20 p-3">
+      <div className="flex items-start gap-2.5">
+        <IconPlugConnected
+          size={16}
+          className="mt-0.5 shrink-0 text-muted-foreground"
+        />
+        <div className="min-w-0 flex-1">
+          <h2 className="text-sm font-semibold text-foreground">
+            {t("settings.mcpConnectionsTitle")}
+          </h2>
+          <p className="mt-1 text-xs leading-5 text-muted-foreground">
+            {t("settings.mcpConnectionsDescription")}
+          </p>
+          <Link
+            to="/agent#connections"
+            className="mt-2 inline-flex items-center gap-1 text-xs font-medium text-foreground underline-offset-4 hover:underline"
+          >
+            {t("settings.openMcpConnections")}
+            <IconExternalLink size={13} />
+          </Link>
+        </div>
+      </div>
+    </section>
+  );
+}
+
 export function ConnectionsSettingsContent({
   settingsPanelProps,
 }: {
@@ -3166,6 +3121,7 @@ export function ConnectionsSettingsContent({
   return (
     <div className="mx-auto w-full max-w-2xl space-y-4">
       <BuilderConnectCard trackingSource="settings_connections" />
+      <McpConnectionsCard />
       <SettingsPanelContent
         {...settingsPanelProps}
         surface="page"