feat: 🚀 Evolve to Stateful MCP Architecture with Context Injection Middleware

Major architectural overhaul to decouple Agent Logic (Service) from Tool Execution (Server) using the Model Context Protocol (MCP).

Key Highlights:
- **Micro-Architecture**: Migrated local toolkits to a standalone `FastMCP` server process (`mcp_server_lifeflow.py`).
- **Context Engineering**: Implemented an AOP-style interceptor using Python `ContextVars`. This automatically injects `session_id` and `api_key` into MCP tool calls, keeping Agent prompts clean and reducing token usage.
- **Multi-Tenant Safety**: Achieved strict session isolation. User-provided API keys dynamically override system environment variables via the injection layer.
- **Runtime Metaprogramming**: Solved Agno/Phidata internal naming conflicts (`_` prefix) by dynamically patching tool entrypoints at startup.
- **Exclusive Channels**: Configured dedicated MCP pipes for each Agent (`Scout`, `Navigator`, etc.) to prevent tool hallucination.

This commit satisfies all requirements for Hackathon Track 2: MCP in Action.

app.py

@@ -1,35 +1,190 @@
 """
-LifeFlow AI - Main Application (Fixed Output Mismatch)
-✅ 修復 Step 4 回傳值數量不匹配導致的 AttributeError
-✅ 確保 outputs 清單包含所有 7 個元件
+LifeFlow AI - Main Application (Fixed for Exclusive Tools Dict)
+✅ 修正錯誤: 確保傳遞給 Service的是 Dictionary 而不是單一 Object
+✅ 實現多通道隔離 (Scout 只能用 Scout 的工具)
 """
 
 import gradio as gr
-import inspect
+import asyncio
+import os
+import sys
+import traceback
+from contextlib import asynccontextmanager
 from datetime import datetime
+
+# Agno / MCP Imports
+from agno.tools.mcp import MCPTools
+
+# UI Imports
 from ui.theme import get_enhanced_css
 from ui.components.header import create_header
 from ui.components.progress_stepper import create_progress_stepper, update_stepper
 from ui.components.input_form import create_input_form, toggle_location_inputs
 from ui.components.modals import create_settings_modal, create_doc_modal
-from ui.renderers import (
-    create_agent_dashboard,
-    create_summary_card,
-)
+from ui.renderers import create_agent_dashboard, create_summary_card
+
+# Core Imports
 from core.session import UserSession
 from services.planner_service import PlannerService
 from services.validator import APIValidator
 from config import MODEL_OPTIONS
+from src.infra.client_context import client_session_ctx
+
+# ==================== 1. Tool Isolation Config ====================
+
+# 定義每個 Agent 專屬的工具名稱 (對應 mcp_server_lifeflow.py 裡的 @mcp.tool 名稱)
+AGENT_TOOL_MAP = {
+    "scout": "search_and_offload",
+    "optimizer": "optimize_from_ref",
+    "navigator": "calculate_traffic_and_timing",
+    "weatherman": "check_weather_for_timeline",
+    "presenter": "read_final_itinerary",
+}
+
+# 全域變數：存放 "Agent Name" -> "MCPToolkit Instance" 的對照表
+GLOBAL_TOOLKITS_DICT = {}
+
+# ==================== 2. MCP Lifecycle Manager ====================
+
+def inject_context_into_tools(toolkit):
+    """
+    手術刀函式：
+    1. [Context] 為每個工具安裝攔截器，自動注入 session_id。
+    2. [Rename] (新增) 移除 Agno 自動加上的底線前綴，讓 Agent 能找到工具。
+    """
+    # 嘗試取得工具列表
+    funcs = getattr(toolkit, "functions", {})
+
+    # 如果是 List，轉成 Dict 方便我們操作名稱
+    # (Agno 的 MCPToolkit 通常是用 Dict 存的: {name: function})
+    if isinstance(funcs, list):
+        print("⚠️ Warning: toolkit.functions is a list. Renaming might be tricky.")
+        tool_iterator = funcs
+    elif isinstance(funcs, dict):
+        tool_iterator = list(funcs.values())  # 轉成 List 以便安全迭代
+    else:
+        print(f"⚠️ Warning: Unknown functions type: {type(funcs)}")
+        return 0
+
+    count = 0
+    renamed_count = 0
+
+    for tool in tool_iterator:
+        # --- A. 執行 Context 注入 (原本的邏輯) ---
+        original_entrypoint = tool.entrypoint
+
+        async def context_aware_wrapper(*args, **kwargs):
+            current_sid = client_session_ctx.get()
+            if current_sid:
+                kwargs['session_id'] = current_sid
+
+            if asyncio.iscoroutinefunction(original_entrypoint):
+                return await original_entrypoint(*args, **kwargs)
+            else:
+                return original_entrypoint(*args, **kwargs)
+
+        tool.entrypoint = context_aware_wrapper
+        count += 1
+
+        # --- B. 執行更名手術 (新增邏輯) ---
+        # 如果名字是以 "_" 開頭 (例如 _search_and_offload)
+        if tool.name.startswith("_"):
+            old_name = tool.name
+            new_name = old_name[1:]  # 去掉第一個字元
+
+            # 1. 改工具物件本身的名字
+            tool.name = new_name
+
+            # 2. 如果 funcs 是字典，也要更新 Key，不然 Agent 查表會查不到
+            if isinstance(funcs, dict):
+                # 建立新 Key，移除舊 Key
+                funcs[new_name] = tool
+                if old_name in funcs:
+                    del funcs[old_name]
+
+            renamed_count += 1
+            # print(f"      🔧 Renamed '{old_name}' -> '{new_name}'")
+
+    print(f"      🛡️ Injection: {count} tools patched, {renamed_count} tools renamed.")
+    return count
+
+
+
+@asynccontextmanager
+async def lifespan_manager():
+    """
+    MCP 生命週期管理器 (多通道模式)：
+    迴圈建立 5 個獨立的 MCP Client，每個只包含該 Agent 需要的工具。
+    """
+    global GLOBAL_TOOLKITS_DICT
+    print("🚀 [System] Initializing Exclusive MCP Connections...")
+
+    server_script = "mcp_server_lifeflow.py"
+    env_vars = os.environ.copy()
+    env_vars["PYTHONUNBUFFERED"] = "1"
+
+    started_toolkits = []
+
+    try:
+        # 🔥 迴圈建立隔離的工具箱
+        for agent_name, tool_name in AGENT_TOOL_MAP.items():
+            print(f"   ⚙️ Connecting {agent_name} -> tool: {tool_name}...")
+
+            # 建立專屬連線
+            tool = MCPTools(
+                command=f"{sys.executable} {server_script}",
+                env=env_vars,
+                # 🔥 關鍵：只允許看見這個工具
+                include_tools=[tool_name]
+            )
+
+            # 啟動連線
+            await tool.connect()
+
+            inject_context_into_tools(tool)
+            GLOBAL_TOOLKITS_DICT[agent_name] = tool
+            # 存入字典
+            started_toolkits.append(tool)
+
+        print(f"✅ [System] All {len(started_toolkits)} MCP Channels Ready!")
+        yield
+
+    except Exception as e:
+        print(f"❌ [System] MCP Connection Failed: {e}")
+        traceback.print_exc()
+        yield
+
+    finally:
+        print("🔻 [System] Closing All MCP Connections...")
+        for name, tool in GLOBAL_TOOLKITS_DICT.items():
+            try:
+                await tool.close()
+            except Exception as e:
+                print(f"⚠️ Error closing {name}: {e}")
+        print("🏁 [System] Shutdown Complete.")
+
+# ==================== 3. Main Application Class ====================
 
 class LifeFlowAI:
     def __init__(self):
         self.service = PlannerService()
 
+    def inject_tools(self, toolkits_dict):
+        """
+        依賴注入：接收工具字典
+        """
+        # 這裡會檢查傳進來的是不是字典，避免你剛才遇到的錯誤
+        if isinstance(toolkits_dict, dict) and toolkits_dict:
+            self.service.set_global_tools(toolkits_dict)
+            print("💉 [App] Tools Dictionary injected into Service.")
+        else:
+            print(f"⚠️ [App] Warning: Invalid toolkits format. Expected dict, got {type(toolkits_dict)}")
+
+    # ... (Event Wrappers 保持不變，因為它們只呼叫 self.service) ...
+
     def cancel_wrapper(self, session_data):
         session = UserSession.from_dict(session_data)
-        if session.session_id:
-            self.service.cancel_session(session.session_id)
-        # 不需要回傳任何東西，這只是一個副作用 (Side Effect) 函數
+        if session.session_id: self.service.cancel_session(session.session_id)
 
     def _get_dashboard_html(self, active_agent: str = None, status: str = "idle", message: str = "Waiting") -> str:
         agents = ['team', 'scout', 'optimizer', 'navigator', 'weatherman', 'presenter']
@@ -42,19 +197,13 @@ class LifeFlowAI:
 
     def _check_api_status(self, session_data):
         session = UserSession.from_dict(session_data)
-        has_model_api = bool(session.custom_settings.get("model_api"))
-        has_google = bool(session.custom_settings.get("google_maps_api_key"))
-        msg = "✅ System Ready" if (has_model_api and has_google) else "⚠️ Missing API Keys"
-        return msg
+        has_key = bool(session.custom_settings.get("model_api_key")) or bool(os.environ.get("OPENAI_API_KEY")) or bool(os.environ.get("GOOGLE_API_KEY"))
+        return "✅ System Ready (Exclusive Mode)" if has_key else "⚠️ Check API Keys"
 
     def _get_gradio_chat_history(self, session):
-        history = []
-        for msg in session.chat_history:
-            history.append({"role": msg["role"], "content": msg["message"]})
-        return history
-
-    # ================= Event Wrappers =================
+        return [{"role": msg["role"], "content": msg["message"]} for msg in session.chat_history]
 
+    # --- Wrappers ---
     def analyze_wrapper(self, user_input, auto_loc, lat, lon, session_data):
         session = UserSession.from_dict(session_data)
         iterator = self.service.run_step1_analysis(user_input, auto_loc, lat, lon, session)
@@ -63,61 +212,19 @@ class LifeFlowAI:
             current_session = event.get("session", session)
             if evt_type == "error":
                 gr.Warning(event.get('message'))
-                yield (
-                    gr.update(visible=True),  # Step 1 Container: 保持顯示
-                    gr.update(visible=False),  # Step 2 Container: 保持隱藏
-                    gr.update(visible=False),  # Step 3 Container
-                    gr.HTML(f"<div style='color:red'>{event.get('message')}</div>"),  # s1_stream
-                    gr.update(),  # task_list
-                    gr.update(),  # task_summary
-                    gr.update(),  # chatbot
-                    current_session.to_dict()  # state
-                )
+                yield (gr.update(visible=True), gr.update(visible=False), gr.update(visible=False), gr.HTML(f"<div style='color:red'>{event.get('message')}</div>"), gr.update(), gr.update(), gr.update(), current_session.to_dict())
                 return
-
             if evt_type == "stream":
-                yield (
-                    gr.update(visible=True),
-                    gr.update(visible=False),
-                    gr.update(visible=False),
-                    event.get("stream_text", ""),
-                    gr.update(),
-                    gr.update(),
-                    gr.update(),
-                    current_session.to_dict()
-                )
-
+                yield (gr.update(visible=True), gr.update(visible=False), gr.update(visible=False), event.get("stream_text", ""), gr.update(), gr.update(), gr.update(), current_session.to_dict())
             elif evt_type == "complete":
                 tasks_html = self.service.generate_task_list_html(current_session)
-
-                print(event)
                 date_str = event.get("start_time", "N/A")
-                high_priority = event.get("high_priority", "N/A")
-                total_time = event.get("total_time", "N/A")
-                loc_str = event.get("start_location", "N/A")
-
-                summary_html = create_summary_card(len(current_session.task_list),
-                                                   high_priority,
-                                                   total_time,
-                                                   location=loc_str, date=date_str)
-
+                summary_html = create_summary_card(len(current_session.task_list), event.get("high_priority", 0), event.get("total_time", 0), location=event.get("start_location", "N/A"), date=date_str)
                 chat_history = self._get_gradio_chat_history(current_session)
                 if not chat_history:
-                    chat_history = [
-                        {"role": "assistant", "content": event.get('stream_text', "")},
-                        {"role": "assistant", "content": "Hi! I'm LifeFlow. Tell me if you want to change priorities, add stops, or adjust times."}]
+                    chat_history = [{"role": "assistant", "content": event.get('stream_text', "")}]
                     current_session.chat_history.append({"role": "assistant", "message": "Hi! I'm LifeFlow...", "time": ""})
-
-                yield (
-                    gr.update(visible=False),  # Hide S1
-                    gr.update(visible=True),  # Show S2
-                    gr.update(visible=False),  # Hide S3
-                    "",  # Clear Stream
-                    gr.HTML(tasks_html),
-                    gr.HTML(summary_html),
-                    chat_history,
-                    current_session.to_dict()
-                )
+                yield (gr.update(visible=False), gr.update(visible=True), gr.update(visible=False), "", gr.HTML(tasks_html), gr.HTML(summary_html), chat_history, current_session.to_dict())
 
     def chat_wrapper(self, msg, session_data):
         session = UserSession.from_dict(session_data)
@@ -129,175 +236,81 @@ class LifeFlowAI:
             gradio_history = self._get_gradio_chat_history(sess)
             yield (gradio_history, tasks_html, summary_html, sess.to_dict())
 
-    def step3_wrapper(self, session_data):
+    # 🔥 記得改成 async def
+    async def step3_wrapper(self, session_data):
         session = UserSession.from_dict(session_data)
-
-        # Init variables
-        log_content = ""
-        report_content = ""
-
+        log_content, report_content = "", ""
         tasks_html = self.service.generate_task_list_html(session)
         init_dashboard = self._get_dashboard_html('team', 'working', 'Initializing...')
-
-        # HTML Content (No Indentation)
-        loading_html = inspect.cleandoc("""
-        <div style="text-align: center; padding: 60px 20px; color: #64748b;">
-            <div style="font-size: 48px; margin-bottom: 20px; animation: pulse 1.5s infinite;">🧠</div>
-            <div style="font-size: 1.2rem; font-weight: 600; color: #334155;">AI Team is analyzing your request...</div>
-            <div style="font-size: 0.9rem; margin-top: 8px;">Checking routes, weather, and optimizing schedule.</div>
-        </div>
-        <style>@keyframes pulse { 0% { transform: scale(1); opacity: 1; } 50% { transform: scale(1.1); opacity: 0.7; } 100% { transform: scale(1); opacity: 1; } }</style>
-        """)
-
-        init_log = '<div style="padding: 10px; color: #94a3b8; font-style: italic;">Waiting for agents...</div>'
+        loading_html = '<div style="text-align: center; padding: 60px;">🧠 Analyzing...</div>'
+        init_log = '<div style="padding: 10px; color: #94a3b8;">Waiting for agents...</div>'
 
         yield (init_dashboard, init_log, loading_html, tasks_html, session.to_dict())
 
         try:
-            iterator = self.service.run_step3_team(session)
-
-            for event in iterator:
+            # 🔥 使用 async for
+            async for event in self.service.run_step3_team(session):
                 sess = event.get("session", session)
                 evt_type = event.get("type")
 
-                if evt_type == "error":
-                    raise Exception(event.get("message"))
-
-                if evt_type == "report_stream":
-                    report_content = event.get("content", "")
+                if evt_type == "error": raise Exception(event.get("message"))
+                if evt_type == "report_stream": report_content = event.get("content", "")
 
                 if evt_type == "reasoning_update":
                     agent, status, msg = event.get("agent_status")
                     time_str = datetime.now().strftime('%H:%M:%S')
-                    log_entry = f"""
-                    <div style="margin-bottom: 8px; border-left: 3px solid #6366f1; padding-left: 10px;">
-                        <div style="font-size: 0.75rem; color: #94a3b8;">{time_str} • {agent.upper()}</div>
-                        <div style="color: #334155; font-size: 0.9rem;">{msg}</div>
-                    </div>
-                    """
+                    log_entry = f'<div style="margin-bottom: 8px; border-left: 3px solid #6366f1; padding-left: 10px;"><div style="font-size: 0.75rem; color: #94a3b8;">{time_str} • {agent.upper()}</div><div style="color: #334155; font-size: 0.9rem;">{msg}</div></div>'
                     log_content = log_entry + log_content
                     dashboard_html = self._get_dashboard_html(agent, status, msg)
                     log_html = f'<div style="height: 500px; overflow-y: auto; padding: 10px; background: #fff;">{log_content}</div>'
                     current_report = report_content + "\n\n" if report_content else loading_html
-
-                    yield (dashboard_html, log_html, current_report, tasks_html, sess.to_dict())
-
-                if evt_type in ["report_stream", "reasoning_update"]:
                     yield (dashboard_html, log_html, current_report, tasks_html, sess.to_dict())
 
                 if evt_type == "complete":
                     final_report = event.get("report_html", report_content)
-                    final_log = f"""
-                    <div style="margin-bottom: 8px; border-left: 3px solid #10b981; padding-left: 10px; background: #ecfdf5; padding: 10px;">
-                        <div style="font-weight: bold; color: #059669;">✅ Planning Completed</div>
-                    </div>
-                    {log_content}
-                    """
+                    final_log = f'<div style="margin-bottom: 8px; border-left: 3px solid #10b981; padding-left: 10px; background: #ecfdf5; padding: 10px;"><div style="font-weight: bold; color: #059669;">✅ Planning Completed</div></div>{log_content}'
                     final_log_html = f'<div style="height: 500px; overflow-y: auto; padding: 10px; background: #fff;">{final_log}</div>'
-
-                    yield (
-                        self._get_dashboard_html('team', 'complete', 'Planning Finished'),
-                        final_log_html,
-                        final_report,
-                        tasks_html,
-                        sess.to_dict()
-                    )
+                    yield (self._get_dashboard_html('team', 'complete', 'Planning Finished'), final_log_html, final_report, tasks_html, sess.to_dict())
 
         except Exception as e:
-            error_msg = str(e)
-            gr.Warning(f"⚠️ Planning Interrupted: {error_msg}")
-
-            # 這裡我們做一個特殊的 UI 操作：
-            # 雖然這個 Wrapper 的 outputs 綁定的是 Step 3 的內部元件
-            # 但我們可以透過修改 Step 3 的 "Log" 或 "Report" 區域來顯示「重試按鈕」
-            # 或者 (更進階做法) 在 app.py 綁定 outputs 時，就把 Step 2 container 也包進來。
-
-            # 💡 最簡單不改動 outputs 結構的做法：
-            # 在 Log 區域顯示紅色錯誤，並提示用戶手動點擊 "Back"
-
-            error_html = f"""
-                    <div style="padding: 20px; background: #fee2e2; border: 1px solid #ef4444; border-radius: 8px; color: #b91c1c;">
-                        <strong>❌ Error Occurred:</strong><br>{error_msg}<br><br>
-                        Please check your API keys or modify tasks, then try again.
-                    </div>
-                    """
-
-            # 回傳錯誤訊息到 UI，讓使用者知道發生了什麼
-            yield (
-                self._get_dashboard_html('team', 'error', 'Failed'),  # Dashboard 變紅
-                error_html,  # Log 顯示錯誤
-                "",
-                tasks_html,
-                session.to_dict()
-            )
+            error_html = f"<div style='color:red'>Error: {str(e)}</div>"
+            yield (self._get_dashboard_html('team', 'error', 'Failed'), error_html, "", tasks_html, session.to_dict())
 
     def step4_wrapper(self, session_data):
         session = UserSession.from_dict(session_data)
         result = self.service.run_step4_finalize(session)
-
-        # 🔥 Wrapper 回傳 7 個值
         if result['type'] == 'success':
-            return (
-                gr.update(visible=False), # 1. Step 3 Hide
-                gr.update(visible=True),  # 2. Step 4 Show
-                result['summary_tab_html'], # 3. Summary Tab HTML
-                result['report_md'],        # 4. Report Tab Markdown
-                result['task_list_html'],   # 5. Task List HTML
-                result['map_fig'],          # 6. Map Plot
-                session.to_dict()           # 7. Session State
-            )
+            return (gr.update(visible=False), gr.update(visible=True), result['summary_tab_html'], result['report_md'], result['task_list_html'], result['map_fig'], session.to_dict())
         else:
-            return (
-                gr.update(visible=True), gr.update(visible=False),
-                "", "", "", None,
-                session.to_dict()
-            )
+            return (gr.update(visible=True), gr.update(visible=False), "", "", "", None, session.to_dict())
 
     def save_settings(self, g, w, prov, m_key, m_sel, fast, g_key_in, f_sel, s_data):
         sess = UserSession.from_dict(s_data)
-
-                # 存入 Session
-        sess.custom_settings.update({
-                    'google_maps_api_key': g,
-                    'openweather_api_key': w,
-                    'llm_provider': prov,
-                    'model_api_key': m_key,     # 主模型 Key
-                    'model': m_sel,             # 主模型 ID
-                    'enable_fast_mode': fast,   # 🔥 Fast Mode 開關
-                    'groq_fast_model': f_sel,
-                    'groq_api_key': g_key_in    # 🔥 獨立 Groq Key
-        })
-        print("Settings saved:", sess.custom_settings)
-
+        sess.custom_settings.update({'google_maps_api_key': g, 'openweather_api_key': w, 'llm_provider': prov, 'model_api_key': m_key, 'model': m_sel, 'enable_fast_mode': fast, 'groq_fast_model': f_sel, 'groq_api_key': g_key_in})
         return gr.update(visible=False), sess.to_dict(), "✅ Configuration Saved"
-    # ================= Main UI Builder =================
+
+    # ==================== 4. UI Builder ====================
 
     def build_interface(self):
         container_css = """
-                .gradio-container {
-                    max-width: 100% !important; 
-                    padding: 0;
-                    height: 100vh !important;      /* 1. 關鍵：鎖定高度為視窗大小 */
-                    overflow-y: auto !important;   /* 2. 關鍵：內容過長時，在內部產生捲軸 */
-                }
+                .gradio-container { max-width: 100% !important; padding: 0; height: 100vh !important; overflow-y: auto !important; }
                 """
-
-        with gr.Blocks(title="LifeFlow AI", css=container_css) as demo:
+        with gr.Blocks(title="LifeFlow AI (MCP)", css=container_css) as demo:
             gr.HTML(get_enhanced_css())
-
             session_state = gr.State(UserSession().to_dict())
 
             with gr.Column(elem_classes="step-container"):
-                home_btn, settings_btn, doc_btn = create_header() #theme_btn
-
+                home_btn, settings_btn, doc_btn = create_header()
                 stepper = create_progress_stepper(1)
-                status_bar = gr.Markdown("Ready", visible=False)
+                status_bar = gr.Markdown("Initializing MCP...", visible=False)
 
-            # STEP 1
+            # --- Steps UI (Copy from previous) ---
+            # 為節省篇幅，這裡省略中間 UI 宣告代碼，它們與之前完全相同
+            # 請確保這裡是完整的 create_input_form, step2, step3, step4 定義
+            # ...
             with gr.Group(visible=True, elem_classes="step-container centered-input-container") as step1_container:
                 (input_area, s1_stream_output, user_input, auto_loc, loc_group, lat_in, lon_in, analyze_btn) = create_input_form("")
 
-            # STEP 2
             with gr.Group(visible=False, elem_classes="step-container") as step2_container:
                 gr.Markdown("### ✅ Review & Refine Tasks")
                 with gr.Row(elem_classes="step2-split-view"):
@@ -317,276 +330,132 @@ class LifeFlowAI:
                     back_btn = gr.Button("← Back", variant="secondary", scale=1)
                     plan_btn = gr.Button("🚀 Start Planning", variant="primary", scale=2)
 
-            # STEP 3
             with gr.Group(visible=False, elem_classes="step-container") as step3_container:
                 gr.Markdown("### 🤖 AI Team Operations")
-
-                # 1. Agent Dashboard (保持不變)
                 with gr.Group(elem_classes="agent-dashboard-container"):
                     agent_dashboard = gr.HTML(value=self._get_dashboard_html())
-
-                # 2. 主要內容區 (左右分欄)
                 with gr.Row():
-                    # 🔥 左側：主要報告顯示區 (佔 3/4 寬度)
                     with gr.Column(scale=3):
                         with gr.Tabs():
                             with gr.Tab("📝 Full Report"):
-                                # 🔥 修正 2: 加入白底容器 (live-report-wrapper)
                                 with gr.Group(elem_classes="live-report-wrapper"):
                                     live_report_md = gr.Markdown()
-
                             with gr.Tab("📋 Task List"):
                                 with gr.Group(elem_classes="panel-container"):
                                     with gr.Group(elem_classes="scrollable-content"):
                                         task_list_s3 = gr.HTML()
-
-                    # 🔥 右側：控制區與日誌 (佔 1/4 寬度)
                     with gr.Column(scale=1):
-                        # 🔥 修正 1: 將停止按鈕移到這裡 (右側欄位頂部)
-                        # variant="stop" 會呈現紅色，更符合 "緊急停止" 的語意
                         cancel_plan_btn = gr.Button("🛑 Stop & Back to Edit", variant="stop")
-
                         gr.Markdown("### ⚡ Activity Log")
                         with gr.Group(elem_classes="panel-container"):
                             planning_log = gr.HTML(value="Waiting...")
 
-            # STEP 4
             with gr.Group(visible=False, elem_classes="step-container") as step4_container:
                 with gr.Row():
-                    # Left: Tabs (Summary / Report / Tasks)
                     with gr.Column(scale=1, elem_classes="split-left-panel"):
                         with gr.Tabs():
                             with gr.Tab("📊 Summary"):
                                 summary_tab_output = gr.HTML()
-
                             with gr.Tab("📝 Full Report"):
                                 with gr.Group(elem_classes="live-report-wrapper"):
                                     report_tab_output = gr.Markdown()
-
                             with gr.Tab("📋 Task List"):
                                 task_list_tab_output = gr.HTML()
-
-                    # Right: Hero Map
                     with gr.Column(scale=2, elem_classes="split-right-panel"):
                         map_view = gr.HTML(label="Route Map")
 
-            # Modals & Events
-            (settings_modal,
-             g_key, g_stat,
-             w_key, w_stat,
-             llm_provider, main_key, main_stat, model_sel,
-             fast_mode_chk, groq_model_sel, groq_key, groq_stat,
-             close_set, save_set, set_stat) = create_settings_modal()
-
-            # 2. 綁定 Google Maps 測試
-            g_key.blur(
-                fn=lambda k: "⏳ Checking..." if k else "",  # 先顯示 checking
-                inputs=[g_key], outputs=[g_stat]
-            ).then(
-                fn=APIValidator.test_google_maps,
-                inputs=[g_key],
-                outputs=[g_stat]
-            )
-
-            # 3. OpenWeather 自動驗證
-            w_key.blur(
-                fn=lambda k: "⏳ Checking..." if k else "",
-                inputs=[w_key], outputs=[w_stat]
-            ).then(
-                fn=APIValidator.test_openweather,
-                inputs=[w_key],
-                outputs=[w_stat]
-            )
+            # --- Modals & Events ---
+            (settings_modal, g_key, g_stat, w_key, w_stat, llm_provider, main_key, main_stat, model_sel,
+             fast_mode_chk, groq_model_sel, groq_key, groq_stat, close_set, save_set, set_stat) = create_settings_modal()
 
-            # 4. 綁定 Main Brain 測試
-            main_key.blur(
-                fn=lambda k: "⏳ Checking..." if k else "",
-                inputs=[main_key], outputs=[main_stat]
-            ).then(
-                fn=APIValidator.test_llm,
-                inputs=[llm_provider, main_key, model_sel],
-                outputs=[main_stat]
-            )
-
-            # 5. Groq 自動驗證
-            groq_key.blur(
-                fn=lambda k: "⏳ Checking..." if k else "",
-                inputs=[groq_key], outputs=[groq_stat]
-            ).then(
-                fn=lambda k, m: APIValidator.test_llm("Groq", k, m),
-                inputs=[groq_key, groq_model_sel],
-                outputs=[groq_stat]
-            )
+            # Validators
+            g_key.blur(fn=lambda k: "⏳ Checking..." if k else "", inputs=[g_key], outputs=[g_stat]).then(fn=APIValidator.test_google_maps, inputs=[g_key], outputs=[g_stat])
+            w_key.blur(fn=lambda k: "⏳ Checking..." if k else "", inputs=[w_key], outputs=[w_stat]).then(fn=APIValidator.test_openweather, inputs=[w_key], outputs=[w_stat])
+            main_key.blur(fn=lambda k: "⏳ Checking..." if k else "", inputs=[main_key], outputs=[main_stat]).then(fn=APIValidator.test_llm, inputs=[llm_provider, main_key, model_sel], outputs=[main_stat])
 
             def resolve_groq_visibility(fast_mode, provider):
-                """
-                綜合判斷 Groq 相關欄位是否該顯示
-                回傳: (Model選單狀態, Key輸入框狀態, 狀態訊息狀態)
-                """
-                # 1. 如果沒開 Fast Mode -> 全部隱藏 + 清空狀態
-                if not fast_mode:
-                    return (
-                        gr.update(visible=False),
-                        gr.update(visible=False),
-                        gr.update(visible=False)  # 🔥 清空狀態
-                    )
-
-                # 2. 如果開了 Fast Mode
+                if not fast_mode: return (gr.update(visible=False), gr.update(visible=False), gr.update(visible=False))
                 model_vis = gr.update(visible=True)
+                if provider == "Groq": return (model_vis, gr.update(visible=False), gr.update(visible=False))
+                else: return (model_vis, gr.update(visible=True), gr.update(visible=True))
+            fast_mode_chk.change(fn=resolve_groq_visibility, inputs=[fast_mode_chk, llm_provider], outputs=[groq_model_sel, groq_key, groq_stat])
 
-                # 3. 判斷 Key 是否需要顯示
-                is_main_groq = (provider == "Groq")
-
-                if is_main_groq:
-                    # 如果主 Provider 是 Groq，隱藏 Key 並清空狀態 (避免誤導)
-                    return (
-                        model_vis,
-                        gr.update(visible=False),
-                        gr.update(visible=False)  # 🔥 清空狀態
-                    )
-                else:
-                    # 否則顯示 Key，狀態保持原樣 (不更動)
-                    return (
-                        model_vis,
-                        gr.update(visible=True),
-                        gr.update(visible=True)  # 保持原樣
-                    )
-
-            fast_mode_chk.change(
-                fn=resolve_groq_visibility,
-                inputs=[fast_mode_chk, llm_provider],
-                outputs=[groq_model_sel, groq_key, groq_stat]  # 🔥 新增 groq_stat
-            )
-
-            # --- 事件 B: 當 "Main Provider" 改變時 ---
             def on_provider_change(provider, fast_mode):
-                # 1. 更新 Model 下拉選單 (原有邏輯)
                 new_choices = MODEL_OPTIONS.get(provider, [])
                 default_val = new_choices[0][1] if new_choices else ""
                 model_update = gr.Dropdown(choices=new_choices, value=default_val)
-
-                # 2. 清空 Main API Key (原有邏輯)
-                key_clear = gr.Textbox(value="")
-                stat_clear = gr.Markdown(value="")
-
-                # 3. 重算 Groq 欄位可見性 (包含狀態清空)
                 g_model_vis, g_key_vis, g_stat_vis = resolve_groq_visibility(fast_mode, provider)
-
-                # 回傳順序要對應下面的 outputs
-                return (
-                    model_update,  # model_sel
-                    key_clear,  # main_key
-                    stat_clear,  # main_stat
-                    g_model_vis,  # groq_model_sel
-                    g_key_vis,  # groq_key
-                    g_stat_vis  # groq_stat (新)
-                )
-
-            llm_provider.change(
-                fn=on_provider_change,
-                inputs=[llm_provider, fast_mode_chk],
-                # 🔥 outputs 增加到 6 個，確保所有狀態都被重置
-                outputs=[model_sel, main_key, main_stat, groq_model_sel, groq_key, groq_stat]
-            )
+                return (model_update, gr.Textbox(value=""), gr.Markdown(value=""), g_model_vis, g_key_vis, g_stat_vis)
+            llm_provider.change(fn=on_provider_change, inputs=[llm_provider, fast_mode_chk], outputs=[model_sel, main_key, main_stat, groq_model_sel, groq_key, groq_stat])
 
             doc_modal, close_doc_btn = create_doc_modal()
-
             settings_btn.click(fn=lambda: gr.update(visible=True), outputs=[settings_modal])
             close_set.click(fn=lambda: gr.update(visible=False), outputs=[settings_modal])
             doc_btn.click(fn=lambda: gr.update(visible=True), outputs=[doc_modal])
             close_doc_btn.click(fn=lambda: gr.update(visible=False), outputs=[doc_modal])
-            #theme_btn.click(fn=None, js="() => { document.querySelector('.gradio-container').classList.toggle('theme-dark'); }")
-
-            analyze_btn.click(
-                fn=self.analyze_wrapper,
-                inputs=[user_input, auto_loc, lat_in, lon_in, session_state,],
-                outputs=[step1_container, step2_container, step3_container, s1_stream_output, task_list_box, task_summary_box, chatbot, session_state]
-            ).then(fn=lambda: update_stepper(2), outputs=[stepper])
 
+            # Actions
+            analyze_btn.click(fn=self.analyze_wrapper, inputs=[user_input, auto_loc, lat_in, lon_in, session_state], outputs=[step1_container, step2_container, step3_container, s1_stream_output, task_list_box, task_summary_box, chatbot, session_state]).then(fn=lambda: update_stepper(2), outputs=[stepper])
             chat_send.click(fn=self.chat_wrapper, inputs=[chat_input, session_state], outputs=[chatbot, task_list_box, task_summary_box, session_state]).then(fn=lambda: "", outputs=[chat_input])
             chat_input.submit(fn=self.chat_wrapper, inputs=[chat_input, session_state], outputs=[chatbot, task_list_box, task_summary_box, session_state]).then(fn=lambda: "", outputs=[chat_input])
 
-            step3_start = plan_btn.click(
-                fn=lambda: (gr.update(visible=False), gr.update(visible=True), update_stepper(3)),
-                outputs=[step2_container, step3_container, stepper]
-            ).then(
-                fn=self.step3_wrapper,
-                inputs=[session_state],
-                outputs=[agent_dashboard, planning_log, live_report_md, task_list_s3, session_state],
-                show_progress="hidden"
-            )
-
-            cancel_plan_btn.click(
-                fn=self.cancel_wrapper,  # 1. 先執行取消
-                inputs=[session_state],
-                outputs=None
-            ).then(
-                fn=lambda: (gr.update(visible=True), gr.update(visible=False), update_stepper(2)),  # 2. 再切換 UI
-                inputs=None,
-                outputs=[step2_container, step3_container, stepper]
-            )
+            # 🔥 Step 3 Start
+            step3_start = plan_btn.click(fn=lambda: (gr.update(visible=False), gr.update(visible=True), update_stepper(3)), outputs=[step2_container, step3_container, stepper]).then(fn=self.step3_wrapper, inputs=[session_state], outputs=[agent_dashboard, planning_log, live_report_md, task_list_s3, session_state], show_progress="hidden")
 
-            step3_start.then(
-                fn=self.step4_wrapper,
-                inputs=[session_state],
-                # 🔥🔥🔥 關鍵修正：這裡列出了 7 個 Outputs，必須對應 Wrapper 回傳的 7 個值
-                outputs=[
-                    step3_container,      # 1. Hide Step 3
-                    step4_container,      # 2. Show Step 4
-                    summary_tab_output,   # 3. Summary Tab
-                    report_tab_output,    # 4. Report Tab
-                    task_list_tab_output, # 5. Task List Tab
-                    map_view,             # 6. Map
-                    session_state         # 7. State
-                ]
-            ).then(fn=lambda: update_stepper(4), outputs=[stepper])
+            cancel_plan_btn.click(fn=self.cancel_wrapper, inputs=[session_state], outputs=None).then(fn=lambda: (gr.update(visible=True), gr.update(visible=False), update_stepper(2)), inputs=None, outputs=[step2_container, step3_container, stepper])
+            step3_start.then(fn=self.step4_wrapper, inputs=[session_state], outputs=[step3_container, step4_container, summary_tab_output, report_tab_output, task_list_tab_output, map_view, session_state]).then(fn=lambda: update_stepper(4), outputs=[stepper])
 
             def reset_all(session_data):
-                old_session = UserSession.from_dict(session_data)
-                new_session = UserSession()
-                new_session.custom_settings = old_session.custom_settings
-                return (gr.update(visible=True), gr.update(visible=False), gr.update(visible=False), gr.update(visible=False), update_stepper(1), new_session.to_dict(), "")
-
-            home_btn.click(
-                fn=self.cancel_wrapper,  # 1. 先執行取消 (防止後台繼續跑)
-                inputs=[session_state],
-                outputs=None
-            ).then(
-                fn=reset_all,  # 2. 再重置 UI
-                inputs=[session_state],
-                outputs=[step1_container, step2_container, step3_container, step4_container, stepper, session_state,
-                         user_input]
-            )
-
-            back_btn.click(
-                fn=self.cancel_wrapper,
-                inputs=[session_state],
-                outputs=None
-            ).then(
-                fn=reset_all,
-                inputs=[session_state],
-                outputs=[step1_container, step2_container, step3_container, step4_container, stepper, session_state,
-                         user_input]
-            )
-
-            save_set.click(
-                fn=self.save_settings,
-                # 輸入參數對應上面的 create_settings_modal 回傳順序
-                inputs=[g_key, w_key, llm_provider, main_key, model_sel, fast_mode_chk, groq_key, groq_model_sel, session_state],
-                outputs=[settings_modal, session_state, status_bar]
-            )
-
-
-
+                old_s = UserSession.from_dict(session_data)
+                new_s = UserSession()
+                new_s.custom_settings = old_s.custom_settings
+                return (gr.update(visible=True), gr.update(visible=False), gr.update(visible=False), gr.update(visible=False), update_stepper(1), new_s.to_dict(), "")
+
+            home_btn.click(fn=self.cancel_wrapper, inputs=[session_state], outputs=None).then(fn=reset_all, inputs=[session_state], outputs=[step1_container, step2_container, step3_container, step4_container, stepper, session_state, user_input])
+            back_btn.click(fn=self.cancel_wrapper, inputs=[session_state], outputs=None).then(fn=reset_all, inputs=[session_state], outputs=[step1_container, step2_container, step3_container, step4_container, stepper, session_state, user_input])
+            save_set.click(fn=self.save_settings, inputs=[g_key, w_key, llm_provider, main_key, model_sel, fast_mode_chk, groq_key, groq_model_sel, session_state], outputs=[settings_modal, session_state, status_bar])
             auto_loc.change(fn=toggle_location_inputs, inputs=auto_loc, outputs=loc_group)
             demo.load(fn=self._check_api_status, inputs=[session_state], outputs=[status_bar])
 
         return demo
 
+# ==================== 5. Main ====================
+
 def main():
-    app = LifeFlowAI()
-    demo = app.build_interface()
-    demo.launch(server_name="0.0.0.0", server_port=7860, share=True, show_error=True)
-    #7860
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+
+    async def run_app_lifecycle():
+        async with lifespan_manager():
+            app = LifeFlowAI()
+            # 🔥 注入工具字典 (Dictionary)
+            app.inject_tools(GLOBAL_TOOLKITS_DICT)
+
+            demo = app.build_interface()
+            demo.launch(
+                server_name="0.0.0.0",
+                server_port=8100,
+                share=True,
+                show_error=True,
+                prevent_thread_lock=True
+            )
+            print("✨ App is running. Press Ctrl+C to stop.")
+            try:
+                while True: await asyncio.sleep(1)
+            except asyncio.CancelledError:
+                pass
+
+    try:
+        loop.run_until_complete(run_app_lifecycle())
+    except KeyboardInterrupt:
+        pass
+    except Exception as e:
+        print("\n❌ CRITICAL ERROR STARTUP FAILED ❌")
+        traceback.print_exc()
+    finally:
+        print("🛑 Shutting down process...")
+        import os
+        os._exit(0)
+
 if __name__ == "__main__":
     main()

config.py

@@ -8,6 +8,7 @@ from pathlib import Path
 
 # ===== 系統預設值 =====
 BASE_DIR = Path(__file__).parent
+MCP_SERVER_PATH = "mcp_server_lifeflow.py"
 
 LOG_LEVEL = "DEBUG"
 

requirements.txt

@@ -29,6 +29,7 @@ matplotlib==3.9.2
 folium
 
 # Utilities
+toolbox-core
 timezonefinder
 pytz==2024.2
 typing-extensions==4.12.2

services/planner_service.py

@@ -1,35 +1,32 @@
 """
-LifeFlow AI - Planner Service (Fixed: Session Persistence)
+LifeFlow AI - Planner Service (Refactored for MCP Architecture)
 核心業務邏輯層：負責協調 Agent 運作、狀態更新與資料處理。
+✅ 移除本地 Toolkits
+✅ 整合全域 MCP Client
+✅ 保持業務邏輯不變
 """
 import json
 import time
 import uuid
 from datetime import datetime
-from typing import Generator, Dict, Any, Tuple, Optional
-from contextlib import contextmanager
+from typing import Generator, Dict, Any, Tuple, Optional, AsyncGenerator
 
-# 導入 Core & UI 模組
+# Core Imports
 from core.session import UserSession
 from ui.renderers import (
     create_task_card,
     create_summary_card,
     create_timeline_html_enhanced,
-    create_result_visualization,
 )
 from core.visualizers import create_animated_map
-
-# 導入 Config
 from config import AGENTS_INFO
 
-# 導入 Model API
-from google.genai.types import HarmCategory, HarmBlockThreshold
+# Models
 from agno.models.google import Gemini
 from agno.models.openai import OpenAIChat
 from agno.models.groq import Groq
 
-# 導入 Agent 系統
-
+# Agno Framework
 from agno.agent import RunEvent
 from agno.run.team import TeamRunEvent
 from src.agent.base import UserState, Location, get_context
@@ -37,380 +34,244 @@ from src.agent.planner import create_planner_agent
 from src.agent.core_team import create_core_team
 from src.infra.context import set_session_id
 from src.infra.poi_repository import poi_repo
-from src.tools import (
-    ScoutToolkit, OptimizationToolkit,
-    NavigationToolkit, WeatherToolkit, ReaderToolkit
-)
 from src.infra.logger import get_logger
+from src.infra.client_context import client_session_ctx
 
+# 🔥🔥🔥 NEW IMPORTS: 只使用 MCPTools
+from agno.tools.mcp import MCPTools
 
 gemini_safety_settings = [
-            {"category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_NONE"},
-            {"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE"},
-            {"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "threshold": "BLOCK_NONE"},
-            {"category": "HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "BLOCK_NONE"},
-        ]
+    {"category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_NONE"},
+    {"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE"},
+    {"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "threshold": "BLOCK_NONE"},
+    {"category": "HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "BLOCK_NONE"},
+]
 
 logger = get_logger(__name__)
 max_retries = 5
 
 
-@contextmanager
-def patch_repo_context(session_id: str):
+class PlannerService:
     """
-    暴力解決方案：
-    在執行期間，暫時將 poi_repo 的 save/add 方法「綁架」，
-    強迫它們在執行前，先設定當前的 Thread Session。
+    PlannerService (MCP Version)
     """
+    # Active Sessions 快取 (僅存 Session 物件，不含全域資源)
+    _active_sessions: Dict[str, UserSession] = {}
+    _cancelled_sessions: set = set()
 
-    # 1. 備份原始方法
-    original_save = getattr(poi_repo, 'save', None)
-    original_add = getattr(poi_repo, 'add', None)
-
-    # 2. 定義「綁架」後的方法
-    def patched_save(*args, **kwargs):
-        set_session_id(session_id)
-        # 呼叫原始方法
-        if original_save:
-            return original_save(*args, **kwargs)
-        elif original_add:
-            return original_add(*args, **kwargs)
-
-    # 3. 執行替換
-    if original_save:
-        setattr(poi_repo, 'save', patched_save)
-    if original_add:
-        setattr(poi_repo, 'add', patched_save)
-
-    try:
-        yield
-    finally:
-        # 4. 恢復原始方法
-        if original_save:
-            setattr(poi_repo, 'save', original_save)
-        if original_add:
-            setattr(poi_repo, 'add', original_add)
+    # 🔥 全域工具參照 (由 App 注入)
+    _global_toolkits: Dict[str, MCPTools] = {}
 
+    def set_global_tools(self, toolkits_dict: Dict[str, MCPTools]):
+        """由 app.py 呼叫，注入 MCP Client"""
+        self._global_toolkits = toolkits_dict
+        logger.info("💉 MCP Toolkit injected into PlannerService successfully.")
 
-class PlannerService:
-    """
-    PlannerService 封裝了所有的業務流程 (Step 1-4)。
-    修正：使用 class level dictionary 來保存活著的 session 物件，防止 Agent 丟失。
-    """
+    def _inject_session_id_into_toolkit(self, toolkit: MCPTools, session_id: str):
+        """
+        Monkey Patch 2.0:
+        攔截 Toolkit 產生的 Function，並在執行時自動注入 session_id 參數。
+        """
+        # 1. 備份原始的 get_tools 方法
+        # 因為 Agno 是呼叫 get_tools() 來取得工具列表的
+        original_get_tools = toolkit.functions
 
-    # 🌟 [Fix] In-Memory Store: 保存包含 Agent 實例的完整 Session 物件
-    _active_sessions: Dict[str, UserSession] = {}
-    _cancelled_sessions: set = set()
+        def get_tools_wrapper():
+            # 2. 取得原始工具列表 (List[Function])
+            tools = original_get_tools
+
+            for tool in tools:
+                # 3. 備份每個工具的執行入口 (entrypoint)
+                original_entrypoint = tool.entrypoint
+
+                # 4. 定義新的執行入口 (Wrapper)
+                def entrypoint_wrapper(*args, **kwargs):
+                    # 🔥 核心魔法：在這裡偷偷塞入 session_id
+                    # 這樣 LLM 沒傳這個參數，也會被自動補上
+                    kwargs['session_id'] = session_id
+
+                    # 執行原始 MCP 呼叫
+                    return original_entrypoint(*args, **kwargs)
+
+                # 5. 替換掉入口
+                tool.entrypoint = entrypoint_wrapper
+
+            return tools
+
+        # 6. 將 Toolkit 的 get_tools 換成我們的 Wrapper
+        # 這是 Instance Level 的修改，只會影響當前這個 Agent 的 Toolkit
+        toolkit.get_tools = get_tools_wrapper
 
     def cancel_session(self, session_id: str):
-        """標記 Session 為取消狀態"""
         if session_id:
             logger.info(f"🛑 Requesting cancellation for session: {session_id}")
             self._cancelled_sessions.add(session_id)
 
     def _get_live_session(self, incoming_session: UserSession) -> UserSession:
-        """
-        從 Gradio 傳來的 incoming_session 恢復 Live Session
-        """
         sid = incoming_session.session_id
-
-        if not sid:
-            return incoming_session
-
-        # 1. 如果內存中有此 Session
+        if not sid: return incoming_session
         if sid and sid in self._active_sessions:
             live_session = self._active_sessions[sid]
-
-            # 同步基礎數據
             live_session.lat = incoming_session.lat
             live_session.lng = incoming_session.lng
-
-            # 🔥 關鍵修正：確保 API Settings 不會被覆蓋為空
-            # 如果 incoming 有設定，就用 incoming 的；否則保留 live 的
             if incoming_session.custom_settings:
-                # 合併設定，優先使用 incoming (前端最新)
                 live_session.custom_settings.update(incoming_session.custom_settings)
-
-            # 同步聊天記錄
             if len(incoming_session.chat_history) > len(live_session.chat_history):
                 live_session.chat_history = incoming_session.chat_history
-
             return live_session
-
-        # 2. 如果是新的 Session，註冊它
         self._active_sessions[sid] = incoming_session
         return incoming_session
 
-    def _inject_tool_instance(self, tool_instance, session_id):
-        """
-        Monkey Patch: 在 Tool 執行前，將 Session ID 寫入 Repo 的 Thread Local。
-        這樣 Repo.save() 就能在同一個執行緒中讀到 ID。
-        """
-
-        for attr_name in dir(tool_instance):
-            if attr_name.startswith("_"): continue
-            attr = getattr(tool_instance, attr_name)
-
-            if callable(attr):
-                if attr_name in ["register", "toolkit_id"]: continue
-
-                def create_wrapper(original_func, sid):
-                    def wrapper(*args, **kwargs):
-                        # 🔥 1. 設定 Thread Local Context
-                        poi_repo.set_thread_session(sid)
-                        try:
-                            # 🔥 2. 執行 Tool
-                            return original_func(*args, **kwargs)
-                        finally:
-                            # (可選) 清理 context，防止污染線程池中的下一個任務
-                            # 但在单次請求中，保留著通常也沒問題，覆蓋即可
-                            pass
-
-                    return wrapper
-
-                setattr(tool_instance, attr_name, create_wrapper(attr, session_id))
-
     def initialize_agents(self, session: UserSession, lat: float, lng: float) -> UserSession:
         if not session.session_id:
             session.session_id = str(uuid.uuid4())
             logger.info(f"🆔 Generated New Session ID: {session.session_id}")
 
-
         session = self._get_live_session(session)
         session.lat = lat
         session.lng = lng
-
         if not session.user_state:
             session.user_state = UserState(location=Location(lat=lat, lng=lng))
         else:
             session.user_state.location = Location(lat=lat, lng=lng)
 
         if session.planner_agent is not None:
-            logger.info(f"♻️ Agents already initialized for {session.session_id}")
             return session
 
-            # 1. 讀取設定
+        # 1. 設定模型 (Models)
         settings = session.custom_settings
         provider = settings.get("llm_provider", "Gemini")
         main_api_key = settings.get("model_api_key")
         selected_model_id = settings.get("model", "gemini-2.5-flash")
         helper_model_id = settings.get("groq_fast_model", "openai/gpt-oss-20b")
-        google_map_key = settings.get("google_maps_api_key")
-        weather_map_key = settings.get("openweather_api_key")
-
-            # 🔥 讀��� Fast Mode 設定
         enable_fast_mode = settings.get("enable_fast_mode", False)
         groq_api_key = settings.get("groq_api_key", "")
 
-        model_logger = {"main_provider": provider, "main_model": selected_model_id, "sub_model": None,
-                            "fast_mode": enable_fast_mode}
-
-        # 2. 初始化 "主模型 (Brain)" - 負責 Planner, Leader, Presenter
+        # 初始化 Main Brain
         if provider.lower() == "gemini":
-            thinking_budget = None
-            if '2.5' in selected_model_id:
-                thinking_budget = 1024
-
-            main_brain = Gemini(id=selected_model_id,
-                                api_key=main_api_key,
-                                thinking_budget=thinking_budget,
+            main_brain = Gemini(id=selected_model_id, api_key=main_api_key, thinking_budget=1024,
                                 safety_settings=gemini_safety_settings)
         elif provider.lower() == "openai":
-            main_brain = OpenAIChat(id=selected_model_id, api_key=main_api_key, reasoning_effort="low")
+            main_brain = OpenAIChat(id=selected_model_id, api_key=main_api_key)
         elif provider.lower() == "groq":
             main_brain = Groq(id=selected_model_id, api_key=main_api_key, temperature=0.1)
         else:
-            main_brain = Gemini(id='gemini-2.5-flash', api_key=main_api_key, thinking_budget=1024)
+            main_brain = Gemini(id='gemini-2.5-flash', api_key=main_api_key)
 
-        # 3. 初始化 "輔助模型 (Muscle)" - 負責 Scout, Optimizer, Navigator
-        helper_model = None
-
-        # 🔥 判斷是否啟用 Fast Mode
+        # 初始化 Helper Model
         if enable_fast_mode and groq_api_key:
-            model_logger["sub_model"] = helper_model_id
-            logger.info(f"⚡ Fast Mode ENABLED: Using Groq - {helper_model_id} for helpers.")
-            helper_model = Groq(
-                    id=model_logger["sub_model"],
-                    api_key=groq_api_key,
-                    temperature=0.1
-                )
+            helper_model = Groq(id=helper_model_id, api_key=groq_api_key, temperature=0.1)
         else:
-                # 如果沒開 Fast Mode，或者沒填 Groq Key，就使用主模型 (或其 Lite 版本)
-            logger.info("🐢 Fast Mode DISABLED: Helpers using Main Provider.")
             if provider.lower() == "gemini":
-                model_logger["sub_model"] = "gemini-2.5-flash-lite"
-                helper_model = Gemini(id=model_logger["sub_model"], api_key=main_api_key,safety_settings=gemini_safety_settings)
+                helper_model = Gemini(id="gemini-2.5-flash-lite", api_key=main_api_key,
+                                      safety_settings=gemini_safety_settings)
             elif provider.lower() == "openai":
-                model_logger["sub_model"] = "gpt-5-nano"
-                helper_model = OpenAIChat(id=model_logger["sub_model"], api_key=main_api_key, reasoning_effort="low")
-            elif provider.lower() == "groq":
-                model_logger["sub_model"] = "openai/gpt-oss-20b"
-                helper_model = Groq(id=model_logger["sub_model"], api_key=main_api_key, temperature=0.1)
-
+                helper_model = OpenAIChat(id="gpt-4o-mini", api_key=main_api_key)
+            else:
+                helper_model = main_brain
 
-            # 4. 分配模型給 Agents
-            # 🧠 大腦組：需要高智商
         models_dict = {
-                "team": main_brain,  # Leader: 指揮需要聰明
-                "presenter": main_brain,  # Presenter: 寫作需要文筆
-                # 💪 肌肉組：需要速度 (若 Fast Mode 開啟，這裡就是 Groq)
-                "scout": helper_model,
-                "optimizer": helper_model,
-                "navigator": helper_model,
-                "weatherman": helper_model
+            "team": main_brain,
+            "presenter": main_brain,
+            "scout": helper_model,
+            "optimizer": helper_model,
+            "navigator": helper_model,
+            "weatherman": helper_model
         }
 
-        planner_model = main_brain
+        # 2. 準備 Tools (🔥 MCP 重構核心)
+        if not self._global_toolkits:
+            logger.warning("⚠️ MCP Toolkit is NOT initialized! Agents will have no tools.")
 
-        # 3. 準備 Tools (先實例化，還不要給 Agent)
-        scout_tool = ScoutToolkit(google_map_key)
-        optimizer_tool = OptimizationToolkit()
-        navigator_tool = NavigationToolkit(google_map_key)
-        weather_tool = WeatherToolkit(weather_map_key)
-        reader_tool = ReaderToolkit()
+        def get_tool_list(agent_name):
+            toolkit = self._global_toolkits.get(agent_name)
+            return [toolkit] if toolkit else []
 
-        # 4. 🔥 執行注入！確保所有 Agent 的 Tools 都帶有 Session ID
-        self._inject_tool_instance(scout_tool, session.session_id)
-        self._inject_tool_instance(optimizer_tool, session.session_id)
-        self._inject_tool_instance(navigator_tool, session.session_id)
-        self._inject_tool_instance(weather_tool, session.session_id)
-        self._inject_tool_instance(reader_tool, session.session_id)
-
-        # 5. 構建 Tools Dict (使用已注入的 Tool 實例)
         tools_dict = {
-            "scout": [scout_tool],
-            "optimizer": [optimizer_tool],
-            "navigator": [navigator_tool],
-            "weatherman": [weather_tool],
-            "presenter": [reader_tool],
+            "scout": get_tool_list("scout"),
+            "optimizer": get_tool_list("optimizer"),
+            "navigator": get_tool_list("navigator"),
+            "weatherman": get_tool_list("weatherman"),
+            "presenter": get_tool_list("presenter"),
         }
 
+
         planner_kwargs = {
-            "additional_context": get_context(session.user_state),  # 這裡現在安全了
+            "additional_context": get_context(session.user_state),
             "timezone_identifier": session.user_state.utc_offset,
             "debug_mode": False,
         }
-
         team_kwargs = {"timezone_identifier": session.user_state.utc_offset}
 
-        # 6. 建立 Agents
-        session.planner_agent = create_planner_agent(planner_model, planner_kwargs, session_id=session.session_id)
+        # 3. 建立 Agents
+        session.planner_agent = create_planner_agent(main_brain, planner_kwargs, session_id=session.session_id)
         session.core_team = create_core_team(models_dict, team_kwargs, tools_dict, session_id=session.session_id)
 
         self._active_sessions[session.session_id] = session
-
-        logger.info(f"✅ Agents initialized for session {session.session_id}")
+        logger.info(f"✅ Agents initialized (MCP Mode) for session {session.session_id}")
         return session
 
     # ================= Step 1: Analyze Tasks =================
 
     def run_step1_analysis(self, user_input: str, auto_location: bool,
                            lat: float, lng: float, session: UserSession) -> Generator[Dict[str, Any], None, None]:
-
-        # 🛡️ 檢查 1: 用戶輸入是否為空
         if not user_input or len(user_input.strip()) == 0:
-            yield {
-                "type": "error",
-                "message": "⚠️ Please enter your plans first!",
-                "stream_text": "Waiting for input...",
-                "block_next_step": True  # 🔥 新增 flag 阻止 UI 跳轉
-            }
+            yield {"type": "error", "message": "⚠️ Please enter your plans first!",
+                   "stream_text": "Waiting for input...", "block_next_step": True}
             return
-
-            # 🛡️ 驗證 2: 位置檢查
-            # 前端 JS 如果失敗會回傳 0, 0
         if auto_location and (lat == 0 or lng == 0):
-            yield {
-                "type": "error",
-                "message": "⚠️ Location detection failed. Please uncheck 'Auto-detect' and enter manually.",
-                "stream_text": "Location Error...",
-                "block_next_step": True
-            }
+            yield {"type": "error", "message": "⚠️ Location detection failed.", "stream_text": "Location Error...",
+                   "block_next_step": True}
             return
-
         if not auto_location and (lat is None or lng is None):
-            yield {
-                "type": "error",
-                "message": "⚠️ Please enter valid Latitude/Longitude.",
-                "stream_text": "Location Error...",
-                "block_next_step": True
-            }
+            yield {"type": "error", "message": "⚠️ Please enter valid Latitude/Longitude.",
+                   "stream_text": "Location Error...", "block_next_step": True}
             return
 
         try:
             session = self.initialize_agents(session, lat, lng)
-
-            # 階段 1: 初始化
             self._add_reasoning(session, "planner", "🚀 Starting analysis...")
-            yield {
-                "type": "stream",
-                "stream_text": "🤔 Analyzing your request with AI...",
-                "agent_status": ("planner", "working", "Initializing..."),
-                "session": session
-            }
-
-            # 階段 2: 提取任務 (即時串流優化)
+            yield {"type": "stream", "stream_text": "🤔 Analyzing your request with AI...",
+                   "agent_status": ("planner", "working", "Initializing..."), "session": session}
+
             self._add_reasoning(session, "planner", f"Processing: {user_input[:50]}...")
             current_text = "🤔 Analyzing your request with AI...\n📋 AI is extracting tasks..."
 
-            # 呼叫 Agent
             planner_stream = session.planner_agent.run(
                 f"help user to update the task_list, user's message: {user_input}",
                 stream=True, stream_events=True
             )
 
-            accumulated_response = ""
-            displayed_text = current_text + "\n\n"
-
+            accumulated_response, displayed_text = "", current_text + "\n\n"
             for chunk in planner_stream:
                 if chunk.event == RunEvent.run_content:
                     content = chunk.content
                     accumulated_response += content
-                    if "@@@" not in accumulated_response:  # 簡單過濾 JSON 標記
+                    if "@@@" not in accumulated_response:
                         displayed_text += content
-
                         formatted_text = displayed_text.replace("\n", "<br/>")
-                        yield {
-                            "type": "stream",
-                            "stream_text": formatted_text,
-                            "agent_status": ("planner", "working", "Thinking..."),
-                            "session": session
-                        }
-
-            # 解析 JSON 結果
+                        yield {"type": "stream", "stream_text": formatted_text,
+                               "agent_status": ("planner", "working", "Thinking..."), "session": session}
+
             json_data = "{" + accumulated_response.split("{", maxsplit=1)[-1]
             json_data = json_data.replace("`", "").replace("@", "").replace("\\", " ").replace("\n", " ")
-            task_list_data = {}
+
             try:
                 task_list_data = json.loads(json_data)
                 if task_list_data["global_info"]["start_location"].lower() == "user location":
-                    task_list_data["global_info"]["start_location"] = {
-                        "lat": lat,
-                        "lng": lng
-                    }
-
-                session.planner_agent.update_session_state(
-                    session_id=session.session_id,
-                    session_state_updates={"task_list": task_list_data}
-                )
-
+                    task_list_data["global_info"]["start_location"] = {"lat": lat, "lng": lng}
+                session.planner_agent.update_session_state(session_id=session.session_id,
+                                                           session_state_updates={"task_list": task_list_data})
                 session.task_list = self._convert_task_list_to_ui_format(task_list_data)
             except Exception as e:
                 logger.error(f"Failed to parse task_list: {e}")
-                print(json_data)
                 session.task_list = []
 
-            # 🛡️ 檢查 2: Planner 是否回傳空列表
-            if not session.task_list or len(session.task_list) == 0:
+            if not session.task_list:
                 err_msg = "⚠️ AI couldn't identify any tasks."
                 self._add_reasoning(session, "planner", "❌ No tasks found")
-                yield {
-                    "type": "error",
-                    "message": err_msg,
-                    "stream_text": err_msg,
-                    "session": session,
-                    "block_next_step": True  # 🔥 阻止 UI 跳轉
-                }
+                yield {"type": "error", "message": err_msg, "stream_text": err_msg, "session": session,
+                       "block_next_step": True}
                 return
 
             if "priority" in session.task_list:
@@ -422,17 +283,11 @@ class PlannerService:
 
             high_priority = sum(1 for t in session.task_list if t.get("priority") == "HIGH")
             total_time = sum(int(t.get("duration", "0").split()[0]) for t in session.task_list if t.get("duration"))
-            logger.info(f"✅ Task list: {task_list_data}")
-            yield {
-                "type": "complete",
-                "stream_text": "Analysis complete!",
-                "start_location": task_list_data["global_info"].get("start_location", "N/A"),
-                "high_priority": high_priority,
-                "total_time": total_time,
-                "start_time": task_list_data["global_info"].get("departure_time", "N/A"),
-                "session": session,
-                "block_next_step": False
-            }
+            yield {"type": "complete", "stream_text": "Analysis complete!",
+                   "start_location": task_list_data["global_info"].get("start_location", "N/A"),
+                   "high_priority": high_priority, "total_time": total_time,
+                   "start_time": task_list_data["global_info"].get("departure_time", "N/A"), "session": session,
+                   "block_next_step": False}
 
         except Exception as e:
             logger.error(f"Error: {e}")
@@ -441,22 +296,13 @@ class PlannerService:
     # ================= Task Modification (Chat) =================
 
     def modify_task_chat(self, user_message: str, session: UserSession) -> Generator[Dict[str, Any], None, None]:
-
-        # 🛡️ 檢查 3: Chat 輸入是否為空
         if not user_message or len(user_message.replace(' ', '')) == 0:
-            yield {
-                "type": "chat_error",
-                "message": "Please enter a message.",
-                "session": session
-            }
+            yield {"type": "chat_error", "message": "Please enter a message.", "session": session}
             return
 
         session = self._get_live_session(session)
-
-        # 用戶輸入上屏
-        session.chat_history.append({
-            "role": "user", "message": user_message, "time": datetime.now().strftime("%H:%M:%S")
-        })
+        session.chat_history.append(
+            {"role": "user", "message": user_message, "time": datetime.now().strftime("%H:%M:%S")})
         yield {"type": "update_history", "session": session}
 
         try:
@@ -467,10 +313,8 @@ class PlannerService:
                     yield {"type": "chat_error", "message": "Session lost. Please restart.", "session": session}
                     return
 
-            # Agent 思考中
-            session.chat_history.append({
-                "role": "assistant", "message": "🤔 AI is thinking...", "time": datetime.now().strftime("%H:%M:%S")
-            })
+            session.chat_history.append(
+                {"role": "assistant", "message": "🤔 AI is thinking...", "time": datetime.now().strftime("%H:%M:%S")})
             yield {"type": "update_history", "session": session}
 
             planner_stream = session.planner_agent.run(
@@ -481,302 +325,167 @@ class PlannerService:
             accumulated_response = ""
             for chunk in planner_stream:
                 if chunk.event == RunEvent.run_content:
-                    content = chunk.content
-                    accumulated_response += content
-                    if "@@@" not in accumulated_response:  # 簡單過濾 JSON 標記
-                        accumulated_response += content
-                        formatted_text = accumulated_response.replace("\n", "<br/>")
+                    accumulated_response += chunk.content
 
             json_data = "{" + accumulated_response.split("{", maxsplit=1)[-1]
             json_data = json_data.replace("`", "").replace("@", "").replace("\\", " ").replace("\n", " ")
 
             try:
                 task_list_data = json.loads(json_data)
-                if isinstance(task_list_data["global_info"]["start_location"], str) and task_list_data["global_info"]["start_location"].lower() == "user location":
-                    task_list_data["global_info"]["start_location"] = {
-                        "lat": session.lat,
-                        "lng": session.lng
-                    }
-                session.planner_agent.update_session_state(
-                    session_id=session.session_id,
-                    session_state_updates={"task_list": task_list_data}
-                )
+                if isinstance(task_list_data["global_info"]["start_location"], str) and task_list_data["global_info"][
+                    "start_location"].lower() == "user location":
+                    task_list_data["global_info"]["start_location"] = {"lat": session.lat, "lng": session.lng}
+                session.planner_agent.update_session_state(session_id=session.session_id,
+                                                           session_state_updates={"task_list": task_list_data})
                 session.task_list = self._convert_task_list_to_ui_format(task_list_data)
             except Exception as e:
                 logger.error(f"Failed to parse modified task_list: {e}")
-                print(json_data)
                 raise e
 
-            # 🔥 更新 Summary (回應 "Does summary still exist?" -> Yes!)
             high_priority = sum(1 for t in session.task_list if t.get("priority") == "HIGH")
             total_time = sum(int(t.get("duration", "0").split()[0]) for t in session.task_list if t.get("duration"))
             start_location = task_list_data["global_info"].get("start_location", "N/A")
-            date = task_list_data["global_info"].get("departure_time", "N/A"),
+            date = task_list_data["global_info"].get("departure_time", "N/A")
 
             summary_html = create_summary_card(len(session.task_list), high_priority, total_time, start_location, date)
-
-            done_message = session.chat_history[-1]["message"] = "✅ Tasks updated based on your request."
-
-            session.chat_history[-1] = {
-                "role": "assistant",
-                "message": done_message,
-                "time": datetime.now().strftime("%H:%M:%S")
-            }
+            session.chat_history[-1] = {"role": "assistant", "message": "✅ Tasks updated.",
+                                        "time": datetime.now().strftime("%H:%M:%S")}
             self._add_reasoning(session, "planner", f"Updated: {user_message[:30]}...")
 
-            yield {
-                "type": "complete",
-                "summary_html": summary_html,  # 回傳新的 Summary
-                "session": session
-            }
+            yield {"type": "complete", "summary_html": summary_html, "session": session}
 
         except Exception as e:
             logger.error(f"Chat error: {e}")
-            session.chat_history.append({
-                "role": "assistant", "message": f"❌ Error: {str(e)}", "time": datetime.now().strftime("%H:%M:%S")
-            })
+            session.chat_history.append(
+                {"role": "assistant", "message": f"❌ Error: {str(e)}", "time": datetime.now().strftime("%H:%M:%S")})
             yield {"type": "update_history", "session": session}
 
-    # ================= Step 2: Search POIs =================
-
-    def run_step2_search(self, session: UserSession) -> Dict[str, Any]:
-        # 🌟 [Fix] 獲取 Live Session
-        session = self._get_live_session(session)
-        if session.session_id:
-            set_session_id(session.session_id)
-            logger.info(f"🔄 [Step 2] Session Context Set: {session.session_id}")
-
-        return {"session": session}
-
     # ================= Step 3: Run Core Team =================
-
-    def run_step3_team(self, session: UserSession) -> Generator[Dict[str, Any], None, None]:
+    async def run_step3_team(self, session: UserSession) -> AsyncGenerator[Dict[str, Any], None]:
+        token = client_session_ctx.set(session.session_id)
 
         attempt = 0
         success = False
+        start_time = time.perf_counter()
         try:
             session = self._get_live_session(session)
             sid = session.session_id
-
-            if sid in self._cancelled_sessions:
-                self._cancelled_sessions.remove(sid)
-
-            if session.session_id:
-                set_session_id(session.session_id)
-                logger.info(f"🔄 [Step 3] Session Context Set: {session.session_id}")
-
+            if sid in self._cancelled_sessions: self._cancelled_sessions.remove(sid)
             if not session.task_list:
                 yield {"type": "error", "message": "No tasks to plan.", "session": session}
                 return
 
-            # 準備 Task List String
             task_list_input = session.planner_agent.get_session_state()["task_list"]
             task_list_str = json.dumps(task_list_input, indent=2, ensure_ascii=False) if isinstance(task_list_input, (
-            dict, list)) else str(task_list_input)
+                dict, list)) else str(task_list_input)
 
             self._add_reasoning(session, "team", "🎯 Multi-agent collaboration started")
-
-            # 🔥 初始狀態
-            yield {
-                "type": "reasoning_update",
-                "session": session,
-                "agent_status": ("team", "working", "Analyzing tasks...")
-            }
-
-            #print(f"task_list_input: {task_list_str}")
-
-            message = task_list_str
+            yield {"type": "reasoning_update", "session": session,
+                   "agent_status": ("team", "working", "Analyzing tasks...")}
 
             while attempt < max_retries and not success:
                 attempt += 1
-
-                # 如果是第 2 次以上嘗試，發個 log
-                if attempt > 1:
-                    logger.warning(f"🔄 Retry attempt {attempt}/{max_retries} for Session {session.session_id}")
-                    # 可以選擇在這裡 yield 一個 "Retrying..." 的狀態給 UI (選用)
-
                 try:
-                    # 🔥 [CRITICAL FIX] 使用 Patch Context 包裹執行區塊
-                    with patch_repo_context(session.session_id):
-                        active_agents = set()
-                        team_stream = session.core_team.run(
-                            message,
-                            stream=True, stream_events=True, session_id=session.session_id
-                        )
-
-                        report_content = ""
-                        start_time = time.perf_counter()
-                        has_content = False
-                        # 🔥 Event Loop: 捕捉事件並 yield 給 UI
-                        for event in team_stream:
-                            if event.event in [RunEvent.run_content, RunEvent.tool_call_started]:
-                                has_content = True
-                                success = True  # 標記成功
-
-                            if sid in self._cancelled_sessions:
-                                logger.warning(f"🛑 Execution terminated by user for session {sid}")
-                                self._cancelled_sessions.remove(sid)
-                                yield {"type": "error", "message": "Plan cancelled by user."}
-                                return
-
-                            # 1. 捕捉 Agent "開始工作"
-                            if event.event == RunEvent.run_started:
-                                agent_id = event.agent_id or "team"
-                                if not event.agent_id: agent_id = "team"
-
-                                active_agents.add(agent_id)
-                                if agent_id == "presenter":
-                                    report_content = ""
-
-                                yield {
-                                    "type": "reasoning_update",
-                                    "session": session,
-                                    "agent_status": (agent_id, "working", "Thinking...")
-                                }
-
-                            # 2. 捕捉 Agent "完成工作" (⭐⭐ 修正重點 ⭐⭐)
-                            elif event.event == RunEvent.run_completed:
-                                agent_id = event.agent_id or "team"
-                                if not event.agent_id: agent_id = "team"
-
-                                # A. 如果是 Leader：絕對不准休息！
-                                if agent_id == "team":
-                                    yield {
-                                        "type": "reasoning_update",
-                                        "session": session,
-                                        "agent_status": ("team", "working", "Processing...")
-                                    }
-                                    continue  # 跳過設為 Idle 的步驟
-
-                                # B. 如果是 Member：做完工作了
-                                if agent_id in active_agents:
-                                    active_agents.remove(agent_id)
-
-                                # B-1. 成員變灰 (下班)
-                                yield {
-                                    "type": "reasoning_update",
-                                    "session": session,
-                                    "agent_status": (agent_id, "idle", "Standby")
-                                }
-
-                                # 🔥🔥 B-2. (關鍵新增) Leader 立刻接手 (上班) 🔥🔥
-                                # 這消除了成員做完 -> Leader 分派下一個任務之間的空窗期
-                                yield {
-                                    "type": "reasoning_update",
-                                    "session": session,
-                                    "agent_status": ("team", "working", "Reviewing results...")
-                                }
-
-                            # 3. 捕捉 Report 內容
-                            elif event.event == RunEvent.run_content and event.agent_id == "presenter":
-                                report_content += event.content
-                                yield {
-                                    "type": "report_stream",
-                                    "content": report_content,
-                                    "session": session
-                                }
-
-                            # 4. Team Delegate (分派任務)
-                            elif event.event == TeamRunEvent.tool_call_started:
-                                tool_name = event.tool.tool_name
-
-                                # Leader 顯示正在指揮
-                                yield {
-                                    "type": "reasoning_update",
-                                    "session": session,
-                                    "agent_status": ("team", "working", "Orchestrating...")
-                                }
-
-                                if "delegate_task_to_member" in tool_name:
-                                    member_id = event.tool.tool_args.get("member_id", "unknown")
-                                    msg = f"Delegating to {member_id}..."
-                                    self._add_reasoning(session, "team", f"👉 {msg}")
-
-                                    # 成員亮燈 (接單)
-                                    yield {
-                                        "type": "reasoning_update",
-                                        "session": session,
-                                        "agent_status": (member_id, "working", "Receiving Task...")
-                                    }
-                                else:
-                                    self._add_reasoning(session, "team", f"🔧 Tool: {tool_name}")
-
-                            # 5. Member Tool Start
-                            elif event.event == RunEvent.tool_call_started:
-                                member_id = event.agent_id
-                                tool_name = event.tool.tool_name
-
-                                # 雙重保險：Member 在用工具時，Leader 也是亮著的 (Monitoring)
-                                yield {
-                                    "type": "reasoning_update",
-                                    "session": session,
-                                    "agent_status": ("team", "working", f"Monitoring {member_id}...")
-                                }
-
-                                self._add_reasoning(session, member_id, f"Using tool: {tool_name}...")
-                                yield {
-                                    "type": "reasoning_update",
-                                    "session": session,
-                                    "agent_status": (member_id, "working", f"Running Tool...")
-                                }
-
-                            # 6. Team Complete
-                            elif event.event == TeamRunEvent.run_completed:
-                                self._add_reasoning(session, "team", "🎉 Planning process finished")
-                                if hasattr(event, 'metrics'):
-                                    logger.info(f"Total tokens: {event.metrics.total_tokens}")
-                                    logger.info(f"Input tokens: {event.metrics.input_tokens}")
-                                    logger.info(f"Output tokens: {event.metrics.output_tokens}")
-
-
-                        if not has_content:
-                            logger.error(f"⚠️ Attempt {attempt}: Agent returned NO content (Silent Failure).")
-                            if attempt < max_retries:
-                                continue  # 重試 while loop
+                    active_agents = set()
+
+                    # 🔥 重點修改 1: 使用 arun (Async Run)
+                    # 🔥 重點修改 2: 這個方法本身回傳的是一個 AsyncGenerator，所以要直接 iterate
+                    team_stream = session.core_team.arun(
+                        task_list_str,
+                        stream=True,
+                        stream_events=True,
+                        session_id=session.session_id
+                    )
+
+                    report_content = ""
+                    start_time = time.perf_counter()
+                    has_content = False
+
+                    # 🔥 重點修改 3: 使用 async for 來迭代
+                    async for event in team_stream:
+                        if event.event in [RunEvent.run_content, RunEvent.tool_call_started]:
+                            has_content = True
+                            success = True
+
+                        if sid in self._cancelled_sessions:
+                            logger.warning(f"🛑 Execution terminated by user for session {sid}")
+                            self._cancelled_sessions.remove(sid)
+                            yield {"type": "error", "message": "Plan cancelled by user."}
+                            return
+
+                        if event.event == RunEvent.run_started:
+                            agent_id = event.agent_id or "team"
+                            active_agents.add(agent_id)
+                            if agent_id == "presenter": report_content = ""
+                            yield {"type": "reasoning_update", "session": session,
+                                   "agent_status": (agent_id, "working", "Thinking...")}
+
+                        elif event.event == RunEvent.run_completed:
+                            agent_id = event.agent_id or "team"
+                            if agent_id == "team":
+                                yield {"type": "reasoning_update", "session": session,
+                                       "agent_status": ("team", "working", "Processing...")}
+                                continue
+                            if agent_id in active_agents: active_agents.remove(agent_id)
+                            yield {"type": "reasoning_update", "session": session,
+                                   "agent_status": (agent_id, "idle", "Standby")}
+                            yield {"type": "reasoning_update", "session": session,
+                                   "agent_status": ("team", "working", "Reviewing results...")}
+
+                        elif event.event == RunEvent.run_content and event.agent_id == "presenter":
+                            report_content += event.content
+                            yield {"type": "report_stream", "content": report_content, "session": session}
+
+                        elif event.event == TeamRunEvent.tool_call_started:
+                            tool_name = event.tool.tool_name
+                            yield {"type": "reasoning_update", "session": session,
+                                   "agent_status": ("team", "working", "Orchestrating...")}
+                            if "delegate_task_to_member" in tool_name:
+                                member_id = event.tool.tool_args.get("member_id", "unknown")
+                                self._add_reasoning(session, "team", f"👉 Delegating to {member_id}...")
+                                yield {"type": "reasoning_update", "session": session,
+                                       "agent_status": (member_id, "working", "Receiving Task...")}
                             else:
-                                raise ValueError("Agent failed to generate output after retries.")
-
-                        break
+                                self._add_reasoning(session, "team", f"🔧 Tool: {tool_name}")
+
+                        elif event.event == RunEvent.tool_call_started:
+                            member_id = event.agent_id
+                            tool_name = event.tool.tool_name
+                            yield {"type": "reasoning_update", "session": session,
+                                   "agent_status": ("team", "working", f"Monitoring {member_id}...")}
+                            self._add_reasoning(session, member_id, f"Using tool: {tool_name}...")
+                            yield {"type": "reasoning_update", "session": session,
+                                   "agent_status": (member_id, "working", f"Running Tool...")}
+
+                        elif event.event == TeamRunEvent.run_completed:
+                            self._add_reasoning(session, "team", "🎉 Planning process finished")
+                            if hasattr(event, 'metrics'):
+                                logger.info(f"Total tokens: {event.metrics.total_tokens}")
+                                logger.info(f"Input tokens: {event.metrics.input_tokens}")
+                                logger.info(f"Output tokens: {event.metrics.output_tokens}")
+
+                    if not has_content and attempt < max_retries: continue
+                    break
 
                 finally:
                     logger.info(f"Run time (s): {time.perf_counter() - start_time}")
 
-
-
             for agent in ["scout", "optimizer", "navigator", "weatherman", "presenter"]:
-                yield {
-                    "type": "reasoning_update",
-                    "session": session,
-                    "agent_status": (agent, "idle", "Standby")
-                }
-
-                # Leader 顯示完成
-            yield {
-                "type": "reasoning_update",
-                "session": session,
-                "agent_status": ("team", "complete", "All Done!")
-            }
-
-            # 迴圈結束
-            session.final_report = report_html = f"## 🎯 Planning Complete\n\n{report_content}"
+                yield {"type": "reasoning_update", "session": session, "agent_status": (agent, "idle", "Standby")}
+            yield {"type": "reasoning_update", "session": session, "agent_status": ("team", "complete", "All Done!")}
 
-            yield {
-                "type": "complete",
-                "report_html": report_html,
-                "session": session,
-                "agent_status": ("team", "complete", "Finished")
-            }
+            session.final_report = report_html = f"## 🎯 Planning Complete\n\n{report_content}"
+            yield {"type": "complete", "report_html": report_html, "session": session,
+                   "agent_status": ("team", "complete", "Finished")}
 
         except GeneratorExit:
-            logger.warning("⚠️ Generator closed by client (Gradio Stop).")
-            return  # 靜默退出，不要報錯
-
+            return
         except Exception as e:
             logger.error(f"Error in attempt {attempt}: {e}")
-            if attempt >= max_retries:
-                yield {"type": "error", "message": str(e), "session": session}
-                return
+            if attempt >= max_retries: yield {"type": "error", "message": str(e), "session": session}
 
+        finally:
+            client_session_ctx.reset(token)
     # ================= Step 4: Finalize =================
 
     def run_step4_finalize(self, session: UserSession) -> Dict[str, Any]:
@@ -787,26 +496,15 @@ class PlannerService:
                 raise ValueError(f"No results found")
 
             structured_data = poi_repo.load(final_ref_id)
-
-            # 1. Timeline
             timeline_html = create_timeline_html_enhanced(structured_data.get("timeline", []))
 
-            # 2. Summary Card & Metrics (快樂表)
             metrics = structured_data.get("metrics", {})
             traffic = structured_data.get("traffic_summary", {})
-            # 🔥 組合 Summary Tab 的內容
-
             task_count = f"{metrics['completed_tasks']} / {metrics['total_tasks']}"
             high_prio = sum(1 for t in session.task_list if t.get("priority") == "HIGH")
-
-            # 時間 (優先使用優化後的時間，如果沒有則用交通總時間)
             total_time = metrics.get("optimized_duration_min", traffic.get("total_duration_min", 0))
-
-            # 距離 (公尺轉公里)
             dist_m = metrics.get("optimized_distance_m", 0)
             total_dist_km = dist_m / 1000.0
-
-            # 效率與節省 (用於快樂表)
             efficiency = metrics.get("route_efficiency_pct", 0)
             saved_dist_m = metrics.get("distance_saved_m", 0)
             saved_time_min = metrics.get("time_saved_min", 0)
@@ -814,8 +512,6 @@ class PlannerService:
             date = structured_data.get("global_info", {}).get("departure_time", "N/A")
 
             summary_card = create_summary_card(task_count, high_prio, int(total_time), start_location, date)
-
-            # B. 進階數據快樂表 (AI Efficiency & Distance)
             eff_color = "#047857" if efficiency >= 80 else "#d97706"
             eff_bg = "#ecfdf5" if efficiency >= 80 else "#fffbeb"
             eff_border = "#a7f3d0" if efficiency >= 80 else "#fde68a"
@@ -823,54 +519,24 @@ class PlannerService:
             ai_stats_html = f"""
                         <div style="display: flex; gap: 12px; margin-bottom: 20px;">
                             <div style="flex: 1; background: {eff_bg}; padding: 16px; border-radius: 12px; border: 1px solid {eff_border};">
-                                <div style="font-size: 0.8rem; color: {eff_color}; font-weight: 600; display: flex; align-items: center; gap: 4px;">
-                                    <span>🚀 AI EFFICIENCY</span>
-                                </div>
-                                <div style="font-size: 1.8rem; font-weight: 800; color: {eff_color}; line-height: 1.2;">
-                                    {efficiency:.1f}%
-                                </div>
-                                <div style="font-size: 0.75rem; color: {eff_color}; opacity: 0.9; margin-top: 4px;">
-                                    ⚡ Saved {saved_time_min:.0f} mins
-                                </div>
+                                <div style="font-size: 0.8rem; color: {eff_color}; font-weight: 600; display: flex; align-items: center; gap: 4px;"><span>🚀 AI EFFICIENCY</span></div>
+                                <div style="font-size: 1.8rem; font-weight: 800; color: {eff_color}; line-height: 1.2;">{efficiency:.1f}%</div>
+                                <div style="font-size: 0.75rem; color: {eff_color}; opacity: 0.9; margin-top: 4px;">⚡ Saved {saved_time_min:.0f} mins</div>
                             </div>
-
                             <div style="flex: 1; background: #eff6ff; padding: 16px; border-radius: 12px; border: 1px solid #bfdbfe;">
                                 <div style="font-size: 0.8rem; color: #2563eb; font-weight: 600;">🚗 TOTAL DISTANCE</div>
-                                <div style="font-size: 1.8rem; font-weight: 800; color: #1d4ed8; line-height: 1.2;">
-                                    {total_dist_km:.2f} <span style="font-size: 1rem;">km</span>
-                                </div>
-                                <div style="font-size: 0.75rem; color: #2563eb; opacity: 0.9; margin-top: 4px;">
-                                    📉 Reduced {saved_dist_m} m
-                                </div>
+                                <div style="font-size: 1.8rem; font-weight: 800; color: #1d4ed8; line-height: 1.2;">{total_dist_km:.2f} <span style="font-size: 1rem;">km</span></div>
+                                <div style="font-size: 0.75rem; color: #2563eb; opacity: 0.9; margin-top: 4px;">📉 Reduced {saved_dist_m} m</div>
                             </div>
-                        </div>
-                        """
+                        </div>"""
 
             full_summary_html = f"{summary_card}{ai_stats_html}<h3>📍 Itinerary Timeline</h3>{timeline_html}"
-
-            # C. 其他 Tab 內容
-            # task_list_html = self.generate_task_list_html(session)
-
-            # 3. Map
             map_fig = create_animated_map(structured_data)
-            #if isinstance(map_fig, str):
-            #    logger.error(f"CRITICAL: map_fig is a string ('{map_fig}'). Creating default map.")
-            #    from core.visualizers import create_animated_map as default_map_gen
-            #   map_fig = default_map_gen(None)
-
-            # 4. Task List
             task_list_html = self.generate_task_list_html(session)
-
             session.planning_completed = True
 
-            return {
-                "type": "success",
-                "summary_tab_html": full_summary_html,  # 快樂表
-                "report_md": session.final_report,  # Full Report
-                "task_list_html": task_list_html,  # Task List
-                "map_fig": map_fig,  # Map
-                "session": session
-            }
+            return {"type": "success", "summary_tab_html": full_summary_html, "report_md": session.final_report,
+                    "task_list_html": task_list_html, "map_fig": map_fig, "session": session}
 
         except Exception as e:
             logger.error(f"Finalize error: {e}", exc_info=True)
@@ -879,11 +545,8 @@ class PlannerService:
     # ================= Helpers =================
 
     def _add_reasoning(self, session: UserSession, agent: str, message: str):
-        session.reasoning_messages.append({
-            "agent": agent,
-            "message": message,
-            "time": datetime.now().strftime("%H:%M:%S")
-        })
+        session.reasoning_messages.append(
+            {"agent": agent, "message": message, "time": datetime.now().strftime("%H:%M:%S")})
 
     def _convert_task_list_to_ui_format(self, task_list_data):
         ui_tasks = []
@@ -893,9 +556,8 @@ class PlannerService:
             tasks = task_list_data
         else:
             return []
-
         for i, task in enumerate(tasks, 1):
-            ui_task = {
+            ui_tasks.append({
                 "id": i,
                 "title": task.get("description", "Task"),
                 "priority": task.get("priority", "MEDIUM"),
@@ -903,26 +565,18 @@ class PlannerService:
                 "duration": f"{task.get('service_duration_min', 30)} minutes",
                 "location": task.get("location_hint", "To be determined"),
                 "icon": self._get_task_icon(task.get("category", "other"))
-            }
-            ui_tasks.append(ui_task)
+            })
         return ui_tasks
 
     def _get_task_icon(self, category: str) -> str:
-        icons = {
-            "medical": "🏥", "shopping": "🛒", "postal": "📮",
-            "food": "🍽️", "entertainment": "🎭", "transportation": "🚗",
-            "other": "📋"
-        }
+        icons = {"medical": "🏥", "shopping": "🛒", "postal": "📮", "food": "🍽️", "entertainment": "🎭",
+                 "transportation": "🚗", "other": "📋"}
         return icons.get(category.lower(), "📋")
 
     def generate_task_list_html(self, session: UserSession) -> str:
-        if not session.task_list:
-            return "<p>No tasks available</p>"
+        if not session.task_list: return "<p>No tasks available</p>"
         html = ""
         for task in session.task_list:
-            html += create_task_card(
-                task["id"], task["title"], task["priority"],
-                task["time"], task["duration"], task["location"],
-                task.get("icon", "📋")
-            )
+            html += create_task_card(task["id"], task["title"], task["priority"], task["time"], task["duration"],
+                                     task["location"], task.get("icon", "📋"))
         return html

src/infra/poi_repository.py

@@ -10,18 +10,39 @@ logger = get_logger(__name__)
 
 
 class PoiRepository:
-    DB_DIR = "storage"
+    # =========================================================================
+    # 1. 設定絕對路徑 (Class Attributes) - 確保在 __init__ 之前就存在
+    # =========================================================================
+
+    # 抓出這個檔案 (poi_repository.py) 的絕對路徑: .../LifeFlow-AI/src/infra
+    BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+
+    # 往上推兩層回到專案根目錄: .../LifeFlow-AI
+    # (src/infra -> src -> LifeFlow-AI)
+    PROJECT_ROOT = os.path.dirname(os.path.dirname(BASE_DIR))
+
+    # 設定 DB 存放目錄: .../LifeFlow-AI/storage
+    DB_DIR = os.path.join(PROJECT_ROOT, "storage")
+
+    # 設定 DB 完整路徑: .../LifeFlow-AI/storage/lifeflow_payloads.db
     DB_FILE = "lifeflow_payloads.db"
     DB_PATH = os.path.join(DB_DIR, DB_FILE)
 
+    # =========================================================================
+    # 2. 初始化邏輯
+    # =========================================================================
+
     def __init__(self):
+        # 1. 先確保資料夾存在 (這時候 self.DB_DIR 已經讀得到了)
+        os.makedirs(self.DB_DIR, exist_ok=True)
+
+        # 2. 再初始化 DB (這時候 self.DB_PATH 已經讀得到了)
         self._init_db()
-        # ✅ 改用字典來存儲： Key=SessionID, Value=RefID
-        self._session_last_id: Dict[str, str] = {}
 
     def _init_db(self):
-        os.makedirs(self.DB_DIR, exist_ok=True)
+        # 使用 self.DB_PATH
         with sqlite3.connect(self.DB_PATH) as conn:
+            # 1. 既有的資料表
             conn.execute("""
                 CREATE TABLE IF NOT EXISTS offloaded_data (
                     ref_id TEXT PRIMARY KEY,
@@ -31,28 +52,51 @@ class PoiRepository:
                 )
             """)
 
+            # 2. Session 狀態表
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS session_state (
+                    session_id TEXT PRIMARY KEY,
+                    last_ref_id TEXT,
+                    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+                )
+            """)
+
+    # =========================================================================
+    # 3. 讀寫操作
+    # =========================================================================
+
     def save(self, data: Any, data_type: str = "generic") -> str:
         ref_id = f"{data_type}_{uuid.uuid4().hex[:8]}"
 
-        # 1. 寫入物理 DB (持久化)
         with sqlite3.connect(self.DB_PATH) as conn:
+            # 1. 寫入 Payload
             conn.execute(
                 "INSERT INTO offloaded_data (ref_id, data_type, payload) VALUES (?, ?, ?)",
                 (ref_id, data_type, json.dumps(data, default=str))
             )
 
-        # 2. ✅ 記錄這個 Session 的最後 ID
-        current_session = get_session_id()
-        if current_session:
-            self._session_last_id[current_session] = ref_id
-            logger.info(f"💾 [Repo] Saved {ref_id} for Session: {current_session}")
-        else:
-            logger.warning(f"⚠️ [Repo] Warning: No session context found! 'last_id' not tracked.")
+            # 2. 更新 Session 的最後 ID
+            current_session = get_session_id()
+            if current_session:
+                conn.execute("""
+                    INSERT OR REPLACE INTO session_state (session_id, last_ref_id)
+                    VALUES (?, ?)
+                """, (current_session, ref_id))
+
+                logger.info(f"💾 [Repo] Saved {ref_id} for Session: {current_session}")
+            else:
+                # 這裡改用 debug level，以免 log 太多雜訊
+                logger.debug(f"⚠️ [Repo] No session context found, 'last_id' not tracked.")
 
         return ref_id
 
     def load(self, ref_id: str) -> Optional[Any]:
-        # load 保持不變，因為它是靠 ref_id 查的
+        if not ref_id: return None
+
+        # 容錯：如果路徑還沒建立 (理論上 init 已建立，但防呆)
+        if not os.path.exists(self.DB_PATH):
+            return None
+
         with sqlite3.connect(self.DB_PATH) as conn:
             cursor = conn.execute("SELECT payload FROM offloaded_data WHERE ref_id = ?", (ref_id,))
             row = cursor.fetchone()
@@ -60,9 +104,17 @@ class PoiRepository:
                 return json.loads(row[0])
         return None
 
-    # ✅ 新增方法：獲取特定 Session 的最後 ID
     def get_last_id_by_session(self, session_id: str) -> Optional[str]:
-        return self._session_last_id.get(session_id)
+        if not os.path.exists(self.DB_PATH):
+            return None
+
+        with sqlite3.connect(self.DB_PATH) as conn:
+            cursor = conn.execute("SELECT last_ref_id FROM session_state WHERE session_id = ?", (session_id,))
+            row = cursor.fetchone()
+            if row:
+                return row[0]
+        return None
 
 
-poi_repo = PoiRepository()
+# 全域���例
+poi_repo = PoiRepository()

src/tools/navigation_toolkit.py

@@ -28,7 +28,7 @@ class NavigationToolkit(Toolkit):
                     str: A JSON string containing the 'nav_ref_id' (e.g., '{"nav_ref_id": "navigation_result_abc"}').
         """
 
-        print(f"🚗 Navigator: Loading Ref {optimization_ref_id}...")
+        logger.info(f"🚗 Navigator: Loading Ref {optimization_ref_id}...")
         data = poi_repo.load(optimization_ref_id)
 
         if not data:
@@ -65,7 +65,7 @@ class NavigationToolkit(Toolkit):
         user_start = global_info.get("start_location")
         if user_start and "lat" in user_start and "lng" in user_start:
             start_coord = user_start
-            print(f"📍 Using User Start Location: {start_coord}")
+            logger.info(f"📍 Using User Start Location: {start_coord}")
 
         # 3. 依據 Route 的順序組裝 Waypoints
         waypoints = []
@@ -98,7 +98,8 @@ class NavigationToolkit(Toolkit):
             if lat is not None and lng is not None:
                 waypoints.append({"lat": lat, "lng": lng})
             else:
-                print(f"⚠️ Skipped step {i}: No coordinates found. Type: {step_type}, ID: {task_id}")
+                pass
+                logger.warning(f"⚠️ Skipped step {i}: No coordinates found. Type: {step_type}, ID: {task_id}")
 
         # 4. 驗證與呼叫 API
         if len(waypoints) < 2:
@@ -114,7 +115,7 @@ class NavigationToolkit(Toolkit):
             except:
                 start_time = datetime.now(timezone.utc)
 
-            print(f"🚗 Navigator: Calling Google Routes for {len(waypoints)} stops...")
+            logger.info(f"🚗 Navigator: Calling Google Routes for {len(waypoints)} stops...")
 
             traffic_result = self.gmaps.compute_routes(
                 place_points=waypoints,
@@ -135,7 +136,7 @@ class NavigationToolkit(Toolkit):
         if "global_info" not in data:
             data["global_info"] = global_info
 
-        print(f"✅ Traffic and timing calculated successfully.\n {data}")
+        logger.info(f"✅ Traffic and timing calculated successfully.\n {data}")
 
         nav_ref_id = poi_repo.save(data, data_type="navigation_result")
 

src/tools/optimizer_toolkit.py

@@ -39,7 +39,7 @@ class OptimizationToolkit(Toolkit):
                      "message": str
                  }
         """
-        logger.info(f"🧮 Optimizer: Fetching data for {ref_id}...")
+        logger.info(f"🧮 Optimizer: Loading Ref {ref_id}...")
 
         data = poi_repo.load(ref_id)
         if not data:
@@ -72,7 +72,7 @@ class OptimizationToolkit(Toolkit):
                     parsed_time = dt_time.fromisoformat(start_time_str)
 
                     start_time = datetime.combine(default_date, parsed_time)
-                    print(f"⚠️ Warning: Received time-only '{start_time_str}'. Auto-fixed to: {start_time}")
+                    logger.warning(f"⚠️ Warning: Received time-only '{start_time_str}'. Auto-fixed to: {start_time}")
 
                 except ValueError:
                     return json.dumps({
@@ -133,7 +133,7 @@ class OptimizationToolkit(Toolkit):
         # 如果不加這一行，Navigator 就會因為找不到 departure_time 而報錯
         result["tasks"] = tasks
         result["global_info"] = global_info
-        print(f"🧾 Optimizer: Inherited global_info to result.\n {result}")
+        logger.info(f"🧾 Optimizer: Inherited global_info to result.\n {result}")
         # 儲存結果
         result_ref_id = poi_repo.save(result, data_type="optimization_result")
 

src/tools/reader_toolkit.py

@@ -38,7 +38,7 @@ class ReaderToolkit(Toolkit):
         """
 
 
-        logger.info(f"📖 Presenter: QA Checking Ref {ref_id}...")
+        logger.info(f"📖 Presenter: QA Loading Ref {ref_id}...")
 
         data = poi_repo.load(ref_id)
         if not data:

src/tools/scout_toolkit.py

@@ -158,6 +158,7 @@ class ScoutToolkit(Toolkit):
                     anchor_point = {"lat": lat, "lng": lng}
                     logger.info(f"   ✅ Resolved Start: {name}")
             except Exception as e:
+                pass
                 logger.warning(f"   ❌ Error searching start location: {e}")
 
         elif isinstance(start_loc, dict):
@@ -255,14 +256,14 @@ class ScoutToolkit(Toolkit):
                 "candidates": candidates
             }
             enriched_tasks.append(task_entry)
-            #print(f"   - Task {task_id}: Found {len(candidates)} POIs")
+            logger.info(f"   - Task {task_id}: Found {len(candidates)} POIs")
 
         full_payload = {"global_info": global_info, "tasks": enriched_tasks}
         ref_id = poi_repo.save(full_payload, data_type="scout_result")
 
         return json.dumps({
             "status": "SUCCESS",
-            #"message": "Search POI complete.",
+            "message_task": len(enriched_tasks),
             "scout_ref": ref_id,
             "note": "Please pass this scout_ref to the Optimizer immediately."
         })

src/tools/weather_toolkit.py

@@ -16,6 +16,25 @@ class WeatherToolkit(Toolkit):
         self.register(self.check_weather_for_timeline)
 
     def check_weather_for_timeline(self, nav_ref_id: str) -> str:
+
+        """
+        Enriches the solved navigation route with weather forecasts and Air Quality Index (AQI) to create the final timeline.
+
+        This tool is the final post-processing step. It loads the solved route data, calculates precise local arrival times for each stop
+        (dynamically adjusting for the destination's timezone), and fetches specific weather conditions and AQI for those times.
+        It also resolves final location names and saves the complete itinerary for presentation.
+
+        Args:
+            nav_ref_id (str): The unique reference ID returned by the Route Solver (or Navigation) step.
+
+        Returns:
+            str: A JSON string containing the reference ID for the finalized data.
+                 Structure:
+                 {
+                     "final_ref_id": str
+                 }
+        """
+
         logger.debug(f"🌤️ Weatherman: Loading Ref {nav_ref_id}...")
         data = poi_repo.load(nav_ref_id)
         if not data: