neoagent 2.3.1-beta.62 → 2.3.1-beta.63

package/.env.example

@@ -51,6 +51,15 @@ NEOAGENT_RELEASE_CHANNEL=stable
 # Example: http://localhost:3333,https://yourdomain.com
 ALLOWED_ORIGINS=
 
+########################################
+# Analytics
+########################################
+
+# Mixpanel project token used by the Flutter app.
+# Leave this blank to disable analytics, or set your own public project token.
+# Keep the token below if you want to support the development of NeoAgent with anonymous usage analytics.
+NEOAGENT_MIXPANEL_TOKEN=4a47ae6a05cf39a8faf0438a1200dde6
+
 ########################################
 # Service email
 ########################################

package/docs/configuration.md

@@ -18,6 +18,17 @@ AI provider credentials, OAuth client secrets, and deployment controls are not c
 | `NEOAGENT_DEPLOYMENT_MODE` | `self_hosted` | `self_hosted` enables in-app update controls; `managed` hides operator-only controls for SaaS deployments. |
 | `NEOAGENT_RELEASE_CHANNEL` | `stable` | Release track used by the self-hosted updater. |
 
+## Analytics
+
+NeoAgent can send anonymous Mixpanel usage events from the Flutter client. The events cover app startup, section navigation, auth success, backend setup, onboarding dismissal, chat sends, recording start/stop, task runs, update checks, and update triggers. They do not include message content, credentials, or other app data.
+
+Set `NEOAGENT_MIXPANEL_TOKEN` to your own public Mixpanel project token to enable analytics. Leave it blank to disable analytics entirely.
+When analytics is enabled, the web client shows a dismissible cookie-consent banner until the user accepts or declines.
+
+| Variable | Default | Description |
+|---|---:|---|
+| `NEOAGENT_MIXPANEL_TOKEN` | optional | Public Mixpanel project token used by the Flutter client. |
+
 ## Service Email
 
 Service email is optional. When `NEOAGENT_EMAIL_FROM` and `NEOAGENT_EMAIL_SMTP_HOST` are set, NeoAgent uses SMTP for account security flows: signup confirmation, password reset, unusual login notifications, password change notifications, and email change notifications. Confirmation and reset links use the same `PUBLIC_URL` base as the other server-generated links.

package/flutter_app/lib/main.dart

@@ -26,6 +26,7 @@ import 'src/android_apk_drop_zone.dart';
 import 'src/android_launcher_bridge.dart';
 import 'src/app_launch_bridge.dart';
 import 'src/app_release_updater.dart' as app_release_updater;
+import 'src/analytics_service.dart';
 import 'src/backend_client.dart';
 import 'src/desktop_companion.dart';
 import 'src/desktop_screen_capture.dart';

package/flutter_app/lib/main_controller.dart

@@ -37,6 +37,7 @@ class NeoAgentController extends ChangeNotifier {
   final OAuthLauncher _oauthLauncher;
   final app_release_updater.AppReleaseUpdater _appReleaseUpdater =
       app_release_updater.AppReleaseUpdater();
+  final AppAnalytics _analytics = AppAnalytics();
   final LiveVoiceCapture _liveVoiceCapture = LiveVoiceCapture();
   final DesktopScreenCapture _desktopScreenCapture =
       createDesktopScreenCapture();
@@ -98,6 +99,10 @@ class NeoAgentController extends ChangeNotifier {
   bool networkStatusKnown = false;
   bool _desktopFloatingToolbarPopupRequested = false;
   bool _voiceAssistantIncludeScreenContext = false;
+  bool _didTrackAppOpen = false;
+  bool _analyticsConfigured = false;
+  bool _analyticsConsentResolved = false;
+  bool _analyticsConsentGranted = false;
 
   bool hasUser = true;
   bool registrationOpen = false;
@@ -319,6 +324,7 @@ class NeoAgentController extends ChangeNotifier {
     _diagnosticLogSubscription?.cancel();
     _connectivitySubscription?.cancel();
     _appReleaseUpdater.dispose();
+    unawaited(_analytics.dispose());
     _desktopCompanion.removeListener(notifyListeners);
     unawaited(_desktopCompanion.disconnect());
     _recordingBridge.removeListener(_handleRecordingBridgeChanged);
@@ -349,6 +355,12 @@ class NeoAgentController extends ChangeNotifier {
   bool get canCaptureVoiceAssistantScreenContext =>
       _desktopScreenCapture.isSupported;
 
+  bool get showAnalyticsConsentBanner =>
+      kIsWeb && _analyticsConfigured && !_analyticsConsentResolved;
+
+  bool get analyticsConsentGranted =>
+      _analyticsConsentResolved && _analyticsConsentGranted;
+
   bool get isLiveVoiceCaptureEngaged =>
       _isStartingLiveVoice || _liveVoiceCaptureActive;
 
@@ -701,6 +713,7 @@ class NeoAgentController extends ChangeNotifier {
     appUpdateAutoCheckEnabled =
         _prefs?.getBool('app.update.autoCheckEnabled') ?? true;
     installedAppVersion = await _safeLoadInstalledAppVersion();
+    await _initializeAnalytics();
     await refreshConnectivityStatus();
     if (_connectivityPluginAvailable && _connectivitySubscription == null) {
       try {
@@ -862,6 +875,101 @@ class NeoAgentController extends ChangeNotifier {
     }
   }
 
+  Future<void> _initializeAnalytics() async {
+    try {
+      final runtimeConfig = await _backendClient.fetchRuntimeConfig(backendUrl);
+      final analyticsConfig = runtimeConfig['analytics'];
+      final mixpanelConfig = analyticsConfig is Map
+          ? analyticsConfig['mixpanel']
+          : null;
+      final token = mixpanelConfig is Map
+          ? mixpanelConfig['token']?.toString()
+          : null;
+      _analyticsConfigured = token != null && token.trim().isNotEmpty;
+      final consentState = _prefs?.getBool('analytics.cookieConsent');
+      _analyticsConsentResolved = consentState != null;
+      _analyticsConsentGranted = consentState == true;
+      await _analytics.initialize(
+        token: token,
+        consentGranted: _analyticsConsentGranted,
+      );
+      _trackAppOpenedIfNeeded();
+    } catch (_) {
+      _analyticsConfigured = false;
+      _analyticsConsentResolved = false;
+      _analyticsConsentGranted = false;
+      await _analytics.initialize(token: null, consentGranted: false);
+    }
+  }
+
+  void _trackAppOpenedIfNeeded({String? consentSource}) {
+    if (!_analytics.enabled || _didTrackAppOpen) {
+      return;
+    }
+    _didTrackAppOpen = true;
+    unawaited(
+      _analytics.trackAppOpened(
+        appMode: appMode.name,
+        platform: _analyticsPlatformLabel(),
+        backendMode: backendUrl.trim().isEmpty ? 'same_origin' : 'custom',
+        selectedSection: selectedSection.label,
+        deploymentProfile: deploymentProfile,
+        authenticated: isAuthenticated,
+      ),
+    );
+    if (consentSource != null) {
+      unawaited(
+        _analytics.track(
+          'analytics_consent_granted',
+          properties: <String, Object?>{'consent_source': consentSource},
+        ),
+      );
+    }
+  }
+
+  String _analyticsPlatformLabel() {
+    if (kIsWeb) {
+      return 'web';
+    }
+    switch (defaultTargetPlatform) {
+      case TargetPlatform.android:
+        return 'android';
+      case TargetPlatform.iOS:
+        return 'ios';
+      case TargetPlatform.macOS:
+        return 'macos';
+      case TargetPlatform.windows:
+        return 'windows';
+      case TargetPlatform.linux:
+        return 'linux';
+      case TargetPlatform.fuchsia:
+        return 'fuchsia';
+    }
+  }
+
+  Future<void> acceptAnalyticsConsent() async {
+    if (!_analyticsConfigured) {
+      return;
+    }
+    _analyticsConsentResolved = true;
+    _analyticsConsentGranted = true;
+    await _prefs?.setBool('analytics.cookieConsent', true);
+    await _analytics.setConsentGranted(true);
+    _trackAppOpenedIfNeeded(consentSource: 'banner');
+    notifyListeners();
+  }
+
+  Future<void> declineAnalyticsConsent() async {
+    if (!_analyticsConfigured) {
+      return;
+    }
+    _analyticsConsentResolved = true;
+    _analyticsConsentGranted = false;
+    await _prefs?.setBool('analytics.cookieConsent', false);
+    await _analytics.setConsentGranted(false);
+    notifyListeners();
+  }
+
   Future<void> setAppUpdateChannel(String channel) async {
     final normalized = channel.trim().toLowerCase() == 'beta'
         ? 'beta'
@@ -886,6 +994,7 @@ class NeoAgentController extends ChangeNotifier {
     if (isCheckingAppUpdate) {
       return;
     }
+    unawaited(_analytics.trackAppUpdateCheck(silent: silent));
     if (!appUpdaterConfigured) {
       appUpdateErrorMessage = kIsWeb
           ? 'Client app update checks are unavailable in the web app.'
@@ -975,6 +1084,11 @@ class NeoAgentController extends ChangeNotifier {
       isBooting = true;
       notifyListeners();
       await bootstrap();
+      unawaited(
+        _analytics.trackBackendUrlSaved(
+          backendMode: backendUrl.trim().isEmpty ? 'same_origin' : 'custom',
+        ),
+      );
       return true;
     } catch (error) {
       errorMessage = _friendlyErrorMessage(error);
@@ -1147,6 +1261,7 @@ class NeoAgentController extends ChangeNotifier {
         response,
         retentionErrorMessage:
             'QR login completed, but NeoAgent could not keep the session. Please try again.',
+        authMethod: 'qr',
       );
     } catch (error) {
       final message = _friendlyErrorMessage(error);
@@ -1199,6 +1314,7 @@ class NeoAgentController extends ChangeNotifier {
     String? fallbackUsername,
     String? retentionErrorMessage,
     bool isRegistration = false,
+    String authMethod = 'password',
   }) async {
     user = Map<String, dynamic>.from(
       response['user'] as Map<dynamic, dynamic>? ??
@@ -1220,6 +1336,14 @@ class NeoAgentController extends ChangeNotifier {
     _clearQrLoginChallenge();
     await _persistCredentials();
     await refresh();
+    if (isAuthenticated) {
+      unawaited(
+        _analytics.trackSignedIn(
+          authMethod: authMethod,
+          isRegistration: isRegistration,
+        ),
+      );
+    }
     if (!isAuthenticated && retentionErrorMessage != null) {
       errorMessage = retentionErrorMessage;
     }
@@ -1289,6 +1413,7 @@ class NeoAgentController extends ChangeNotifier {
       await _completeAuthenticatedResponse(
         response,
         isRegistration: register,
+        authMethod: 'oauth',
         retentionErrorMessage:
             'Sign-in completed, but NeoAgent could not keep the browser session. Please sign in again. If this keeps happening, check backend session cookie settings.',
       );
@@ -1315,6 +1440,7 @@ class NeoAgentController extends ChangeNotifier {
       await _completeAuthenticatedResponse(
         response,
         fallbackUsername: pendingTwoFactorUsername,
+        authMethod: 'two_factor',
         retentionErrorMessage:
             'Two-factor sign-in completed, but NeoAgent could not keep the browser session. Please sign in again.',
       );
@@ -1405,6 +1531,7 @@ class NeoAgentController extends ChangeNotifier {
         response,
         fallbackUsername: username,
         isRegistration: register,
+        authMethod: 'password',
         retentionErrorMessage:
             'Sign-in completed, but NeoAgent could not keep the browser session. Please sign in again. If this keeps happening, the backend session cookie is likely not being retained.',
       );
@@ -1435,6 +1562,7 @@ class NeoAgentController extends ChangeNotifier {
     final logoutFuture = _backendClient.logout(backendUrl);
     _authCycle += 1;
     _clearAuthenticatedState();
+    unawaited(_analytics.trackSignedOut());
     isAuthenticating = true;
     notifyListeners();
 
@@ -1451,6 +1579,7 @@ class NeoAgentController extends ChangeNotifier {
     notifyListeners();
     try {
       await _backendClient.completeOnboarding(backendUrl);
+      unawaited(_analytics.trackOnboardingDismissed());
       if (isAuthenticated && user != null) {
         user!['hasCompletedOnboarding'] = true;
       }
@@ -1604,6 +1733,7 @@ class NeoAgentController extends ChangeNotifier {
   }
 
   void setSelectedSection(AppSection section) {
+    final previousSection = selectedSection;
     selectedSection = section;
     unawaited(_prefs?.setString(_selectedSectionPrefsKey, section.name));
     if (section == AppSection.devices) {
@@ -1612,6 +1742,14 @@ class NeoAgentController extends ChangeNotifier {
     if (section == AppSection.accountSettings) {
       unawaited(refreshAccountSettings());
     }
+    if (previousSection != section) {
+      unawaited(
+        _analytics.trackSectionChanged(
+          section: section.label,
+          previousSection: previousSection.label,
+        ),
+      );
+    }
     notifyListeners();
   }
 
@@ -2422,6 +2560,9 @@ class NeoAgentController extends ChangeNotifier {
   }
 
   Future<void> refreshWidgets({bool all = false}) async {
+    if (all) {
+      unawaited(_analytics.trackWidgetRefreshRequested(all: all));
+    }
     widgets = _decodeModelList(
       'widgets',
       await _backendClient.fetchWidgets(
@@ -3224,6 +3365,7 @@ class NeoAgentController extends ChangeNotifier {
   }
 
   Future<void> startBackgroundRecording() async {
+    unawaited(_analytics.trackRecordingStarted(kind: 'background'));
     await _startRecordingCapture(
       logKey: 'start_background',
       payload: buildAndroidBackgroundRecordingPayload(),
@@ -3250,6 +3392,7 @@ class NeoAgentController extends ChangeNotifier {
       }
       return;
     }
+    unawaited(_analytics.trackRecordingStarted(kind: 'desktop'));
     await _startRecordingCapture(
       logKey: 'start_desktop',
       payload: buildDesktopRecordingPayload(),
@@ -3633,6 +3776,15 @@ class NeoAgentController extends ChangeNotifier {
     notifyListeners();
     try {
       _desktopFloatingToolbarPopupRequested = false;
+      unawaited(
+        _analytics.trackRecordingStopped(
+          kind: recordingRuntime.supportsBackgroundMic &&
+                  !recordingRuntime.supportsScreenAndMic
+              ? 'background'
+              : 'desktop',
+          stopReason: stopReason,
+        ),
+      );
       await _recordingBridge.stopActiveRecording();
       if (isAndroidBackgroundStop) {
         await Future<void>.delayed(const Duration(milliseconds: 600));
@@ -4261,6 +4413,12 @@ class NeoAgentController extends ChangeNotifier {
     if (trimmed.isEmpty || (isSendingMessage && !canSteerLiveRun)) {
       return;
     }
+    unawaited(
+      _analytics.trackChatMessageSent(
+        length: trimmed.length,
+        steeringLiveRun: canSteerLiveRun,
+      ),
+    );
 
     final optimistic = ChatEntry(
       id: '',
@@ -4682,6 +4840,7 @@ class NeoAgentController extends ChangeNotifier {
     errorMessage = null;
     notifyListeners();
     try {
+      unawaited(_analytics.trackAppUpdateTriggered());
       await _backendClient.triggerUpdate(backendUrl);
       await refreshUpdateStatus();
     } catch (error) {
@@ -5412,8 +5571,7 @@ class NeoAgentController extends ChangeNotifier {
       return;
     }
     _pendingChatDraft = normalized;
-    selectedSection = AppSection.chat;
-    notifyListeners();
+    setSelectedSection(AppSection.chat);
   }
 
   String? takePendingChatDraft() {
@@ -5432,17 +5590,15 @@ class NeoAgentController extends ChangeNotifier {
 
   void openWidgetSurface(String widgetId) {
     final normalized = widgetId.trim();
-    selectedSection = AppSection.widgets;
+    setSelectedSection(AppSection.widgets);
     if (normalized.isNotEmpty) {
       _selectedWidgetId = normalized;
       unawaited(refreshWidgets(all: true));
     }
-    notifyListeners();
   }
 
   void openVoiceAssistantSurface() {
-    selectedSection = AppSection.voiceAssistant;
-    notifyListeners();
+    setSelectedSection(AppSection.voiceAssistant);
   }
 
   String? get selectedWidgetId => _selectedWidgetId;
@@ -5475,6 +5631,7 @@ class NeoAgentController extends ChangeNotifier {
       return;
     }
     _startManualRunCooldown('task', '$id');
+    unawaited(_analytics.trackTaskRunRequested(taskId: id));
     await _backendClient.runSavedTask(backendUrl, id);
     await refreshTasks();
     await refreshRunsOnly();

package/flutter_app/lib/main_runtime.dart

@@ -627,6 +627,28 @@ class _NeoAgentAppState extends State<NeoAgentApp>
                       ),
                     ),
                   ),
+                if (!_desktopToolbarWindowMode &&
+                    !_desktopAssistantPopupWindowMode &&
+                    _controller.showAnalyticsConsentBanner)
+                  Positioned(
+                    left: 0,
+                    right: 0,
+                    bottom: 0,
+                    child: SafeArea(
+                      top: false,
+                      child: Padding(
+                        padding: const EdgeInsets.fromLTRB(12, 0, 12, 12),
+                        child: Center(
+                          child: ConstrainedBox(
+                            constraints: const BoxConstraints(maxWidth: 980),
+                            child: _GlobalAnalyticsConsentBanner(
+                              controller: _controller,
+                            ),
+                          ),
+                        ),
+                      ),
+                    ),
+                  ),
                 if (_supportsDesktopShell &&
                     !_desktopToolbarWindowMode &&
                     !_desktopAssistantPopupWindowMode)

package/flutter_app/lib/main_settings.dart

@@ -195,11 +195,21 @@ class _SettingsPanelState extends State<SettingsPanel> {
     final modelChoices = <DropdownMenuItem<String>>[
       const DropdownMenuItem<String>(
         value: 'auto',
-        child: Text('Smart Selector (Auto)'),
+        child: Text(
+          'Smart Selector (Auto)',
+          maxLines: 1,
+          overflow: TextOverflow.ellipsis,
+        ),
       ),
       ...routingModels.map(
-        (model) =>
-            DropdownMenuItem<String>(value: model.id, child: Text(model.label)),
+        (model) => DropdownMenuItem<String>(
+          value: model.id,
+          child: Text(
+            model.label,
+            maxLines: 1,
+            overflow: TextOverflow.ellipsis,
+          ),
+        ),
       ),
     ];
     final enabledSmartModels = _enabledModels
@@ -634,7 +644,11 @@ class _SettingsPanelState extends State<SettingsPanel> {
                               .map(
                                 (model) => DropdownMenuItem<String>(
                                   value: model.id,
-                                  child: Text(model.label),
+                                  child: Text(
+                                    model.label,
+                                    maxLines: 1,
+                                    overflow: TextOverflow.ellipsis,
+                                  ),
                                 ),
                               )
                               .toList(),
@@ -2030,6 +2044,7 @@ class _RoutingSelectCard extends StatelessWidget {
           DropdownButtonFormField<String>(
             initialValue: value,
             items: items,
+            isExpanded: true,
             decoration: const InputDecoration(isDense: true),
             onChanged: onChanged,
           ),

package/flutter_app/lib/main_shared.dart

@@ -1826,6 +1826,167 @@ class _GlobalWebUpdateBanner extends StatelessWidget {
   }
 }
 
+class _GlobalAnalyticsConsentBanner extends StatelessWidget {
+  const _GlobalAnalyticsConsentBanner({required this.controller});
+
+  final NeoAgentController controller;
+
+  @override
+  Widget build(BuildContext context) {
+    return LayoutBuilder(
+      builder: (context, constraints) {
+        final compact = constraints.maxWidth < 700;
+        final body = Text(
+          'NeoAgent uses anonymous analytics to understand startup, navigation, and setup flows. No messages, credentials, or personal content are collected.',
+          style: TextStyle(color: _textSecondary, height: 1.35),
+        );
+        return Material(
+          color: Colors.transparent,
+          child: _GlassSurface(
+            borderRadius: BorderRadius.circular(22),
+            blurSigma: 26,
+            fillColor: _bgCard.withValues(alpha: 0.94),
+            borderColor: _accent.withValues(alpha: 0.18),
+            overlayGradient: LinearGradient(
+              colors: <Color>[
+                _accent.withValues(alpha: 0.12),
+                _bgCard.withValues(alpha: 0.88),
+                _bgSecondary.withValues(alpha: 0.86),
+              ],
+              stops: const <double>[0, 0.22, 1],
+              begin: const Alignment(-1, -1),
+              end: const Alignment(1, 1),
+            ),
+            boxShadow: <BoxShadow>[
+              BoxShadow(
+                color: Colors.black.withValues(alpha: 0.22),
+                blurRadius: 34,
+                offset: const Offset(0, 18),
+              ),
+              BoxShadow(
+                color: _accent.withValues(alpha: 0.1),
+                blurRadius: 24,
+                offset: const Offset(0, 8),
+              ),
+            ],
+            padding: const EdgeInsets.symmetric(horizontal: 18, vertical: 16),
+            child: compact
+                ? Column(
+                    crossAxisAlignment: CrossAxisAlignment.start,
+                    children: <Widget>[
+                      Row(
+                        crossAxisAlignment: CrossAxisAlignment.start,
+                        children: <Widget>[
+                          Container(
+                            padding: const EdgeInsets.all(10),
+                            decoration: BoxDecoration(
+                              color: _accent.withValues(alpha: 0.16),
+                              shape: BoxShape.circle,
+                              border: Border.all(
+                                color: _accent.withValues(alpha: 0.24),
+                              ),
+                            ),
+                            child: Icon(
+                              Icons.cookie_outlined,
+                              color: _accent,
+                              size: 22,
+                            ),
+                          ),
+                          const SizedBox(width: 12),
+                          Expanded(
+                            child: Column(
+                              crossAxisAlignment: CrossAxisAlignment.start,
+                              children: <Widget>[
+                                Text(
+                                  'Analytics cookies',
+                                  style: TextStyle(
+                                    color: _textPrimary,
+                                    fontSize: 15,
+                                    fontWeight: FontWeight.w700,
+                                  ),
+                                ),
+                                const SizedBox(height: 6),
+                                body,
+                              ],
+                            ),
+                          ),
+                        ],
+                      ),
+                      const SizedBox(height: 14),
+                      Row(
+                        children: <Widget>[
+                          Expanded(
+                            child: OutlinedButton(
+                              onPressed: controller.declineAnalyticsConsent,
+                              child: const Text('Decline'),
+                            ),
+                          ),
+                          const SizedBox(width: 10),
+                          Expanded(
+                            child: FilledButton(
+                              onPressed: controller.acceptAnalyticsConsent,
+                              child: const Text('Allow analytics'),
+                            ),
+                          ),
+                        ],
+                      ),
+                    ],
+                  )
+                : Row(
+                    crossAxisAlignment: CrossAxisAlignment.center,
+                    children: <Widget>[
+                      Container(
+                        padding: const EdgeInsets.all(10),
+                        decoration: BoxDecoration(
+                          color: _accent.withValues(alpha: 0.16),
+                          shape: BoxShape.circle,
+                          border: Border.all(
+                            color: _accent.withValues(alpha: 0.24),
+                          ),
+                        ),
+                        child: Icon(
+                          Icons.cookie_outlined,
+                          color: _accent,
+                          size: 22,
+                        ),
+                      ),
+                      const SizedBox(width: 14),
+                      Expanded(
+                        child: Column(
+                          crossAxisAlignment: CrossAxisAlignment.start,
+                          children: <Widget>[
+                            Text(
+                              'Analytics cookies',
+                              style: TextStyle(
+                                color: _textPrimary,
+                                fontSize: 15,
+                                fontWeight: FontWeight.w700,
+                              ),
+                            ),
+                            const SizedBox(height: 6),
+                            body,
+                          ],
+                        ),
+                      ),
+                      const SizedBox(width: 16),
+                      OutlinedButton(
+                        onPressed: controller.declineAnalyticsConsent,
+                        child: const Text('Decline'),
+                      ),
+                      const SizedBox(width: 10),
+                      FilledButton(
+                        onPressed: controller.acceptAnalyticsConsent,
+                        child: const Text('Allow analytics'),
+                      ),
+                    ],
+                  ),
+          ),
+        );
+      },
+    );
+  }
+}
+
 class _DesktopCloseDecision {
   const _DesktopCloseDecision({
     required this.keepRunning,