webagents 0.1.0__py3-none-any.whl

webagents/agents/skills/core/planning/planner.py

@@ -0,0 +1,343 @@
+"""
+PlannerSkill - Simple Task Planning and Todo Management
+
+A straightforward planner that matches the TypeScript implementation.
+Maintains a single plan state across multiple tool calls for consistent UX.
+"""
+
+import json
+import uuid
+from typing import Dict, List, Any, Optional
+from datetime import datetime
+from dataclasses import dataclass, asdict
+
+from ...base import Skill
+from ....tools.decorators import tool
+
+
+@dataclass
+class PlannerTask:
+    """Represents a single task in a plan"""
+    id: str
+    title: str
+    description: Optional[str] = None
+    status: str = "pending"  # pending, in_progress, completed, cancelled
+    created_at: str = None
+    updated_at: str = None
+
+    def __post_init__(self):
+        if self.created_at is None:
+            self.created_at = datetime.utcnow().isoformat()
+        if self.updated_at is None:
+            self.updated_at = self.created_at
+
+
+@dataclass 
+class PlannerState:
+    """Represents the complete planner state"""
+    plan_id: str
+    title: str
+    description: Optional[str] = None
+    tasks: List[PlannerTask] = None
+    created_at: str = None
+    updated_at: str = None
+    status: str = "active"  # active, completed, cancelled
+
+    def __post_init__(self):
+        if self.tasks is None:
+            self.tasks = []
+        if self.created_at is None:
+            self.created_at = datetime.utcnow().isoformat()
+        if self.updated_at is None:
+            self.updated_at = self.created_at
+
+
+class PlannerSkill(Skill):
+    """
+    Simple task planning and todo management skill that matches the TypeScript implementation.
+    
+    Features:
+    - Single plan state management
+    - Task status tracking (pending, in_progress, completed, cancelled)
+    - State persistence across tool calls
+    - Matches TypeScript planner_tool behavior
+    """
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None):
+        super().__init__(config)
+
+    async def initialize(self, agent_reference):
+        """Initialize with agent reference"""
+        await super().initialize(agent_reference)
+        self.agent = agent_reference
+
+    def _generate_id(self) -> str:
+        """Generate a random ID"""
+        return str(uuid.uuid4())[:8]
+
+    def _get_current_timestamp(self) -> str:
+        """Get current timestamp"""
+        return datetime.utcnow().isoformat()
+
+    def _get_action_message(self, action: str, title: str = None, total_tasks: int = 0, completed_tasks: int = 0) -> str:
+        """Generate action message"""
+        title_part = f' "{title}"' if title else ''
+        
+        if action == 'create_plan':
+            return f"Created new plan{title_part} with {total_tasks} tasks. Start by marking the first task as 'in_progress'."
+        elif action == 'add_task':
+            return f"Added task{title_part} to the plan"
+        elif action == 'update_task':
+            return f"Started task{title_part}. Remember to mark this task as 'completed' when you finish explaining/doing this step."
+        elif action == 'complete_task':
+            next_task_part = '. Move to the next task.' if completed_tasks < total_tasks else ''
+            return f"✅ Completed task{title_part}. Progress: {completed_tasks}/{total_tasks}{next_task_part}"
+        elif action == 'cancel_task':
+            return f"Cancelled task{title_part}"
+        elif action == 'update_plan':
+            return f"Updated plan{title_part}"
+        else:
+            return 'Plan updated'
+
+    @tool(description="Create and manage a single task plan to break down complex work into manageable steps. Use this tool to organize your approach and track progress. CRITICAL: Always pass the complete 'state' object from previous tool results as 'current_state' to maintain the same plan across multiple calls.", scope="all")
+    async def planner_tool(
+        self,
+        action: str,  # create_plan, add_task, update_task, complete_task, cancel_task, update_plan
+        title: Optional[str] = None,
+        description: Optional[str] = None,
+        task_id: Optional[str] = None,
+        tasks: Optional[List[Dict[str, str]]] = None,  # [{"title": "...", "description": "..."}]
+        status: Optional[str] = None,  # pending, in_progress, completed, cancelled
+        current_state: Optional[Dict[str, Any]] = None,
+        context=None
+    ) -> Dict[str, Any]:
+        """
+        Create and manage task plans to break down complex work into manageable steps.
+        
+        Actions:
+        - create_plan: Create a new plan with initial tasks
+        - add_task: Add a task to existing plan
+        - update_task: Update task status
+        - complete_task: Mark task as completed
+        - cancel_task: Mark task as cancelled
+        - update_plan: Update plan details
+        
+        Args:
+            action: The action to perform
+            title: Title for plan or task
+            description: Description for plan or task
+            task_id: ID of task to update (required for task operations)
+            tasks: List of initial tasks when creating plan
+            status: New status for task updates
+            current_state: CRITICAL - Complete state object from previous calls
+        """
+        try:
+            timestamp = self._get_current_timestamp()
+            
+            # Handle state management
+            if action == 'create_plan':
+                # Create new plan
+                state = PlannerState(
+                    plan_id=self._generate_id(),
+                    title=title or 'New Plan',
+                    description=description or '',
+                    created_at=timestamp,
+                    updated_at=timestamp,
+                    status='active'
+                )
+                
+                # Add initial tasks
+                if tasks:
+                    for task_data in tasks:
+                        task = PlannerTask(
+                            id=self._generate_id(),
+                            title=task_data.get('title', ''),
+                            description=task_data.get('description'),
+                            status='pending',
+                            created_at=timestamp,
+                            updated_at=timestamp
+                        )
+                        state.tasks.append(task)
+            else:
+                # For all other actions, require current_state
+                if not current_state:
+                    return {
+                        'success': False,
+                        'action': action,
+                        'error': f"Action '{action}' requires current_state from previous planner_tool result. Please pass the complete 'state' object from the previous call.",
+                        'state': None
+                    }
+                
+                # Reconstruct state from current_state
+                state = PlannerState(
+                    plan_id=current_state['plan_id'],
+                    title=current_state['title'],
+                    description=current_state.get('description'),
+                    status=current_state['status'],
+                    created_at=current_state['created_at'],
+                    updated_at=current_state['updated_at']
+                )
+                
+                # Reconstruct tasks
+                state.tasks = []
+                for task_data in current_state.get('tasks', []):
+                    task = PlannerTask(
+                        id=task_data['id'],
+                        title=task_data['title'],
+                        description=task_data.get('description'),
+                        status=task_data['status'],
+                        created_at=task_data['created_at'],
+                        updated_at=task_data['updated_at']
+                    )
+                    state.tasks.append(task)
+
+            # Execute action
+            if action == 'create_plan':
+                # Already handled above
+                pass
+            
+            elif action == 'add_task':
+                if not title:
+                    raise Exception('Task title is required')
+                
+                new_task = PlannerTask(
+                    id=self._generate_id(),
+                    title=title,
+                    description=description,
+                    status='pending',
+                    created_at=timestamp,
+                    updated_at=timestamp
+                )
+                state.tasks.append(new_task)
+                state.updated_at = timestamp
+            
+            elif action == 'update_task':
+                if not task_id:
+                    raise Exception('Task ID is required for task updates')
+                
+                task = next((t for t in state.tasks if t.id == task_id), None)
+                if not task:
+                    raise Exception(f'Task with ID {task_id} not found')
+                
+                if title:
+                    task.title = title
+                if description is not None:
+                    task.description = description
+                if status:
+                    task.status = status
+                task.updated_at = timestamp
+                state.updated_at = timestamp
+            
+            elif action == 'complete_task':
+                if not task_id:
+                    raise Exception('Task ID is required to complete a task')
+                
+                task = next((t for t in state.tasks if t.id == task_id), None)
+                if not task:
+                    raise Exception(f'Task with ID {task_id} not found')
+                
+                task.status = 'completed'
+                task.updated_at = timestamp
+                state.updated_at = timestamp
+                
+                # Check if all tasks are completed
+                all_completed = all(t.status in ['completed', 'cancelled'] for t in state.tasks)
+                if all_completed and state.tasks:
+                    state.status = 'completed'
+            
+            elif action == 'cancel_task':
+                if not task_id:
+                    raise Exception('Task ID is required to cancel a task')
+                
+                task = next((t for t in state.tasks if t.id == task_id), None)
+                if not task:
+                    raise Exception(f'Task with ID {task_id} not found')
+                
+                task.status = 'cancelled'
+                task.updated_at = timestamp
+                state.updated_at = timestamp
+            
+            elif action == 'update_plan':
+                if title:
+                    state.title = title
+                if description is not None:
+                    state.description = description
+                if status and status in ['active', 'completed', 'cancelled']:
+                    state.status = status
+                state.updated_at = timestamp
+            
+            else:
+                raise Exception(f'Unknown action: {action}')
+
+            # Calculate summary stats
+            total_tasks = len(state.tasks)
+            completed_tasks = len([t for t in state.tasks if t.status == 'completed'])
+            in_progress_tasks = len([t for t in state.tasks if t.status == 'in_progress'])
+            pending_tasks = len([t for t in state.tasks if t.status == 'pending'])
+            cancelled_tasks = len([t for t in state.tasks if t.status == 'cancelled'])
+
+            # Convert state to dict for JSON serialization
+            state_dict = {
+                'plan_id': state.plan_id,
+                'title': state.title,
+                'description': state.description,
+                'tasks': [
+                    {
+                        'id': task.id,
+                        'title': task.title,
+                        'description': task.description,
+                        'status': task.status,
+                        'created_at': task.created_at,
+                        'updated_at': task.updated_at
+                    }
+                    for task in state.tasks
+                ],
+                'created_at': state.created_at,
+                'updated_at': state.updated_at,
+                'status': state.status
+            }
+
+            return {
+                'success': True,
+                'action': action,
+                'state': state_dict,
+                'summary': {
+                    'total_tasks': total_tasks,
+                    'completed_tasks': completed_tasks,
+                    'in_progress_tasks': in_progress_tasks,
+                    'pending_tasks': pending_tasks,
+                    'cancelled_tasks': cancelled_tasks,
+                    'progress_percentage': round((completed_tasks / total_tasks) * 100) if total_tasks > 0 else 0
+                },
+                'message': self._get_action_message(action, title, total_tasks, completed_tasks),
+                '_reminder': "IMPORTANT: Use this 'state' object as 'current_state' parameter in your next planner_tool call to maintain the same plan!"
+            }
+            
+        except Exception as e:
+            return {
+                'success': False,
+                'action': action,
+                'error': str(e),
+                'state': current_state
+            }
+
+    def get_dependencies(self) -> List[str]:
+        """Return list of dependencies"""
+        return []
+
+    def get_skill_info(self) -> Dict[str, Any]:
+        """Get comprehensive skill information"""
+        return {
+            "name": "PlannerSkill",
+            "description": "Simple task planning and todo management that matches TypeScript implementation",
+            "version": "3.0.0",
+            "capabilities": [
+                "Single plan state management",
+                "Task status tracking", 
+                "State persistence across calls",
+                "TypeScript compatibility"
+            ],
+            "tools": [
+                "planner_tool"
+            ]
+        }

webagents/agents/skills/ecosystem/crewai/__init__.py

@@ -0,0 +1 @@
+# TODO: Implement CrewAI skill

webagents/agents/skills/ecosystem/database/__init__.py

@@ -0,0 +1 @@
+# TODO: Implement Database skill

webagents/agents/skills/ecosystem/google/calendar/__init__.py

@@ -0,0 +1,6 @@
+from .skill import GoogleCalendarSkill
+
+__all__ = ["GoogleCalendarSkill"]
+
+
+

webagents/agents/skills/ecosystem/google/calendar/skill.py

@@ -0,0 +1,306 @@
+import os
+import json
+import urllib.parse
+from typing import Any, Dict, Optional, List
+from datetime import datetime, timezone
+
+import httpx
+
+from webagents.agents.skills.base import Skill
+from webagents.agents.tools.decorators import tool, prompt, http, hook
+from webagents.server.context.context_vars import get_context
+from webagents.utils.logging import get_logger, log_skill_event, log_tool_execution
+
+
+class GoogleCalendarSkill(Skill):
+    """Google Calendar integration for the dedicated agent r-google-calendar.
+
+    Flow:
+    - Other agents call tools on r-google-calendar and present an ownership assertion (X-Owner-Assertion).
+    - On first use per user, this skill returns an AuthSub-style consent URL for the user to authorize access.
+    - After consent, Google redirects to our callback endpoint; we exchange code for a token and persist it.
+    - Tokens are stored via the JSON storage skill as simple key-value entries for now.
+    - Subsequent calendar operations use the stored token.
+    """
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None) -> None:
+        super().__init__(config or {}, scope="all")
+        self.logger = None
+        self.oauth_client_id = os.getenv("GOOGLE_CLIENT_ID", "")
+        self.oauth_client_secret = os.getenv("GOOGLE_CLIENT_SECRET", "")
+        self.oauth_redirect_path = "/oauth/google/calendar/callback"
+        self.oauth_scopes = [
+            "https://www.googleapis.com/auth/calendar.readonly",
+            "https://www.googleapis.com/auth/calendar.events.readonly",
+        ]
+        # Base URL where this agent is exposed (needed to form redirect URI)
+        # Single source of truth: AGENTS_BASE_URL. It may be provided with or without trailing /agents.
+        # We normalize to always include exactly one /agents segment.
+        env_agents = os.getenv("AGENTS_BASE_URL")
+        base_root = (env_agents or "http://localhost:2224").rstrip('/')
+        if base_root.endswith("/agents"):
+            self.agent_base_url = base_root
+        else:
+            self.agent_base_url = base_root + "/agents"
+
+    async def initialize(self, agent) -> None:
+        self.agent = agent
+        self.logger = get_logger('skill.google.calendar', agent.name)
+        log_skill_event(agent.name, 'google_calendar', 'initialized', {})
+
+    # ---------------- Helpers ----------------
+    def _redirect_uri(self) -> str:
+        # e.g., http://localhost:8000/agents/{agent-name}/oauth/google/calendar/callback
+        base = self.agent_base_url.rstrip('/')
+        return f"{base}/{self.agent.name}{self.oauth_redirect_path}"
+
+    async def _get_kv_skill(self):
+        # Prefer dedicated KV skill if present; fallback to json_storage
+        return self.agent.skills.get("kv") or self.agent.skills.get("json_storage")
+
+    def _token_filename(self, user_id: str) -> str:
+        return f"gcal_tokens_{user_id}.json"
+
+    async def _save_user_tokens(self, user_id: str, tokens: Dict[str, Any]) -> None:
+        kv_skill = await self._get_kv_skill()
+        if kv_skill and hasattr(kv_skill, 'kv_set'):
+            try:
+                await kv_skill.kv_set(key=self._token_filename(user_id), value=json.dumps(tokens), namespace="auth")
+                return
+            except Exception:
+                pass
+        # Fallback: in-memory
+        setattr(self.agent, '_gcal_tokens', getattr(self.agent, '_gcal_tokens', {}))
+        self.agent._gcal_tokens[user_id] = tokens
+
+    async def _load_user_tokens(self, user_id: str) -> Optional[Dict[str, Any]]:
+        kv_skill = await self._get_kv_skill()
+        if kv_skill and hasattr(kv_skill, 'kv_get'):
+            try:
+                stored = await kv_skill.kv_get(key=self._token_filename(user_id), namespace="auth")
+                if isinstance(stored, str) and stored.startswith('{'):
+                    return json.loads(stored)
+            except Exception:
+                pass
+        mem = getattr(self.agent, '_gcal_tokens', {})
+        return mem.get(user_id)
+
+    def _build_auth_url(self, user_id: str) -> str:
+        q = {
+            "client_id": self.oauth_client_id,
+            "response_type": "code",
+            "redirect_uri": self._redirect_uri(),
+            "access_type": "offline",
+            "prompt": "consent",
+            "scope": " ".join(self.oauth_scopes),
+            # State can carry user id for correlation
+            "state": user_id,
+        }
+        return f"https://accounts.google.com/o/oauth2/v2/auth?{urllib.parse.urlencode(q)}"
+
+    async def _exchange_code_for_tokens(self, code: str) -> Dict[str, Any]:
+        token_url = "https://oauth2.googleapis.com/token"
+        payload = {
+            "client_id": self.oauth_client_id,
+            "client_secret": self.oauth_client_secret,
+            "code": code,
+            "grant_type": "authorization_code",
+            "redirect_uri": self._redirect_uri(),
+        }
+        headers = {"Content-Type": "application/x-www-form-urlencoded"}
+        async with httpx.AsyncClient(timeout=20) as client:
+            try:
+                resp = await client.post(token_url, data=payload, headers=headers)
+                resp.raise_for_status()
+                return resp.json()
+            except httpx.HTTPStatusError as e:
+                # Surface detailed Google error payload when available
+                detail = None
+                try:
+                    detail = e.response.json()
+                except Exception:
+                    try:
+                        detail = {"text": e.response.text}
+                    except Exception:
+                        detail = {"error": str(e)}
+                raise Exception(f"Google token exchange failed: status={e.response.status_code}, redirect_uri={payload['redirect_uri']}, detail={detail}")
+
+    async def _refresh_access_token(self, refresh_token: str) -> Dict[str, Any]:
+        token_url = "https://oauth2.googleapis.com/token"
+        payload = {
+            "client_id": self.oauth_client_id,
+            "client_secret": self.oauth_client_secret,
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+        }
+        headers = {"Content-Type": "application/x-www-form-urlencoded"}
+        async with httpx.AsyncClient(timeout=20) as client:
+            resp = await client.post(token_url, data=payload, headers=headers)
+            resp.raise_for_status()
+            return resp.json()
+
+    async def _get_user_id_from_context(self) -> Optional[str]:
+        try:
+            ctx = get_context()
+            if not ctx:
+                return None
+            auth = getattr(ctx, 'auth', None) or (ctx and ctx.get('auth'))
+            return getattr(auth, 'user_id', None)
+        except Exception:
+            return None
+
+    # ---------------- Prompts ----------------
+    @prompt(priority=40, scope=["owner", "all"])  # Visible to all for discoverability
+    def calendar_prompt(self) -> str:
+        return (
+            "Google Calendar skill is available. If calendar access is needed, call init_calendar_auth() to obtain an authorization link. "
+            "After the user authorizes, use list_events() to read calendar events."
+        )
+
+    # ---------------- HTTP callback handler ----------------
+    # Public callback: rely on state param and context-derived user id; no owner scope required
+    @http(subpath="/oauth/google/calendar/callback", method="get", scope=["all"])  # Accept from any caller; identity via state/context
+    async def oauth_callback(self, code: str = None, state: str = None) -> Dict[str, Any]:
+        from fastapi.responses import HTMLResponse
+        # Minimal HTML confirmation UI with brand-consistent styling (use Template to avoid brace issues)
+        def html(success: bool, message: str) -> str:
+            from string import Template
+            color_ok = "#16a34a"  # green-600
+            color_err = "#dc2626"  # red-600
+            accent = color_ok if success else color_err
+            title = "Calendar connected" if success else "Calendar connection failed"
+            # Basic HTML escape and escape $ for Template
+            safe_msg = (message or '')
+            safe_msg = safe_msg.replace('&','&amp;').replace('<','&lt;').replace('>','&gt;').replace('$','$$')
+            template = Template(
+                """<!doctype html>
+<html lang=\"en\">
+  <head>
+    <meta charset=\"utf-8\" />
+    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />
+    <title>WebAgents – Google Calendar</title>
+    <style>
+      :root { color-scheme: light dark; }
+      html, body { height: 100%; margin: 0; font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, "Apple Color Emoji", "Segoe UI Emoji"; }
+      body { background: var(--bg, #0b0b0c); color: var(--fg, #e5e7eb); display: grid; place-items: center; }
+      @media (prefers-color-scheme: light) { body { --bg: #f7f7f8; --card: #ffffff; --border: #e5e7eb; --fg: #0f172a; } }
+      @media (prefers-color-scheme: dark) { body { --bg: #0b0b0c; --card: #111214; --border: #23252a; --fg: #e5e7eb; } }
+      .card { background: var(--card); border: 1px solid var(--border); border-radius: 12px; padding: 24px 20px; width: min(92vw, 420px); box-shadow: 0 6px 24px rgba(0,0,0,.12); text-align: center; }
+      .icon { color: $accent; display:inline-flex; align-items:center; justify-content:center; margin-bottom: 12px; }
+      h1 { margin: 0 0 6px; font-size: 18px; font-weight: 600; color: var(--fg); }
+      p { margin: 0 0 16px; font-size: 13px; opacity: .78; line-height: 1.4; }
+      button { appearance: none; border: 1px solid var(--border); background: transparent; color: var(--fg); border-radius: 8px; padding: 8px 14px; font-size: 13px; cursor: pointer; }
+      button:hover { background: rgba(127,127,127,.12); }
+      .calendar { width: 44px; height: 44px; }
+    </style>
+  </head>
+  <body>
+    <div class=\"card\">
+      <div class=\"icon\">
+        <svg class=\"calendar\" viewBox=\"0 0 24 24\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">
+          <rect x=\"3\" y=\"4\" width=\"18\" height=\"17\" rx=\"3\" ry=\"3\" stroke=\"currentColor\" stroke-width=\"1.5\"/>
+          <path d=\"M3 8H21\" stroke=\"currentColor\" stroke-width=\"1.5\"/>
+          <rect x=\"7\" y=\"11\" width=\"4\" height=\"4\" fill=\"currentColor\" />
+        </svg>
+      </div>
+      <h1>$title</h1>
+      <p>$safe_msg</p>
+      <button id=\"ok\">OK</button>
+    </div>
+    <script>
+      (function(){
+        var payload = { type: 'google-calendar-connected', success: $postSuccess };
+        try {
+          if (window.opener && !window.opener.closed) { window.opener.postMessage(payload, '*'); }
+          else if (window.parent && window.parent !== window) { window.parent.postMessage(payload, '*'); }
+        } catch(e){}
+        var ok = document.getElementById('ok');
+        if (ok) ok.addEventListener('click', function(){
+          try { window.close(); } catch(e) {}
+          setTimeout(function(){ location.replace('about:blank'); }, 150);
+        });
+      })();
+    </script>
+  </body>
+ </html>
+                """
+            )
+            return template.safe_substitute(
+                title=title,
+                accent=accent,
+                safe_msg=safe_msg,
+                postSuccess=("true" if success else "false"),
+            )
+
+        if not code:
+            return HTMLResponse(content=html(False, "Missing authorization code. Please retry."), media_type="text/html")
+        if not self.oauth_client_id or not self.oauth_client_secret:
+            return HTMLResponse(content=html(False, "Server is missing Google OAuth credentials. Contact support."), media_type="text/html")
+        user_id = state or await self._get_user_id_from_context() or ""
+        try:
+            tokens = await self._exchange_code_for_tokens(code)
+            await self._save_user_tokens(user_id, tokens)
+            return HTMLResponse(content=html(True, "Your Google Calendar is now connected."), media_type="text/html")
+        except Exception as e:
+            return HTMLResponse(content=html(False, f"{str(e)}"), media_type="text/html")
+
+    # ---------------- Tools ----------------
+    # @tool(description="Initialize Google Calendar authorization. Returns a URL the user should open to grant access.")
+    # async def init_calendar_auth(self) -> str:
+    #     user_id = await self._get_user_id_from_context()
+    #     if not user_id:
+    #         return "❌ Unable to resolve user identity for authorization"
+    #     auth_url = self._build_auth_url(user_id)
+    #     log_tool_execution(self.agent.name, 'google_calendar.init_calendar_auth', 'success', {"user_id": user_id})
+    #     return f"Open this link to authorize access: {auth_url}"
+
+    @tool(description="Connects to Google calendar and lists upcoming calendar events.")
+    async def list_events(self, max_results: int = 10) -> str:
+        user_id = await self._get_user_id_from_context()
+        if not user_id:
+            return "❌ Missing user identity"
+        tokens = await self._load_user_tokens(user_id)
+        if not tokens or not tokens.get('access_token'):
+            auth_url = self._build_auth_url(user_id)
+            log_tool_execution(self.agent.name, 'google_calendar.init_calendar_auth', 'success', {"user_id": user_id})
+            return f"Open this link to authorize access: {auth_url}"
+            # return "❌ Not authorized. Call init_calendar_auth() first."
+        try:
+            access_token = tokens.get('access_token')
+            headers = {"Authorization": f"Bearer {access_token}"}
+            params = {
+                "maxResults": int(max_results),
+                "singleEvents": True,
+                "orderBy": "startTime",
+                "timeMin": datetime.now(timezone.utc).isoformat(),
+            }
+            async with httpx.AsyncClient(timeout=20) as client:
+                resp = await client.get("https://www.googleapis.com/calendar/v3/calendars/primary/events", headers=headers, params=params)
+                if resp.status_code == 401 and tokens.get('refresh_token'):
+                    refreshed = await self._refresh_access_token(tokens['refresh_token'])
+                    if 'access_token' in refreshed:
+                        tokens['access_token'] = refreshed['access_token']
+                        await self._save_user_tokens(user_id, tokens)
+                        headers = {"Authorization": f"Bearer {tokens['access_token']}"}
+                        resp = await client.get("https://www.googleapis.com/calendar/v3/calendars/primary/events", headers=headers, params=params)
+                if resp.status_code == 401:
+                    return "❌ Token expired or invalid. Re-run init_calendar_auth()."
+                if resp.status_code == 403:
+                    try:
+                        return f"❌ Permission error (403). Details: {resp.json()}"
+                    except Exception:
+                        return f"❌ Permission error (403)."
+                resp.raise_for_status()
+                data = resp.json()
+                items = data.get('items', [])
+                if not items:
+                    return "(no upcoming events)"
+                lines = []
+                for ev in items[: int(max_results)]:
+                    start = (ev.get('start') or {}).get('dateTime') or (ev.get('start') or {}).get('date') or 'unknown'
+                    lines.append(f"- {start} | {ev.get('summary', '(no title)')}")
+                return "\n".join(lines)
+        except Exception as e:
+            return f"❌ Failed to list events: {e}"
+
+