feat: add OS notifications for completed/failed tasks

apps/web/src/components/settings/SettingsPanels.tsx

@@ -9,8 +9,9 @@ import {
   type ProviderInstanceId,
   type ScopedThreadRef,
 } from "@t3tools/contracts";
+import { DEFAULT_UNIFIED_SETTINGS, NotificationLevel } from "@t3tools/contracts/settings";
+import { normalizeModelSlug } from "@t3tools/shared/model";
 import { scopeThreadRef } from "@t3tools/client-runtime";
-import { DEFAULT_UNIFIED_SETTINGS } from "@t3tools/contracts/settings";
 import { createModelSelection } from "@t3tools/shared/model";
 import { Equal } from "effect";
 import { APP_VERSION } from "../../branding";
@@ -26,6 +27,7 @@ import { TraitsPicker } from "../chat/TraitsPicker";
 import { resolveAndPersistPreferredEditor } from "../../editorPreferences";
 import { isElectron } from "../../env";
 import { useTheme } from "../../hooks/useTheme";
+import { useNotification } from "../../hooks/useNotification";
 import { useSettings, useUpdateSettings } from "../../hooks/useSettings";
 import { useThreadActions } from "../../hooks/useThreadActions";
 import {
@@ -48,6 +50,8 @@ import {
   useStore,
 } from "../../store";
 import { formatRelativeTime, formatRelativeTimeLabel } from "../../timestampFormat";
+import { cn } from "../../lib/utils";
+import { showNativeNotification } from "../../lib/nativeNotifications";
 import { Button } from "../ui/button";
 import { Empty, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from "../ui/empty";
 import { DraftInput } from "../ui/draft-input";
@@ -95,6 +99,29 @@ const TIMESTAMP_FORMAT_LABELS = {
   "24-hour": "24-hour",
 } as const;
 
+const NOTIFICATION_LEVELS = [
+  {
+    value: NotificationLevel.Off,
+    label: "Off",
+    description: "Disable all OS notifications.",
+  },
+  {
+    value: NotificationLevel.Important,
+    label: "Important",
+    description: "Approval/input required and failed tasks only.",
+  },
+  {
+    value: NotificationLevel.Normal,
+    label: "Normal",
+    description: "Important plus completed tasks.",
+  },
+  {
+    value: NotificationLevel.Verbose,
+    label: "Verbose",
+    description: "Normal plus task activity updates.",
+  },
+] as const;
+
 const DEFAULT_DRIVER_KIND = ProviderDriverKind.make("codex");
 
 function withoutProviderInstanceKey<V>(
@@ -451,6 +478,25 @@ export function GeneralSettingsPanel() {
   const { theme, setTheme } = useTheme();
   const settings = useSettings();
   const { updateSettings } = useUpdateSettings();
+  const { permission: notificationPermission, requestPermission } = useNotification();
+  const [openProviderDetails, setOpenProviderDetails] = useState<Record<ProviderKind, boolean>>({
+    codex: Boolean(
+      settings.providers.codex.binaryPath !== DEFAULT_UNIFIED_SETTINGS.providers.codex.binaryPath ||
+      settings.providers.codex.homePath !== DEFAULT_UNIFIED_SETTINGS.providers.codex.homePath ||
+      settings.providers.codex.customModels.length > 0,
+    ),
+    claudeAgent: Boolean(
+      settings.providers.claudeAgent.binaryPath !==
+        DEFAULT_UNIFIED_SETTINGS.providers.claudeAgent.binaryPath ||
+      settings.providers.claudeAgent.customModels.length > 0,
+    ),
+  });
+  const [customModelInputByProvider, setCustomModelInputByProvider] = useState<
+    Record<ProviderKind, string>
+  >({
+    codex: "",
+    claudeAgent: "",
+  });
   const [openingPathByTarget, setOpeningPathByTarget] = useState({
     keybindings: false,
     logsDirectory: false,
@@ -946,6 +992,117 @@ export function GeneralSettingsPanel() {
           }
         />
 
+        <SettingsRow
+          title="Notifications"
+          description="Allow T3 Code to show OS notifications when a task completes."
+          resetAction={
+            settings.notificationLevel !== DEFAULT_UNIFIED_SETTINGS.notificationLevel ? (
+              <SettingResetButton
+                label="notifications"
+                onClick={() =>
+                  updateSettings({
+                    notificationLevel: DEFAULT_UNIFIED_SETTINGS.notificationLevel,
+                  })
+                }
+              />
+            ) : null
+          }
+          control={
+            <Select
+              value={settings.notificationLevel}
+              onValueChange={(value) => {
+                if (
+                  value === NotificationLevel.Off ||
+                  value === NotificationLevel.Important ||
+                  value === NotificationLevel.Normal ||
+                  value === NotificationLevel.Verbose
+                ) {
+                  updateSettings({ notificationLevel: value });
+                }
+              }}
+            >
+              <SelectTrigger className="w-full sm:w-40" aria-label="Notification level">
+                <SelectValue>
+                  {NOTIFICATION_LEVELS.find((option) => option.value === settings.notificationLevel)
+                    ?.label ?? "Normal"}
+                </SelectValue>
+              </SelectTrigger>
+              <SelectPopup align="end" alignItemWithTrigger={false}>
+                {NOTIFICATION_LEVELS.map((option) => (
+                  <SelectItem hideIndicator key={option.value} value={option.value}>
+                    {option.label}
+                  </SelectItem>
+                ))}
+              </SelectPopup>
+            </Select>
+          }
+          status={
+            NOTIFICATION_LEVELS.find((option) => option.value === settings.notificationLevel)
+              ?.description ?? null
+          }
+        >
+          <div className="mt-3 flex flex-col gap-3 border-t border-border/60 pt-3">
+            <div className="flex flex-col gap-2 rounded-lg border border-border/70 bg-background/70 px-3 py-2 sm:flex-row sm:items-center sm:justify-between">
+              <div className="min-w-0 flex-1">
+                <p className="text-xs font-medium text-foreground">Permission status</p>
+                <p className="mt-1 text-[11px] text-muted-foreground">
+                  {isElectron
+                    ? "Desktop app permissions are managed by your OS."
+                    : notificationPermission === "unsupported"
+                      ? "Notifications are not supported by this browser."
+                      : notificationPermission === "granted"
+                        ? "Allowed"
+                        : notificationPermission === "denied"
+                          ? "Blocked"
+                          : "Not yet requested"}
+                </p>
+              </div>
+              {isElectron ? null : (
+                <Button
+                  size="xs"
+                  variant="outline"
+                  disabled={
+                    notificationPermission === "unsupported" || notificationPermission === "granted"
+                  }
+                  onClick={requestPermission}
+                >
+                  Request permission
+                </Button>
+              )}
+            </div>
+
+            <div className="flex flex-wrap items-center gap-2">
+              <Button
+                size="xs"
+                variant="outline"
+                disabled={
+                  settings.notificationLevel === NotificationLevel.Off ||
+                  (!isElectron && notificationPermission !== "granted")
+                }
+                onClick={() => {
+                  showNativeNotification({
+                    title: "T3 Code",
+                    body: "Notification test from settings.",
+                    tag: "t3code:test",
+                  });
+                }}
+              >
+                Send test notification
+              </Button>
+              {!isElectron && notificationPermission === "denied" ? (
+                <p className="text-[11px] text-muted-foreground">
+                  Enable notifications in your browser site settings to allow OS alerts.
+                </p>
+              ) : null}
+              {isElectron || notificationPermission === "granted" ? (
+                <p className="text-[11px] text-muted-foreground">
+                  If notifications still do not appear, check OS notification settings.
+                </p>
+              ) : null}
+            </div>
+          </div>
+        </SettingsRow>
+
         <SettingsRow
           title="Auto-open task panel"
           description="Open the right-side plan and task panel automatically when steps appear."
@@ -971,7 +1128,6 @@ export function GeneralSettingsPanel() {
             />
           }
         />
-
         <SettingsRow
           title="New threads"
           description="Pick the default workspace mode for newly created draft threads."

apps/web/src/hooks/useNotification.ts

@@ -0,0 +1,30 @@
+import { useCallback, useEffect, useState } from "react";
+
+import {
+  getNotificationPermission,
+  requestNotificationPermission,
+} from "../lib/nativeNotifications";
+
+export function useNotification() {
+  const [permission, setPermission] = useState(getNotificationPermission());
+
+  const refresh = useCallback(() => {
+    setPermission(getNotificationPermission());
+  }, []);
+
+  const requestPermission = useCallback(async () => {
+    const next = await requestNotificationPermission();
+    setPermission(next);
+  }, []);
+
+  useEffect(() => {
+    refresh();
+    window.addEventListener("focus", refresh);
+
+    return () => {
+      window.removeEventListener("focus", refresh);
+    };
+  }, [refresh]);
+
+  return { permission, requestPermission, refresh };
+}

apps/web/src/hooks/useSettings.ts

@@ -16,6 +16,11 @@ import {
   type ClientSettings,
   DEFAULT_CLIENT_SETTINGS,
   DEFAULT_UNIFIED_SETTINGS,
+  NotificationLevel,
+  NotificationLevelSchema,
+  SidebarProjectSortOrder,
+  SidebarThreadSortOrder,
+  TimestampFormat,
   UnifiedSettings,
 } from "@t3tools/contracts/settings";
 import { ensureLocalApi } from "~/localApi";
@@ -188,6 +193,140 @@ export function useUpdateSettings() {
   };
 }
 
+// ── One-time migration from localStorage ─────────────────────────────
+
+export function buildLegacyServerSettingsMigrationPatch(legacySettings: Record<string, unknown>) {
+  const patch: DeepMutable<ServerSettingsPatch> = {};
+
+  if (Predicate.isBoolean(legacySettings.enableAssistantStreaming)) {
+    patch.enableAssistantStreaming = legacySettings.enableAssistantStreaming;
+  }
+
+  if (Schema.is(ThreadEnvMode)(legacySettings.defaultThreadEnvMode)) {
+    patch.defaultThreadEnvMode = legacySettings.defaultThreadEnvMode;
+  }
+
+  if (Schema.is(ModelSelection)(legacySettings.textGenerationModelSelection)) {
+    patch.textGenerationModelSelection = legacySettings.textGenerationModelSelection;
+  }
+
+  if (typeof legacySettings.codexBinaryPath === "string") {
+    patch.providers ??= {};
+    patch.providers.codex ??= {};
+    patch.providers.codex.binaryPath = legacySettings.codexBinaryPath;
+  }
+
+  if (typeof legacySettings.codexHomePath === "string") {
+    patch.providers ??= {};
+    patch.providers.codex ??= {};
+    patch.providers.codex.homePath = legacySettings.codexHomePath;
+  }
+
+  if (Array.isArray(legacySettings.customCodexModels)) {
+    patch.providers ??= {};
+    patch.providers.codex ??= {};
+    patch.providers.codex.customModels = normalizeCustomModelSlugs(
+      legacySettings.customCodexModels,
+      new Set<string>(),
+      "codex",
+    );
+  }
+
+  if (Predicate.isString(legacySettings.claudeBinaryPath)) {
+    patch.providers ??= {};
+    patch.providers.claudeAgent ??= {};
+    patch.providers.claudeAgent.binaryPath = legacySettings.claudeBinaryPath;
+  }
+
+  if (Array.isArray(legacySettings.customClaudeModels)) {
+    patch.providers ??= {};
+    patch.providers.claudeAgent ??= {};
+    patch.providers.claudeAgent.customModels = normalizeCustomModelSlugs(
+      legacySettings.customClaudeModels,
+      new Set<string>(),
+      "claudeAgent",
+    );
+  }
+
+  return patch;
+}
+
+export function buildLegacyClientSettingsMigrationPatch(
+  legacySettings: Record<string, unknown>,
+): Partial<DeepMutable<ClientSettings>> {
+  const patch: Partial<DeepMutable<ClientSettings>> = {};
+
+  if (Predicate.isBoolean(legacySettings.confirmThreadArchive)) {
+    patch.confirmThreadArchive = legacySettings.confirmThreadArchive;
+  }
+
+  if (Predicate.isBoolean(legacySettings.confirmThreadDelete)) {
+    patch.confirmThreadDelete = legacySettings.confirmThreadDelete;
+  }
+
+  if (Predicate.isBoolean(legacySettings.diffWordWrap)) {
+    patch.diffWordWrap = legacySettings.diffWordWrap;
+  }
+
+  if (Schema.is(SidebarProjectSortOrder)(legacySettings.sidebarProjectSortOrder)) {
+    patch.sidebarProjectSortOrder = legacySettings.sidebarProjectSortOrder;
+  }
+
+  if (Schema.is(SidebarThreadSortOrder)(legacySettings.sidebarThreadSortOrder)) {
+    patch.sidebarThreadSortOrder = legacySettings.sidebarThreadSortOrder;
+  }
+
+  if (Schema.is(TimestampFormat)(legacySettings.timestampFormat)) {
+    patch.timestampFormat = legacySettings.timestampFormat;
+  }
+
+  if (Schema.is(NotificationLevelSchema)(legacySettings.notificationLevel)) {
+    patch.notificationLevel = legacySettings.notificationLevel as NotificationLevel;
+  }
+
+  return patch;
+}
+
+/**
+ * Call once on app startup.
+ * If the legacy localStorage key exists, migrate its values to the new server
+ * and client storage formats, then remove the legacy key so this only runs once.
+ */
+export function migrateLocalSettingsToServer(): void {
+  if (typeof window === "undefined") return;
+
+  const raw = localStorage.getItem(OLD_SETTINGS_KEY);
+  if (!raw) return;
+
+  try {
+    const old = JSON.parse(raw);
+    if (!Predicate.isObject(old)) return;
+
+    // Migrate server-relevant keys via RPC
+    const serverPatch = buildLegacyServerSettingsMigrationPatch(old);
+    if (Object.keys(serverPatch).length > 0) {
+      const api = ensureNativeApi();
+      void api.server.updateSettings(serverPatch);
+    }
+
+    // Migrate client-only keys to the new localStorage key
+    const clientPatch = buildLegacyClientSettingsMigrationPatch(old);
+    if (Object.keys(clientPatch).length > 0) {
+      const existing = localStorage.getItem(CLIENT_SETTINGS_STORAGE_KEY);
+      const current = existing ? (JSON.parse(existing) as Record<string, unknown>) : {};
+      localStorage.setItem(
+        CLIENT_SETTINGS_STORAGE_KEY,
+        JSON.stringify({ ...current, ...clientPatch }),
+      );
+    }
+  } catch (error) {
+    console.error("[MIGRATION] Error migrating local settings:", error);
+  } finally {
+    // Remove the legacy key regardless to keep migration one-shot behavior.
+    localStorage.removeItem(OLD_SETTINGS_KEY);
+  }
+}
+
 export function __resetClientSettingsPersistenceForTests(): void {
   clientSettingsSnapshot = DEFAULT_CLIENT_SETTINGS;
   clientSettingsHydrated = false;