@agent-native/core 0.137.0 → 0.137.2

package/corpus/README.md

@@ -31,4 +31,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- template files: 7555
+- template files: 7571

package/corpus/templates/analytics/app/components/AgentCompletionSound.tsx

@@ -0,0 +1,105 @@
+import { appPath } from "@agent-native/core/client/api-path";
+import { useActionQuery } from "@agent-native/core/client/hooks";
+import { useEffect, useRef } from "react";
+
+import {
+  ANALYTICS_USER_PREFS_KEY,
+  type AnalyticsUserPrefs,
+} from "../../shared/analytics-user-prefs";
+
+const AGENT_COMPLETION_SOUND_URL = appPath("/agent-completion.mp3");
+const DEFAULT_TAB_ID = "__default__";
+
+function getTabId(detail: unknown): string {
+  if (
+    detail &&
+    typeof detail === "object" &&
+    "tabId" in detail &&
+    typeof detail.tabId === "string" &&
+    detail.tabId
+  ) {
+    return detail.tabId;
+  }
+  return DEFAULT_TAB_ID;
+}
+
+/** Plays the shared Builder bell after a successful Analytics agent run. */
+export function AgentCompletionSound() {
+  const { data: prefs, isError } = useActionQuery<AnalyticsUserPrefs>(
+    "get-user-pref",
+    { key: ANALYTICS_USER_PREFS_KEY },
+  );
+  const soundEnabledRef = useRef(false);
+  const runningTabsRef = useRef(new Set<string>());
+  const autoContinuingTabsRef = useRef(new Set<string>());
+  const failedTabsRef = useRef(new Set<string>());
+
+  useEffect(() => {
+    // Missing and unreadable preferences both keep the sound off until enabled.
+    soundEnabledRef.current = !isError && prefs?.bellSoundEnabled === true;
+  }, [isError, prefs]);
+
+  useEffect(() => {
+    const handleRunError = (event: Event) => {
+      const detail = (event as CustomEvent).detail;
+      failedTabsRef.current.add(getTabId(detail));
+    };
+
+    const handleAutoContinue = (event: Event) => {
+      const detail = (event as CustomEvent).detail;
+      autoContinuingTabsRef.current.add(getTabId(detail));
+    };
+
+    const handleChatRunning = (event: Event) => {
+      const detail = (event as CustomEvent).detail;
+      const tabId = getTabId(detail);
+
+      if (detail?.isRunning === true) {
+        autoContinuingTabsRef.current.delete(tabId);
+        failedTabsRef.current.delete(tabId);
+        runningTabsRef.current.add(tabId);
+        return;
+      }
+
+      if (
+        detail?.isRunning !== false ||
+        !runningTabsRef.current.delete(tabId)
+      ) {
+        return;
+      }
+
+      const wasAutoContinued = autoContinuingTabsRef.current.delete(tabId);
+      const failed = failedTabsRef.current.delete(tabId);
+      if (
+        wasAutoContinued ||
+        failed ||
+        detail.reason === "failed" ||
+        detail.reason === "stopped" ||
+        !soundEnabledRef.current ||
+        typeof Audio === "undefined"
+      ) {
+        return;
+      }
+
+      const audio = new Audio(AGENT_COMPLETION_SOUND_URL);
+      audio.volume = 0.5;
+      void audio.play().catch(() => {
+        // Browsers may reject playback until the user has interacted with the page.
+      });
+    };
+
+    window.addEventListener("agent-chat:run-error", handleRunError);
+    window.addEventListener("agent-chat:auto-continue", handleAutoContinue);
+    window.addEventListener("agentNative.chatRunning", handleChatRunning);
+    return () => {
+      window.removeEventListener("agent-chat:run-error", handleRunError);
+      window.removeEventListener(
+        "agent-chat:auto-continue",
+        handleAutoContinue,
+      );
+      window.removeEventListener("agentNative.chatRunning", handleChatRunning);
+    };
+  }, []);
+
+  return null;
+}

package/corpus/templates/analytics/app/components/layout/Layout.tsx

@@ -22,6 +22,7 @@ import {
 } from "@/lib/chat-handoff";
 import { TAB_ID } from "@/lib/tab-id";
 
+import { AgentCompletionSound } from "../AgentCompletionSound";
 import { Header } from "./Header";
 import { HeaderActionsProvider } from "./HeaderActions";
 import { MobileNav } from "./MobileNav";
@@ -138,7 +139,12 @@ function InteractiveLayout({ children }: LayoutProps) {
   }
 
   if (BARE_ROUTES.has(location.pathname)) {
-    return <>{children}</>;
+    return (
+      <>
+        <AgentCompletionSound />
+        {children}
+      </>
+    );
   }
 
   const contentFrame = (
@@ -177,40 +183,43 @@ function InteractiveLayout({ children }: LayoutProps) {
   );
 
   return (
-    <HeaderActionsProvider>
-      <div className="agent-layout-shell flex h-screen w-full overflow-hidden bg-background text-foreground">
-        <div className="agent-layout-left-drawer hidden shrink-0 md:block">
-          <Sidebar />
-        </div>
-        {isAskRoute ? (
-          <div className="agent-layout-main-surface flex min-w-0 flex-1 overflow-hidden">
-            {contentFrame}
+    <>
+      <AgentCompletionSound />
+      <HeaderActionsProvider>
+        <div className="agent-layout-shell flex h-screen w-full overflow-hidden bg-background text-foreground">
+          <div className="agent-layout-left-drawer hidden shrink-0 md:block">
+            <Sidebar />
           </div>
-        ) : (
-          <AgentSidebar
-            position="right"
-            defaultOpen={false}
-            chatViewTransition
-            chatViewTransitionHandoff={chatHomeHandoffPending}
-            storageKey={ANALYTICS_CHAT_STORAGE_KEY}
-            browserTabId={TAB_ID}
-            openOnChatRunning={chatHomeHandoffActive}
-            onFullscreenRequest={openAskAgentFullscreen}
-            emptyStateText={t("chat.emptyState")}
-            agentPageHref="/agent"
-            suggestions={[
-              t("chat.suggestionArrGrowth"),
-              t("chat.suggestionChurn"),
-              t("chat.suggestionAnomalies"),
-              t("chat.suggestionMrr"),
-            ]}
-            scope={analyticsScope}
-            composerSlot={<CreativeContextComposerChip />}
-          >
-            {contentFrame}
-          </AgentSidebar>
-        )}
-      </div>
-    </HeaderActionsProvider>
+          {isAskRoute ? (
+            <div className="agent-layout-main-surface flex min-w-0 flex-1 overflow-hidden">
+              {contentFrame}
+            </div>
+          ) : (
+            <AgentSidebar
+              position="right"
+              defaultOpen={false}
+              chatViewTransition
+              chatViewTransitionHandoff={chatHomeHandoffPending}
+              storageKey={ANALYTICS_CHAT_STORAGE_KEY}
+              browserTabId={TAB_ID}
+              openOnChatRunning={chatHomeHandoffActive}
+              onFullscreenRequest={openAskAgentFullscreen}
+              emptyStateText={t("chat.emptyState")}
+              agentPageHref="/agent"
+              suggestions={[
+                t("chat.suggestionArrGrowth"),
+                t("chat.suggestionChurn"),
+                t("chat.suggestionAnomalies"),
+                t("chat.suggestionMrr"),
+              ]}
+              scope={analyticsScope}
+              composerSlot={<CreativeContextComposerChip />}
+            >
+              {contentFrame}
+            </AgentSidebar>
+          )}
+        </div>
+      </HeaderActionsProvider>
+    </>
   );
 }

package/corpus/templates/analytics/app/i18n-data.ts

@@ -198,6 +198,10 @@ const enUS = {
     errorEmailNotificationsDescription:
       "Send an email when a new JavaScript error is captured. Off by default.",
     errorEmailNotificationsSaveFailed: "Couldn't save the email preference.",
+    bellSound: "Bell sound",
+    bellSoundDescription:
+      "Play a sound when the agent finishes a run. Off by default.",
+    bellSoundSaveFailed: "Couldn't save the sound preference.",
     about: "About",
     aboutDescription:
       "Analytics is a tool for connecting data sources and building custom dashboards. Connect Google Analytics, BigQuery, Stripe, and more, then ask the agent to create dashboards.",
@@ -4261,6 +4265,9 @@ export const messagesByLocale = {
       errorEmailNotificationsDescription:
         "捕获新的 JavaScript 错误时发送电子邮件。默认关闭。",
       errorEmailNotificationsSaveFailed: "无法保存电子邮件偏好设置。",
+      bellSound: "提示音",
+      bellSoundDescription: "代理完成运行时播放提示音。默认关闭。",
+      bellSoundSaveFailed: "无法保存提示音偏好设置。",
       about: "关于",
       aboutDescription:
         "Analytics 用于连接数据源并构建自定义仪表板。连接 Google Analytics、BigQuery、Stripe 等，然后让代理创建仪表板。",
@@ -4484,6 +4491,10 @@ export const messagesByLocale = {
         "Envía un email cuando se capture un nuevo error de JavaScript. Desactivado de forma predeterminada.",
       errorEmailNotificationsSaveFailed:
         "No se pudo guardar la preferencia de email.",
+      bellSound: "Sonido de campana",
+      bellSoundDescription:
+        "Reproduce un sonido cuando el agente termina una ejecución. Desactivado de forma predeterminada.",
+      bellSoundSaveFailed: "No se pudo guardar la preferencia de sonido.",
       about: "Acerca de",
       aboutDescription:
         "Analytics conecta fuentes de datos y crea paneles personalizados. Conecta Google Analytics, BigQuery, Stripe y más, y pide al agente que cree paneles.",
@@ -4712,6 +4723,10 @@ export const messagesByLocale = {
         "Envoyer un e-mail lorsqu’une nouvelle erreur JavaScript est capturée. Désactivé par défaut.",
       errorEmailNotificationsSaveFailed:
         "Impossible d’enregistrer la préférence e-mail.",
+      bellSound: "Son de notification",
+      bellSoundDescription:
+        "Jouer un son lorsque l’agent termine une exécution. Désactivé par défaut.",
+      bellSoundSaveFailed: "Impossible d’enregistrer la préférence sonore.",
       about: "À propos",
       aboutDescription:
         "Analytics connecte des sources de données et crée des tableaux de bord personnalisés. Connectez Google Analytics, BigQuery, Stripe et plus encore, puis demandez à l'agent de créer des tableaux de bord.",
@@ -4946,6 +4961,11 @@ export const messagesByLocale = {
         "Eine E-Mail senden, wenn ein neuer JavaScript-Fehler erfasst wird. Standardmäßig deaktiviert.",
       errorEmailNotificationsSaveFailed:
         "Die E-Mail-Einstellung konnte nicht gespeichert werden.",
+      bellSound: "Signalton",
+      bellSoundDescription:
+        "Einen Ton abspielen, wenn der Agent einen Lauf beendet. Standardmäßig deaktiviert.",
+      bellSoundSaveFailed:
+        "Die Toneinstellung konnte nicht gespeichert werden.",
       about: "Info",
       aboutDescription:
         "Analytics verbindet Datenquellen und erstellt benutzerdefinierte Dashboards. Verbinde Google Analytics, BigQuery, Stripe und mehr und bitte den Agenten, Dashboards zu erstellen.",
@@ -5170,6 +5190,10 @@ export const messagesByLocale = {
       errorEmailNotificationsDescription:
         "新しい JavaScript エラーが記録されたときにメールを送信します。デフォルトではオフです。",
       errorEmailNotificationsSaveFailed: "メール設定を保存できませんでした。",
+      bellSound: "完了サウンド",
+      bellSoundDescription:
+        "エージェントが実行を完了したときにサウンドを再生します。デフォルトでオフです。",
+      bellSoundSaveFailed: "サウンド設定を保存できませんでした。",
       about: "概要",
       aboutDescription:
         "Analytics はデータソースを接続し、カスタムダッシュボードを作成するツールです。Google Analytics、BigQuery、Stripe などを接続し、エージェントにダッシュボード作成を依頼できます。",
@@ -5393,6 +5417,10 @@ export const messagesByLocale = {
       errorEmailNotificationsDescription:
         "새 JavaScript 오류가 캡처되면 이메일을 보냅니다. 기본값은 꺼져 있습니다.",
       errorEmailNotificationsSaveFailed: "이메일 설정을 저장하지 못했습니다.",
+      bellSound: "완료 소리",
+      bellSoundDescription:
+        "에이전트가 실행을 완료하면 소리를 재생합니다. 기본값은 꺼짐입니다.",
+      bellSoundSaveFailed: "소리 설정을 저장하지 못했습니다.",
       about: "정보",
       aboutDescription:
         "Analytics는 데이터 소스를 연결하고 사용자 지정 대시보드를 만드는 도구입니다. Google Analytics, BigQuery, Stripe 등을 연결한 뒤 에이전트에게 대시보드를 만들게 하세요.",
@@ -5621,6 +5649,10 @@ export const messagesByLocale = {
         "Envie um e-mail quando um novo erro de JavaScript for capturado. Desativado por padrão.",
       errorEmailNotificationsSaveFailed:
         "Não foi possível salvar a preferência de e-mail.",
+      bellSound: "Som de conclusão",
+      bellSoundDescription:
+        "Reproduzir um som quando o agente concluir uma execução. Desativado por padrão.",
+      bellSoundSaveFailed: "Não foi possível salvar a preferência de som.",
       about: "Sobre",
       aboutDescription:
         "Analytics conecta fontes de dados e cria dashboards personalizados. Conecte Google Analytics, BigQuery, Stripe e outros, depois peça ao agente para criar dashboards.",
@@ -5843,6 +5875,9 @@ export const messagesByLocale = {
       errorEmailNotificationsDescription:
         "नया JavaScript त्रुटि कैप्चर होने पर ईमेल भेजें। डिफ़ॉल्ट रूप से बंद।",
       errorEmailNotificationsSaveFailed: "ईमेल प्राथमिकता सहेजी नहीं जा सकी।",
+      bellSound: "पूर्णता ध्वनि",
+      bellSoundDescription: "एजेंट के रन पूरा करने पर ध्वनि चलाएं। डिफ़ॉल्ट रूप से बंद।",
+      bellSoundSaveFailed: "ध्वनि प्राथमिकता सहेजी नहीं जा सकी।",
       about: "परिचय",
       aboutDescription:
         "Analytics डेटा स्रोतों को जोड़ने और कस्टम डैशबोर्ड बनाने का टूल है। Google Analytics, BigQuery, Stripe आदि जोड़ें, फिर एजेंट से डैशबोर्ड बनवाएं।",
@@ -6065,6 +6100,9 @@ export const messagesByLocale = {
       errorEmailNotificationsDescription:
         "إرسال بريد إلكتروني عند التقاط خطأ JavaScript جديد. معطّل افتراضيًا.",
       errorEmailNotificationsSaveFailed: "تعذّر حفظ تفضيل البريد الإلكتروني.",
+      bellSound: "صوت الجرس",
+      bellSoundDescription: "تشغيل صوت عند اكتمال تشغيل الوكيل. معطّل افتراضيًا.",
+      bellSoundSaveFailed: "تعذّر حفظ تفضيل الصوت.",
       about: "حول",
       aboutDescription:
         "Analytics أداة لربط مصادر البيانات وبناء لوحات معلومات مخصصة. اربط Google Analytics وBigQuery وStripe وغيرها، ثم اطلب من الوكيل إنشاء اللوحات.",

package/corpus/templates/analytics/app/pages/Settings.tsx

@@ -54,18 +54,34 @@ export default function Settings() {
   const [errorEmailEnabledOverride, setErrorEmailEnabledOverride] = useState<
     boolean | null
   >(null);
+  const [bellSoundEnabledOverride, setBellSoundEnabledOverride] = useState<
+    boolean | null
+  >(null);
 
   useEffect(() => {
     if (analyticsPrefs) {
       setErrorEmailEnabledOverride(
         analyticsPrefs.errorEmailNotifications === true,
       );
+      setBellSoundEnabledOverride(analyticsPrefs.bellSoundEnabled === true);
     }
   }, [analyticsPrefs]);
 
   const errorEmailEnabled =
     errorEmailEnabledOverride ??
     analyticsPrefs?.errorEmailNotifications === true;
+  const bellSoundEnabled =
+    bellSoundEnabledOverride ?? analyticsPrefs?.bellSoundEnabled === true;
+
+  const currentAnalyticsPrefs: AnalyticsUserPrefs = {
+    ...(analyticsPrefs ?? {}),
+    ...(errorEmailEnabledOverride === null
+      ? {}
+      : { errorEmailNotifications: errorEmailEnabledOverride }),
+    ...(bellSoundEnabledOverride === null
+      ? {}
+      : { bellSoundEnabled: bellSoundEnabledOverride }),
+  };
 
   const saveErrorEmailPreference = (enabled: boolean) => {
     const previous = errorEmailEnabled;
@@ -73,7 +89,10 @@ export default function Settings() {
     void saveAnalyticsPrefs
       .mutateAsync({
         key: ANALYTICS_USER_PREFS_KEY,
-        value: { errorEmailNotifications: enabled },
+        value: {
+          ...currentAnalyticsPrefs,
+          errorEmailNotifications: enabled,
+        },
       })
       .catch((error) => {
         setErrorEmailEnabledOverride(previous);
@@ -85,6 +104,24 @@ export default function Settings() {
       });
   };
 
+  const saveBellSoundPreference = (enabled: boolean) => {
+    const previous = bellSoundEnabled;
+    setBellSoundEnabledOverride(enabled);
+    void saveAnalyticsPrefs
+      .mutateAsync({
+        key: ANALYTICS_USER_PREFS_KEY,
+        value: { ...currentAnalyticsPrefs, bellSoundEnabled: enabled },
+      })
+      .catch((error) => {
+        setBellSoundEnabledOverride(previous);
+        toast.error(
+          error instanceof Error
+            ? error.message
+            : t("settings.bellSoundSaveFailed"),
+        );
+      });
+  };
+
   const extraTabs = useMemo<SettingsTabItem[]>(
     () => [
       {
@@ -170,6 +207,21 @@ export default function Settings() {
                 />
               }
             />
+            <SettingsRow
+              id="bell-sound"
+              label={t("settings.bellSound")}
+              description={t("settings.bellSoundDescription")}
+              control={
+                <Switch
+                  aria-label={t("settings.bellSound")}
+                  checked={bellSoundEnabled}
+                  disabled={
+                    analyticsPrefsLoading || saveAnalyticsPrefs.isPending
+                  }
+                  onCheckedChange={saveBellSoundPreference}
+                />
+              }
+            />
           </SettingsGroup>
 
           {replayStorageStatus.data?.configured ? (

package/corpus/templates/analytics/app/pages/settings/settings-search.ts

@@ -57,6 +57,12 @@ export function buildAnalyticsGeneralSettingsSearchEntries(
       keywords: "email notifications errors alerts javascript monitoring",
       hash: "error-email-notifications",
     },
+    {
+      id: "analytics-bell-sound",
+      label: t("settings.bellSound"),
+      keywords: "sound audio ding agent completion notification",
+      hash: "bell-sound",
+    },
     {
       id: "analytics-about",
       label: t("settings.about"),

package/corpus/templates/analytics/changelog/2026-08-04-choose-whether-analytics-plays-a-bell-when-the-agent-finishe.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-08-04
+---
+
+Choose whether Analytics plays a bell when the agent finishes a run

package/corpus/templates/analytics/shared/analytics-user-prefs.ts

@@ -4,4 +4,6 @@ export const ANALYTICS_USER_PREFS_KEY = "analytics-user-prefs";
 export type AnalyticsUserPrefs = {
   /** New JavaScript error emails are opt-in. */
   errorEmailNotifications?: boolean;
+  /** Play the completion sound when an agent run finishes successfully. */
+  bellSoundEnabled?: boolean;
 };