feat(ui): add comprehensive logging framework with file output to all services and widgets

Adds the `logging` package and a central AppLogger service that writes
structured logs to stderr and optionally to /tmp/agent-studio.log.
Instruments all key services (ApiClient, WsClient) and every major page/widget
(GenUiChatPage, AgentEditor, SettingsPage tabs, ToolsPage, SessionsPage,
MetricsPage, RulesPage, sidebar, onboarding) with contextual log statements
at INFO/FINE/WARNING/SEVERE levels for request tracing, error diagnosis,
and lifecycle visibility.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: lapc506

ui/lib/features/agents/agent_editor_page.dart

@@ -1,5 +1,6 @@
 import 'dart:async';
 import 'package:flutter/material.dart';
+import 'package:logging/logging.dart';
 import '../../services/api_client.dart';
 import '../../services/soul_md_generator.dart';
 import '../../theme/agent_studio_theme.dart';
@@ -17,6 +18,7 @@ class AgentEditorPage extends StatefulWidget {
 
 class _AgentEditorPageState extends State<AgentEditorPage>
     with SingleTickerProviderStateMixin {
+  static final _log = Logger('AgentEditor');
   final _api = ApiClient();
   late TabController _tabController;
   Map<String, dynamic> _agent = {};
@@ -32,15 +34,18 @@ class _AgentEditorPageState extends State<AgentEditorPage>
   }
 
   Future<void> _loadAgent() async {
+    _log.info('Loading agent: ${widget.agentSlug}');
     try {
       final agent = await _api.getAgent(widget.agentSlug);
       final gates = await _api.getGates(widget.agentSlug);
+      _log.info('Agent loaded: ${widget.agentSlug} with ${gates.length} gates');
       setState(() {
         _agent = agent;
         _gates = gates.cast<Map<String, dynamic>>();
         _loading = false;
       });
-    } catch (_) {
+    } catch (e) {
+      _log.warning('Failed to load agent ${widget.agentSlug}, using defaults: $e');
       setState(() {
         _agent = {
           'name': widget.agentSlug,
@@ -55,15 +60,18 @@ class _AgentEditorPageState extends State<AgentEditorPage>
   }
 
   Future<void> _saveAgent() async {
+    _log.info('Saving agent: ${widget.agentSlug}');
     setState(() => _saving = true);
     try {
       await _api.updateAgent(widget.agentSlug, _agent);
+      _log.info('Agent saved successfully: ${widget.agentSlug}');
       if (mounted) {
         ScaffoldMessenger.of(context).showSnackBar(
           const SnackBar(content: Text('Agente guardado'), backgroundColor: AgentStudioTheme.success),
         );
       }
     } catch (e) {
+      _log.warning('Save failed for ${widget.agentSlug}: $e');
       if (mounted) {
         ScaffoldMessenger.of(context).showSnackBar(
           SnackBar(content: Text('Error: $e'), backgroundColor: AgentStudioTheme.error),
@@ -75,10 +83,13 @@ class _AgentEditorPageState extends State<AgentEditorPage>
   }
 
   Future<void> _saveGates(List<Map<String, dynamic>> gates) async {
+    _log.fine('Saving ${gates.length} gates for ${widget.agentSlug}');
     try {
       await _api.updateGates(widget.agentSlug, gates);
-    } catch (_) {
+      _log.fine('Gates saved successfully');
+    } catch (e) {
       // Silently fail — offline-first approach
+      _log.warning('Gates save failed (offline-first): $e');
     }
   }
 

ui/lib/features/agents/rules_page.dart

@@ -1,4 +1,5 @@
 import 'package:flutter/material.dart';
+import 'package:logging/logging.dart';
 import '../../theme/agent_studio_theme.dart';
 
 class RulesPage extends StatefulWidget {
@@ -10,6 +11,7 @@ class RulesPage extends StatefulWidget {
 }
 
 class _RulesPageState extends State<RulesPage> {
+  static final _log = Logger('RulesPage');
   final List<Map<String, dynamic>> _rules = [
     {
       'name': 'Idioma de respuesta',
@@ -173,6 +175,7 @@ class _RulesPageState extends State<RulesPage> {
   }
 
   void _addRule() {
+    _log.info('Opening add rule dialog for agent: ${widget.agentSlug}');
     final nameCtrl = TextEditingController();
     final descCtrl = TextEditingController();
     String selectedType = 'behavior';
@@ -235,6 +238,7 @@ class _RulesPageState extends State<RulesPage> {
             FilledButton(
               onPressed: () {
                 if (nameCtrl.text.isNotEmpty) {
+                  _log.info('Adding rule: ${nameCtrl.text} (type=$selectedType)');
                   setState(() {
                     _rules.add({
                       'name': nameCtrl.text,

ui/lib/features/chat/genui_chat_page.dart

@@ -2,6 +2,7 @@ import 'dart:async';
 
 import 'package:flutter/material.dart';
 import 'package:genui/genui.dart';
+import 'package:logging/logging.dart';
 
 import '../../services/api_client.dart';
 import '../../services/ws_client.dart';
@@ -19,6 +20,7 @@ class GenUiChatPage extends StatefulWidget {
 }
 
 class _GenUiChatPageState extends State<GenUiChatPage> {
+  static final _log = Logger('GenUiChatPage');
   late final SurfaceController _controller;
   final _textController = TextEditingController();
   final _surfaceIds = <String>[];
@@ -57,9 +59,11 @@ class _GenUiChatPageState extends State<GenUiChatPage> {
   // ---------------------------------------------------------------------------
 
   Future<void> _loadAgents() async {
+    _log.info('Loading agents...');
     try {
       var agents = await _apiClient.listAgents();
       if (agents.isEmpty) {
+        _log.info('No agents found, auto-creating demo agent');
         // Auto-create demo agent
         await _apiClient.createAgent({
           'name': 'Asistente Demo',
@@ -69,12 +73,14 @@ class _GenUiChatPageState extends State<GenUiChatPage> {
         });
         agents = await _apiClient.listAgents();
       }
+      _log.info('Loaded ${agents.length} agents');
       setState(() => _agents = agents);
       if (agents.isNotEmpty && _selectedAgent == null) {
         _selectAgent(agents.first['slug'] as String);
       }
-    } catch (_) {
+    } catch (e) {
       // Backend may not be available yet
+      _log.warning('Failed to load agents: $e');
     }
   }
 
@@ -83,6 +89,7 @@ class _GenUiChatPageState extends State<GenUiChatPage> {
   // ---------------------------------------------------------------------------
 
   void _selectAgent(String slug) {
+    _log.info('Selecting agent: $slug');
     // Tear down any previous conversation
     _eventSub?.cancel();
     _conversation?.dispose();
@@ -161,6 +168,7 @@ class _GenUiChatPageState extends State<GenUiChatPage> {
 
   void _onWsMessage(Map<String, dynamic> msg) {
     final type = msg['type'] as String?;
+    _log.fine('WS message: $type');
     switch (type) {
       case 'session_created':
         setState(() {
@@ -257,6 +265,7 @@ class _GenUiChatPageState extends State<GenUiChatPage> {
   void _sendMessage() {
     final text = _textController.text.trim();
     if (text.isEmpty || _selectedAgent == null) return;
+    _log.info('Sending message to $_selectedAgent (${text.length} chars)');
 
     // Record the user message locally
     setState(() {

ui/lib/features/metrics/metrics_page.dart

@@ -1,5 +1,6 @@
 import 'package:flutter/material.dart';
 import 'package:graphic/graphic.dart';
+import 'package:logging/logging.dart';
 import '../../theme/agent_studio_theme.dart';
 import '../../services/api_client.dart';
 
@@ -38,6 +39,7 @@ class MetricsPage extends StatefulWidget {
 }
 
 class _MetricsPageState extends State<MetricsPage> {
+  static final _log = Logger('MetricsPage');
   final _api = ApiClient();
   bool _loading = true;
 
@@ -60,6 +62,7 @@ class _MetricsPageState extends State<MetricsPage> {
   }
 
   Future<void> _loadMetrics() async {
+    _log.info('Loading metrics...');
     try {
       final results = await Future.wait([
         _api.getMetrics('latency').catchError((_) => <String, dynamic>{}),
@@ -104,7 +107,9 @@ class _MetricsPageState extends State<MetricsPage> {
 
         _loading = false;
       });
-    } catch (_) {
+      _log.fine('Metrics loaded: sessions=$_activeSessions latency=$_latencyP99 gates=$_gatesPassRate tokens=$_tokensPerHour');
+    } catch (e) {
+      _log.warning('Failed to load metrics: $e');
       setState(() => _loading = false);
     }
   }

ui/lib/features/onboarding/onboarding_dialog.dart

@@ -1,6 +1,7 @@
 import 'dart:convert';
 import 'package:flutter/material.dart';
 import 'package:http/http.dart' as http;
+import 'package:logging/logging.dart';
 import '../../services/api_client.dart';
 import '../../theme/agent_studio_theme.dart';
 
@@ -15,6 +16,7 @@ class OnboardingDialog extends StatefulWidget {
 }
 
 class _OnboardingDialogState extends State<OnboardingDialog> {
+  static final _log = Logger('OnboardingDialog');
   int _step = 0; // 0 = welcome, 1 = provider, 2 = agent, 3 = done
   String _selectedProvider = 'openrouter_free';
   final _apiKeyCtrl = TextEditingController();
@@ -61,6 +63,7 @@ class _OnboardingDialogState extends State<OnboardingDialog> {
   };
 
   Future<void> _saveAndFinish() async {
+    _log.info('Onboarding: saving config with provider=$_selectedProvider');
     setState(() => _saving = true);
     final preset = _presets[_selectedProvider]!;
 
@@ -103,14 +106,17 @@ class _OnboardingDialogState extends State<OnboardingDialog> {
           'graph_template': 'react',
         }),
       );
-    } catch (_) {
+    } catch (e) {
       // If backend is unavailable, still dismiss
+      _log.warning('Onboarding save failed (continuing anyway): $e');
     }
 
+    _log.info('Onboarding complete');
     widget.onComplete();
   }
 
   Future<void> _skipWithDefaults() async {
+    _log.info('Onboarding: skipping with defaults');
     setState(() => _saving = true);
     try {
       // Create default agent from defaults
@@ -124,7 +130,10 @@ class _OnboardingDialogState extends State<OnboardingDialog> {
           'graph_template': 'react',
         }),
       );
-    } catch (_) {}
+    } catch (e) {
+      _log.warning('Default agent creation failed: $e');
+    }
+    _log.info('Onboarding skipped with defaults');
     widget.onComplete();
   }
 
@@ -194,7 +203,10 @@ class _OnboardingDialogState extends State<OnboardingDialog> {
             ),
             const SizedBox(width: 12),
             FilledButton(
-              onPressed: () => setState(() => _step = 1),
+              onPressed: () {
+                _log.info('Onboarding step: welcome -> provider selection');
+                setState(() => _step = 1);
+              },
               style: FilledButton.styleFrom(backgroundColor: AgentStudioTheme.primary),
               child: const Text('Configurar', style: TextStyle(fontSize: 13)),
             ),
@@ -260,7 +272,10 @@ class _OnboardingDialogState extends State<OnboardingDialog> {
             ),
             const SizedBox(width: 8),
             FilledButton(
-              onPressed: () => setState(() => _step = 2),
+              onPressed: () {
+                _log.info('Onboarding step: provider selection -> agent creation (provider=$_selectedProvider)');
+                setState(() => _step = 2);
+              },
               style: FilledButton.styleFrom(backgroundColor: AgentStudioTheme.primary),
               child: const Text('Siguiente'),
             ),

ui/lib/features/sessions/sessions_page.dart

@@ -1,4 +1,5 @@
 import 'package:flutter/material.dart';
+import 'package:logging/logging.dart';
 import '../../theme/agent_studio_theme.dart';
 import '../../services/api_client.dart';
 
@@ -10,6 +11,7 @@ class SessionsPage extends StatefulWidget {
 }
 
 class _SessionsPageState extends State<SessionsPage> {
+  static final _log = Logger('SessionsPage');
   final _api = ApiClient();
   List<Map<String, dynamic>> _sessions = [];
   bool _loading = true;
@@ -28,13 +30,16 @@ class _SessionsPageState extends State<SessionsPage> {
   }
 
   Future<void> _loadSessions() async {
+    _log.info('Loading sessions...');
     try {
       final sessions = await _api.listSessions();
+      _log.fine('Loaded ${sessions.length} sessions');
       setState(() {
         _sessions = sessions;
         _loading = false;
       });
-    } catch (_) {
+    } catch (e) {
+      _log.warning('Failed to load sessions: $e');
       setState(() {
         _loading = false;
         _error = 'No se pudo conectar al API.';