From 754def28a5488fc93de543e7efeb10cc0bb68d86 Mon Sep 17 00:00:00 2001
From: AprilNEA <github@sku.moe>
Date: Sun, 2 Aug 2026 02:31:13 +0800
Subject: [PATCH] feat(mobile): add remote push notifications

---
 apps/mobile/src/app/_layout.tsx               |  2 +
 apps/mobile/src/app/account.tsx               |  5 +-
 apps/mobile/src/app/settings.tsx              | 50 ++++++++++++++-
 .../components/shell/notification-observer.ts | 58 ++++++++++++++++++
 .../__tests__/notification-route.test.ts      | 16 +++++
 apps/mobile/src/runtime/cloud/account.ts      |  7 +++
 apps/mobile/src/runtime/cloud/devices.ts      | 15 +++++
 apps/mobile/src/runtime/notification-route.ts | 23 +++++++
 apps/mobile/src/runtime/notifications.ts      | 61 +++++++++++++++++++
 apps/mobile/src/stores/settings-store.ts      | 16 ++++-
 packages/presentation/i18n/src/locales/en.ts  | 10 +++
 .../presentation/i18n/src/locales/zh-cn.ts    | 10 +++
 12 files changed, 267 insertions(+), 6 deletions(-)
 create mode 100644 apps/mobile/src/components/shell/notification-observer.ts
 create mode 100644 apps/mobile/src/runtime/__tests__/notification-route.test.ts
 create mode 100644 apps/mobile/src/runtime/notification-route.ts
 create mode 100644 apps/mobile/src/runtime/notifications.ts

diff --git a/apps/mobile/src/app/_layout.tsx b/apps/mobile/src/app/_layout.tsx
index c283471cc..11af1effc 100644
--- a/apps/mobile/src/app/_layout.tsx
+++ b/apps/mobile/src/app/_layout.tsx
@@ -10,6 +10,7 @@ import {
   AppKeyboardProvider,
   AppThemeProvider,
 } from '@mobile/components/shell/app-providers';
+import { NotificationObserver } from '@mobile/components/shell/notification-observer';
 import { MobileProductAnalyticsProvider } from '@mobile/components/shell/product-analytics-provider';
 import { RootNavigator } from '@mobile/components/shell/root-navigator';
 import { ThemeController } from '@mobile/components/shell/theme-controller';
@@ -78,6 +79,7 @@ function RootLayout() {
         ]}
       >
         <ThemeController />
+        <NotificationObserver />
         <RootNavigator />
       </ComposeContextProvider>
     </GestureHandlerRootView>
diff --git a/apps/mobile/src/app/account.tsx b/apps/mobile/src/app/account.tsx
index aeaa5770c..f42306ea2 100644
--- a/apps/mobile/src/app/account.tsx
+++ b/apps/mobile/src/app/account.tsx
@@ -3,6 +3,7 @@ import { DevicesSection } from '@mobile/components/account/devices-section';
 import { ProfileRow } from '@mobile/components/account/profile-row';
 import { signOutOfCloud, useCloudAccount } from '@mobile/runtime/cloud/account';
 import { Redirect, Stack } from 'expo-router';
+import { Alert } from 'react-native';
 import { useTranslations } from 'use-intl';
 
 /** Account screen: profile, the account's device registry, and sign-out. */
@@ -30,9 +31,7 @@ export default function AccountScreen(): React.ReactNode {
                 <Button
                   role="destructive"
                   label={t('signOut')}
-                  onPress={() => {
-                    void signOutOfCloud();
-                  }}
+                  onPress={() => signOutOfCloud().catch(() => Alert.alert(t('signOutError')))}
                 />
               </Section>
             </>
diff --git a/apps/mobile/src/app/settings.tsx b/apps/mobile/src/app/settings.tsx
index ad211ae34..6a2efc1e8 100644
--- a/apps/mobile/src/app/settings.tsx
+++ b/apps/mobile/src/app/settings.tsx
@@ -1,13 +1,19 @@
 import { Form, Host, Link, Picker, Section, Text, Toggle, VStack } from '@expo/ui/swift-ui';
-import { font, foregroundStyle, pickerStyle, tag } from '@expo/ui/swift-ui/modifiers';
+import { disabled, font, foregroundStyle, pickerStyle, tag } from '@expo/ui/swift-ui/modifiers';
 import { AgentKindSchema, WIRE_PROTOCOL_VERSION } from '@linkcode/schema';
 import { NavigationRow } from '@mobile/components/form/navigation-row';
 import { useCloudAccount } from '@mobile/runtime/cloud/account';
+import {
+  requestNotificationPermission,
+  revokeDevicePushToken,
+  syncDevicePushToken,
+} from '@mobile/runtime/notifications';
 import { setMobileProductAnalyticsEnabled } from '@mobile/runtime/product-analytics';
 import { useAnalyticsPreferenceStore } from '@mobile/stores/analytics-store';
 import type { ThemePreference } from '@mobile/stores/settings-store';
 import { useSettingsStore } from '@mobile/stores/settings-store';
 import { Stack, useRouter } from 'expo-router';
+import { Alert, Linking } from 'react-native';
 import { useTranslations } from 'use-intl';
 
 const THEME_PREFERENCES: readonly ThemePreference[] = ['system', 'light', 'dark'];
@@ -32,7 +38,31 @@ export default function SettingsScreen(): React.ReactNode {
   const account = useCloudAccount();
   const productAnalyticsEnabled = useAnalyticsPreferenceStore((state) => state.enabled);
   const themePreference = useSettingsStore((state) => state.themePreference);
+  const notificationsEnabled = useSettingsStore((state) => state.notificationsEnabled);
   const setThemePreference = useSettingsStore((state) => state.setThemePreference);
+  const setNotificationsEnabled = useSettingsStore((state) => state.setNotificationsEnabled);
+
+  const updateNotifications = async (enabled: boolean) => {
+    try {
+      if (!enabled) {
+        await revokeDevicePushToken();
+        setNotificationsEnabled(false);
+        return;
+      }
+      if (account.status !== 'signed-in') return;
+      if (await requestNotificationPermission()) {
+        await syncDevicePushToken(account.user.id);
+        setNotificationsEnabled(true);
+        return;
+      }
+      Alert.alert(t('notificationsDeniedTitle'), t('notificationsDenied'), [
+        { text: t('cancel'), style: 'cancel' },
+        { text: t('openSettings'), onPress: () => Linking.openSettings() },
+      ]);
+    } catch {
+      Alert.alert(t('notificationsErrorTitle'), t('notificationsError'));
+    }
+  };
 
   return (
     <>
@@ -79,6 +109,24 @@ export default function SettingsScreen(): React.ReactNode {
             />
           </Section>
 
+          <Section
+            title={t('notifications')}
+            footer={
+              <Text>
+                {account.status === 'signed-in'
+                  ? t('notificationsHint')
+                  : t('notificationsRequiresCloud')}
+              </Text>
+            }
+          >
+            <Toggle
+              isOn={notificationsEnabled}
+              onIsOnChange={updateNotifications}
+              label={t('notifications')}
+              modifiers={[disabled(account.status !== 'signed-in')]}
+            />
+          </Section>
+
           {/* Native links open the URL themselves — no Linking.openURL fallback to get wrong. */}
           <Section title={t('legalAndSupport')}>
             <Link label={t('privacyPolicy')} destination={PRIVACY_POLICY_URL} />
diff --git a/apps/mobile/src/components/shell/notification-observer.ts b/apps/mobile/src/components/shell/notification-observer.ts
new file mode 100644
index 000000000..b6fe4ee24
--- /dev/null
+++ b/apps/mobile/src/components/shell/notification-observer.ts
@@ -0,0 +1,58 @@
+import { useCloudAccount } from '@mobile/runtime/cloud/account';
+import { resolveNotificationRoute } from '@mobile/runtime/notification-route';
+import { syncDevicePushToken } from '@mobile/runtime/notifications';
+import { useHostRegistryHydrated, useHostRegistryStore } from '@mobile/stores/host-store';
+import { useSettingsStore } from '@mobile/stores/settings-store';
+import * as Sentry from '@sentry/react-native';
+import * as Notifications from 'expo-notifications';
+import { useRouter } from 'expo-router';
+import { useEffect } from 'react';
+import { AppState } from 'react-native';
+
+export function NotificationObserver(): null {
+  const router = useRouter();
+  const account = useCloudAccount();
+  const hydrated = useHostRegistryHydrated();
+  const hosts = useHostRegistryStore((state) => state.hosts);
+  const enabled = useSettingsStore((state) => state.notificationsEnabled);
+  const userId = account.status === 'signed-in' ? account.user.id : null;
+
+  useEffect(() => {
+    if (!hydrated) return;
+
+    const open = (response: Notifications.NotificationResponse) => {
+      const route = resolveNotificationRoute(response.notification.request.content.data, hosts);
+      if (route) router.push(route);
+    };
+
+    const initial = Notifications.getLastNotificationResponse();
+    if (initial) {
+      open(initial);
+      Notifications.clearLastNotificationResponse();
+    }
+    const subscription = Notifications.addNotificationResponseReceivedListener(open);
+    return () => subscription.remove();
+  }, [hosts, hydrated, router]);
+
+  useEffect(() => {
+    if (!enabled || !userId) return;
+
+    const sync = (devicePushToken?: Notifications.DevicePushToken) => {
+      syncDevicePushToken(userId, devicePushToken).catch((error: unknown) =>
+        Sentry.captureException(error),
+      );
+    };
+
+    sync();
+    const tokenSubscription = Notifications.addPushTokenListener(sync);
+    const appStateSubscription = AppState.addEventListener('change', (state) => {
+      if (state === 'active') sync();
+    });
+    return () => {
+      tokenSubscription.remove();
+      appStateSubscription.remove();
+    };
+  }, [enabled, userId]);
+
+  return null;
+}
diff --git a/apps/mobile/src/runtime/__tests__/notification-route.test.ts b/apps/mobile/src/runtime/__tests__/notification-route.test.ts
new file mode 100644
index 000000000..e3fe7fc48
--- /dev/null
+++ b/apps/mobile/src/runtime/__tests__/notification-route.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { resolveNotificationRoute } from '../notification-route';
+
+describe('resolveNotificationRoute', () => {
+  const hosts = [{ id: 'local host', tunnelHostId: 'tunnel-1' }];
+
+  it('routes known tunnel hosts, falls back for unknown hosts, and rejects invalid data', () => {
+    expect(
+      resolveNotificationRoute({ tunnelHostId: 'tunnel-1', sessionId: 'session/1' }, hosts),
+    ).toBe('/host/local%20host/session/session%2F1');
+    expect(
+      resolveNotificationRoute({ tunnelHostId: 'tunnel-2', sessionId: 'session-2' }, hosts),
+    ).toBe('/connect');
+    expect(resolveNotificationRoute({ tunnelHostId: 'tunnel-1' }, hosts)).toBeNull();
+  });
+});
diff --git a/apps/mobile/src/runtime/cloud/account.ts b/apps/mobile/src/runtime/cloud/account.ts
index 664e4850c..2c3100fc2 100644
--- a/apps/mobile/src/runtime/cloud/account.ts
+++ b/apps/mobile/src/runtime/cloud/account.ts
@@ -1,3 +1,5 @@
+import { revokeDevicePushToken } from '@mobile/runtime/notifications';
+import { useSettingsStore } from '@mobile/stores/settings-store';
 import { noop } from 'foxact/noop';
 import { cloudAuthClient } from './client';
 import { clearDeviceEnrollment } from './devices';
@@ -39,6 +41,11 @@ export async function signInToCloud(): Promise<void> {
 }
 
 export async function signOutOfCloud(): Promise<void> {
+  const settings = useSettingsStore.getState();
+  if (settings.notificationsEnabled) {
+    await revokeDevicePushToken();
+    settings.setNotificationsEnabled(false);
+  }
   await cloudAuthClient.signOut();
   // Forget the enrollment so a different account signing in on this phone
   // registers the device under itself instead of silently skipping.
diff --git a/apps/mobile/src/runtime/cloud/devices.ts b/apps/mobile/src/runtime/cloud/devices.ts
index dded0960e..9771bf29e 100644
--- a/apps/mobile/src/runtime/cloud/devices.ts
+++ b/apps/mobile/src/runtime/cloud/devices.ts
@@ -61,6 +61,21 @@ export async function clearDeviceEnrollment(): Promise<void> {
   await SecureStore.deleteItemAsync(ENROLLMENT_KEY);
 }
 
+export async function registerDevicePushToken(expoPushToken: string): Promise<void> {
+  const { error } = await cloudAuthClient.$fetch<unknown>(`${CLOUD_URL}/devices/push-token`, {
+    method: 'PUT',
+    body: { expoPushToken },
+  });
+  if (error) throw new Error(`push token registration failed (${error.status})`);
+}
+
+export async function revokeDevicePushToken(): Promise<void> {
+  const { error } = await cloudAuthClient.$fetch<unknown>(`${CLOUD_URL}/devices/push-token`, {
+    method: 'DELETE',
+  });
+  if (error) throw new Error(`push token revocation failed (${error.status})`);
+}
+
 /** Client view of cloud device rows; timestamps arrive as ISO strings over JSON. */
 export const CloudDeviceSchema = z.object({
   id: z.string().min(1),
diff --git a/apps/mobile/src/runtime/notification-route.ts b/apps/mobile/src/runtime/notification-route.ts
new file mode 100644
index 000000000..25d797c19
--- /dev/null
+++ b/apps/mobile/src/runtime/notification-route.ts
@@ -0,0 +1,23 @@
+import { SessionIdSchema } from '@linkcode/schema';
+import { z } from 'zod';
+
+const NotificationDataSchema = z.object({
+  tunnelHostId: z.string().min(1),
+  sessionId: SessionIdSchema,
+});
+
+interface NotificationHost {
+  id: string;
+  tunnelHostId?: string;
+}
+
+export function resolveNotificationRoute(
+  data: unknown,
+  hosts: readonly NotificationHost[],
+): string | null {
+  const parsed = NotificationDataSchema.safeParse(data);
+  if (!parsed.success) return null;
+  const host = hosts.find((candidate) => candidate.tunnelHostId === parsed.data.tunnelHostId);
+  if (!host) return '/connect';
+  return `/host/${encodeURIComponent(host.id)}/session/${encodeURIComponent(parsed.data.sessionId)}`;
+}
diff --git a/apps/mobile/src/runtime/notifications.ts b/apps/mobile/src/runtime/notifications.ts
new file mode 100644
index 000000000..c88ffe356
--- /dev/null
+++ b/apps/mobile/src/runtime/notifications.ts
@@ -0,0 +1,61 @@
+import {
+  ensureDeviceRegistered,
+  registerDevicePushToken,
+  revokeDevicePushToken,
+} from '@mobile/runtime/cloud/devices';
+import Constants from 'expo-constants';
+import * as Device from 'expo-device';
+import type { DevicePushToken } from 'expo-notifications';
+import * as Notifications from 'expo-notifications';
+
+export const NOTIFICATION_CHANNEL_ID = 'session-events';
+
+Notifications.setNotificationHandler({
+  handleNotification: () =>
+    Promise.resolve({
+      shouldPlaySound: true,
+      shouldSetBadge: false,
+      shouldShowBanner: true,
+      shouldShowList: true,
+    }),
+});
+
+function permissionGranted(settings: Notifications.NotificationPermissionsStatus): boolean {
+  return (
+    settings.granted || settings.ios?.status === Notifications.IosAuthorizationStatus.PROVISIONAL
+  );
+}
+
+export async function requestNotificationPermission(): Promise<boolean> {
+  if (process.env.EXPO_OS === 'android') {
+    await Notifications.setNotificationChannelAsync(NOTIFICATION_CHANNEL_ID, {
+      name: 'Session events',
+      importance: Notifications.AndroidImportance.HIGH,
+      sound: 'default',
+    });
+  }
+
+  const current = await Notifications.getPermissionsAsync();
+  if (permissionGranted(current)) return true;
+  if (!current.canAskAgain) return false;
+  return permissionGranted(await Notifications.requestPermissionsAsync());
+}
+
+export async function syncDevicePushToken(
+  userId: string,
+  devicePushToken?: DevicePushToken,
+): Promise<void> {
+  if (!Device.isDevice) throw new Error('push notifications require a physical device');
+  const projectId = Constants.expoConfig?.extra?.eas?.projectId;
+  if (typeof projectId !== 'string' || !projectId) {
+    throw new Error('Expo project ID is missing');
+  }
+  await ensureDeviceRegistered(userId);
+  const expoPushToken = await Notifications.getExpoPushTokenAsync({
+    projectId,
+    devicePushToken,
+  });
+  await registerDevicePushToken(expoPushToken.data);
+}
+
+export { revokeDevicePushToken };
diff --git a/apps/mobile/src/stores/settings-store.ts b/apps/mobile/src/stores/settings-store.ts
index d71b44011..ba1a941bb 100644
--- a/apps/mobile/src/stores/settings-store.ts
+++ b/apps/mobile/src/stores/settings-store.ts
@@ -8,25 +8,37 @@ export const ThemePreferenceSchema = z.enum(['system', 'light', 'dark']);
 export type ThemePreference = z.infer<typeof ThemePreferenceSchema>;
 
 /** Persisted subset — every field optional so partial/stale storage merges over the defaults. */
-const PersistedSettingsSchema = z.object({ themePreference: ThemePreferenceSchema }).partial();
+const PersistedSettingsSchema = z
+  .object({
+    themePreference: ThemePreferenceSchema,
+    notificationsEnabled: z.boolean(),
+  })
+  .partial();
 type PersistedSettings = z.infer<typeof PersistedSettingsSchema>;
 
 export interface SettingsState {
   themePreference: ThemePreference;
+  notificationsEnabled: boolean;
   setThemePreference: (preference: ThemePreference) => void;
+  setNotificationsEnabled: (enabled: boolean) => void;
 }
 
 export const useSettingsStore = create<SettingsState>()(
   zodPersist<SettingsState, [], [], PersistedSettings, PersistedSettings>(
     (set) => ({
       themePreference: 'system',
+      notificationsEnabled: false,
       setThemePreference: (preference) => set({ themePreference: preference }),
+      setNotificationsEnabled: (enabled) => set({ notificationsEnabled: enabled }),
     }),
     {
       name: 'linkcode.mobile.settings:v1',
       schema: PersistedSettingsSchema,
       storage: createJSONStorage(() => Storage),
-      partialize: (state) => ({ themePreference: state.themePreference }),
+      partialize: (state) => ({
+        themePreference: state.themePreference,
+        notificationsEnabled: state.notificationsEnabled,
+      }),
     },
   ),
 );
diff --git a/packages/presentation/i18n/src/locales/en.ts b/packages/presentation/i18n/src/locales/en.ts
index 89dfaf30d..45667bff0 100644
--- a/packages/presentation/i18n/src/locales/en.ts
+++ b/packages/presentation/i18n/src/locales/en.ts
@@ -1189,6 +1189,7 @@ export const en = {
     account: {
       title: 'Account',
       signOut: 'Sign out',
+      signOutError: 'Could not sign out. Check your connection and try again.',
       devices: 'Devices',
       refresh: 'Refresh',
       devicesEmpty: 'No devices registered on this account yet.',
@@ -1313,6 +1314,15 @@ export const en = {
       analytics: 'Share usage analytics',
       analyticsHint:
         'Send feature usage events without conversations, code, paths, or terminal content. Off by default.',
+      notifications: 'Notifications',
+      notificationsHint: 'Notify you when a Thread finishes a turn or needs approval.',
+      notificationsRequiresCloud: 'Sign in to LinkCode Cloud to enable remote notifications.',
+      notificationsDeniedTitle: 'Notifications are off',
+      notificationsDenied: 'Allow notifications in system settings to enable this feature.',
+      notificationsErrorTitle: 'Could not update notifications',
+      notificationsError: 'Try again after checking your network and system settings.',
+      openSettings: 'Open Settings',
+      cancel: 'Cancel',
       legalAndSupport: 'Legal & Support',
       privacyPolicy: 'Privacy Policy',
       termsOfService: 'Terms of Service',
diff --git a/packages/presentation/i18n/src/locales/zh-cn.ts b/packages/presentation/i18n/src/locales/zh-cn.ts
index e3d58820d..cbc82fc44 100644
--- a/packages/presentation/i18n/src/locales/zh-cn.ts
+++ b/packages/presentation/i18n/src/locales/zh-cn.ts
@@ -1158,6 +1158,7 @@ export const zhCN = {
     account: {
       title: '账号',
       signOut: '退出登录',
+      signOutError: '无法退出登录，请检查网络后重试。',
       devices: '设备',
       refresh: '刷新',
       devicesEmpty: '该账号还没有注册设备。',
@@ -1279,6 +1280,15 @@ export const zhCN = {
       privacy: '隐私',
       analytics: '共享使用分析',
       analyticsHint: '发送功能使用事件，不包含对话、代码、路径或终端内容。默认关闭。',
+      notifications: '通知',
+      notificationsHint: 'Thread 完成一轮或需要授权时通知你。',
+      notificationsRequiresCloud: '登录 LinkCode Cloud 后可启用远程通知。',
+      notificationsDeniedTitle: '通知已关闭',
+      notificationsDenied: '请在系统设置中允许通知后再启用此功能。',
+      notificationsErrorTitle: '无法更新通知',
+      notificationsError: '请检查网络和系统设置后重试。',
+      openSettings: '打开设置',
+      cancel: '取消',
       legalAndSupport: '法律与支持',
       privacyPolicy: '隐私政策',
       termsOfService: '服务条款',