signalwire-agents 0.1.6__py3-none-any.whl → 0.1.8__py3-none-any.whl

signalwire_agents/core/security/session_manager.py

@@ -14,73 +14,92 @@ Session manager for handling call sessions and security tokens
 from typing import Dict, Any, Optional, Tuple
 import secrets
 import time
-from datetime import datetime
-
-
-class CallSession:
-    """
-    Represents a single call session with associated tokens and state
-    """
-    def __init__(self, call_id: str):
-        self.call_id = call_id
-        self.tokens: Dict[str, str] = {}  # function_name -> token
-        self.state = "pending"  # pending, active, expired
-        self.started_at = datetime.now()
-        self.metadata: Dict[str, Any] = {}  # Custom state for the call
+import hmac
+import hashlib
+import base64
+from datetime import datetime, timedelta
 
 
 class SessionManager:
     """
-    Manages call sessions and their associated security tokens
+    Manages security tokens for function calls
+    
+    This implementation is completely stateless - it does not track call sessions
+    or store any information in memory. All validation is done using cryptographic
+    signatures with the tokens containing all necessary information.
     """
-    def __init__(self, token_expiry_secs: int = 600):
+    def __init__(self, token_expiry_secs: int = 3600, secret_key: Optional[str] = None):
         """
         Initialize the session manager
         
         Args:
-            token_expiry_secs: Seconds until tokens expire (default: 10 minutes)
+            token_expiry_secs: Seconds until tokens expire (default: 60 minutes)
+            secret_key: Secret key for signing tokens (generated if not provided)
         """
-        self._active_calls: Dict[str, CallSession] = {}
         self.token_expiry_secs = token_expiry_secs
+        # Use provided secret key or generate a secure one
+        self.secret_key = secret_key or secrets.token_hex(32)
     
     def create_session(self, call_id: Optional[str] = None) -> str:
         """
-        Create a new call session
+        Create a new session ID if one isn't provided
         
         Args:
             call_id: Optional call ID, generated if not provided
             
         Returns:
-            The call_id for the new session
+            The call_id for the session
         """
         # Generate call_id if not provided
         if not call_id:
             call_id = secrets.token_urlsafe(16)
         
-        # Create new session
-        self._active_calls[call_id] = CallSession(call_id)
         return call_id
     
     def generate_token(self, function_name: str, call_id: str) -> str:
         """
-        Generate a secure token for a function call
+        Generate a secure self-contained token for a function call
         
         Args:
             function_name: Name of the function to generate a token for
             call_id: Call session ID
             
         Returns:
-            A secure random token
-            
-        Raises:
-            ValueError: If the call session does not exist
+            A secure token
         """
-        if call_id not in self._active_calls:
-            raise ValueError(f"No active session for call_id: {call_id}")
+        # Create token parts
+        expiry = int(time.time()) + self.token_expiry_secs
+        nonce = secrets.token_hex(4)
+        
+        # Create the message to sign
+        message = f"{call_id}:{function_name}:{expiry}:{nonce}"
+        
+        # Sign the message
+        signature = hmac.new(
+            self.secret_key.encode(),
+            message.encode(),
+            hashlib.sha256
+        ).hexdigest()[:16]  # Use first 16 chars of signature for shorter tokens
         
-        token = secrets.token_urlsafe(24)
-        self._active_calls[call_id].tokens[function_name] = token
-        return token
+        # Combine all parts into the token
+        token = f"{call_id}.{function_name}.{expiry}.{nonce}.{signature}"
+        
+        # Base64 encode for URL safety
+        return base64.urlsafe_b64encode(token.encode()).decode()
+    
+    # Alias for generate_token to maintain backward compatibility
+    def create_tool_token(self, function_name: str, call_id: str) -> str:
+        """
+        Alias for generate_token to maintain backward compatibility
+        
+        Args:
+            function_name: Name of the function to generate a token for
+            call_id: Call session ID
+            
+        Returns:
+            A secure token
+        """
+        return self.generate_token(function_name, call_id)
     
     def validate_token(self, call_id: str, function_name: str, token: str) -> bool:
         """
@@ -94,86 +113,155 @@ class SessionManager:
         Returns:
             True if valid, False otherwise
         """
-        session = self._active_calls.get(call_id)
-        if not session or session.state != "active":
-            return False
-        
-        # Check if token matches and is not expired
-        expected_token = session.tokens.get(function_name)
-        if not expected_token or expected_token != token:
-            return False
+        try:
+            # Decode the token
+            decoded_token = base64.urlsafe_b64decode(token.encode()).decode()
             
-        # Check expiry
-        now = datetime.now()
-        seconds_elapsed = (now - session.started_at).total_seconds()
-        if seconds_elapsed > self.token_expiry_secs:
-            session.state = "expired"
-            return False
+            # Split the token parts
+            parts = decoded_token.split('.')
+            if len(parts) != 5:
+                return False
+                
+            token_call_id, token_function, token_expiry, token_nonce, token_signature = parts
             
-        return True
+            # Special case: if call_id is None or empty, use the call_id from the token
+            # This helps with scenarios where the call_id isn't provided in the request
+            if not call_id:
+                call_id = token_call_id
+            
+            # Verify the function matches
+            if token_function != function_name:
+                return False
+                
+            # Check if the token has expired
+            expiry = int(token_expiry)
+            if expiry < time.time():
+                return False
+                
+            # Recreate the message and verify the signature
+            message = f"{token_call_id}:{token_function}:{token_expiry}:{token_nonce}"
+            expected_signature = hmac.new(
+                self.secret_key.encode(),
+                message.encode(),
+                hashlib.sha256
+            ).hexdigest()[:16]
+            
+            if token_signature != expected_signature:
+                return False
+                
+            # Finally, verify the call_id matches unless we're in special case
+            # This check is done last to ensure the token is otherwise valid
+            if token_call_id != call_id:
+                return False
+                
+            return True
+        except Exception:
+            # Any exception during validation means the token is invalid
+            return False
     
-    def activate_session(self, call_id: str) -> bool:
+    # Alias for validate_token to maintain backward compatibility
+    def validate_tool_token(self, function_name: str, token: str, call_id: str) -> bool:
         """
-        Activate a call session (called by startup_hook)
+        Alias for validate_token to maintain backward compatibility
         
         Args:
+            function_name: Name of the function being called
+            token: Token to validate
             call_id: Call session ID
             
         Returns:
-            True if successful, False otherwise
+            True if valid, False otherwise
+        """
+        # Reorder parameters to match validate_token signature (call_id first, then function_name)
+        return self.validate_token(call_id=call_id, function_name=function_name, token=token)
+    
+    # Legacy methods that now don't track state but provide API compatibility
+    
+    def activate_session(self, call_id: str) -> bool:
+        """
+        Legacy method, does nothing but returns success
         """
-        session = self._active_calls.get(call_id)
-        if not session:
-            return False
-            
-        session.state = "active"
         return True
     
     def end_session(self, call_id: str) -> bool:
         """
-        End a call session (called by hangup_hook)
-        
-        Args:
-            call_id: Call session ID
-            
-        Returns:
-            True if successful, False otherwise
+        Legacy method, does nothing but returns success
         """
-        if call_id in self._active_calls:
-            del self._active_calls[call_id]
-            return True
-        return False
+        return True
     
     def get_session_metadata(self, call_id: str) -> Optional[Dict[str, Any]]:
         """
-        Get custom metadata for a call session
-        
-        Args:
-            call_id: Call session ID
-            
-        Returns:
-            Metadata dict or None if session not found
+        Legacy method, always returns empty metadata
         """
-        session = self._active_calls.get(call_id)
-        if not session:
-            return None
-        return session.metadata
+        return {}
     
     def set_session_metadata(self, call_id: str, key: str, value: Any) -> bool:
         """
-        Set custom metadata for a call session
+        Legacy method, does nothing but returns success
+        """
+        return True
+    
+    def debug_token(self, token: str) -> Dict[str, Any]:
+        """
+        Debug a token without validating it
+        
+        This method decodes the token and extracts its components for debugging purposes
+        without performing validation.
         
         Args:
-            call_id: Call session ID
-            key: Metadata key
-            value: Metadata value
+            token: The token to debug
             
         Returns:
-            True if successful, False otherwise
+            Dictionary with token components and analysis
         """
-        session = self._active_calls.get(call_id)
-        if not session:
-            return False
+        try:
+            # Decode the token
+            decoded_token = base64.urlsafe_b64decode(token.encode()).decode()
             
-        session.metadata[key] = value
-        return True
+            # Split the token parts
+            parts = decoded_token.split('.')
+            if len(parts) != 5:
+                return {
+                    "valid_format": False,
+                    "parts_count": len(parts),
+                    "decoded": decoded_token
+                }
+                
+            token_call_id, token_function, token_expiry, token_nonce, token_signature = parts
+            
+            # Check expiration
+            current_time = int(time.time())
+            try:
+                expiry = int(token_expiry)
+                is_expired = expiry < current_time
+                expires_in = expiry - current_time if not is_expired else 0
+                expiry_date = datetime.fromtimestamp(expiry).isoformat()
+            except ValueError:
+                expiry = None
+                is_expired = None
+                expires_in = None
+                expiry_date = None
+            
+            return {
+                "valid_format": True,
+                "components": {
+                    "call_id": token_call_id,
+                    "function": token_function,
+                    "expiry": token_expiry,
+                    "expiry_date": expiry_date,
+                    "nonce": token_nonce,
+                    "signature": token_signature
+                },
+                "status": {
+                    "current_time": current_time,
+                    "is_expired": is_expired,
+                    "expires_in_seconds": expires_in
+                }
+            }
+        except Exception as e:
+            # Any exception during parsing
+            return {
+                "valid_format": False,
+                "error": str(e),
+                "token": token
+            }

signalwire_agents/core/swml_builder.py

@@ -14,7 +14,11 @@ This module provides a fluent builder API for creating SWML documents.
 It allows for chaining method calls to build up a document step by step.
 """
 
-from typing import Dict, List, Any, Optional, Union, Self, TypeVar
+from typing import Dict, List, Any, Optional, Union, TypeVar
+try:
+    from typing import Self  # Python 3.11+
+except ImportError:
+    from typing_extensions import Self  # For Python 3.9-3.10
 
 from signalwire_agents.core.swml_service import SWMLService
 

signalwire_agents/core/swml_service.py

@@ -565,58 +565,41 @@ class SWMLService:
     
     def as_router(self) -> APIRouter:
         """
-        Get a FastAPI router for this service
+        Create a FastAPI router for this service
         
         Returns:
-            FastAPI router
+            APIRouter: FastAPI router
         """
-        router = APIRouter()
+        router = APIRouter(redirect_slashes=False)
         
-        # Root endpoint - without trailing slash
-        @router.get("")
-        @router.post("")
-        async def handle_root_no_slash(request: Request, response: Response):
-            """Handle GET/POST requests to the root endpoint"""
-            return await self._handle_request(request, response)
-            
-        # Root endpoint - with trailing slash
+        # Root endpoint with and without trailing slash
         @router.get("/")
         @router.post("/")
-        async def handle_root_with_slash(request: Request, response: Response):
-            """Handle GET/POST requests to the root endpoint with trailing slash"""
+        async def handle_root(request: Request, response: Response):
+            """Handle requests to the root endpoint"""
             return await self._handle_request(request, response)
         
-        # Add endpoints for all registered routing callbacks
+        # Register routing callbacks as needed
         if hasattr(self, '_routing_callbacks') and self._routing_callbacks:
             for callback_path, callback_fn in self._routing_callbacks.items():
-                # Skip the root path as it's already handled
+                # Skip the root path which is already handled
                 if callback_path == "/":
                     continue
                     
-                # Register the endpoint without trailing slash
-                @router.get(callback_path)
-                @router.post(callback_path)
-                async def handle_callback_no_slash(request: Request, response: Response, cb_path=callback_path):
-                    """Handle GET/POST requests to a registered callback path"""
-                    # Store the callback path in request state for _handle_request to use
+                # Register both versions: with and without trailing slash
+                path = callback_path.rstrip("/")
+                path_with_slash = f"{path}/"
+                
+                @router.get(path)
+                @router.get(path_with_slash)
+                @router.post(path)
+                @router.post(path_with_slash)
+                async def handle_callback(request: Request, response: Response, cb_path=callback_path):
+                    """Handle requests to callback endpoints"""
+                    # Store the callback path in the request state
                     request.state.callback_path = cb_path
                     return await self._handle_request(request, response)
-                    
-                # Register the endpoint with trailing slash if it doesn't already have one
-                if not callback_path.endswith('/'):
-                    slash_path = f"{callback_path}/"
-                    
-                    @router.get(slash_path)
-                    @router.post(slash_path)
-                    async def handle_callback_with_slash(request: Request, response: Response, cb_path=callback_path):
-                        """Handle GET/POST requests to a registered callback path with trailing slash"""
-                        # Store the callback path in request state for _handle_request to use
-                        request.state.callback_path = cb_path
-                        return await self._handle_request(request, response)
-                        
-                self.log.info("callback_endpoint_registered", path=callback_path)
         
-        self._router = router
         return router
     
     def register_routing_callback(self, callback_fn: Callable[[Request, Dict[str, Any]], Optional[str]], 
@@ -789,20 +772,22 @@ class SWMLService:
         Start a web server for this service
         
         Args:
-            host: Optional host to override the default
-            port: Optional port to override the default
+            host: Host to bind to (defaults to self.host)
+            port: Port to bind to (defaults to self.port)
             ssl_cert: Path to SSL certificate file
-            ssl_key: Path to SSL private key file
-            ssl_enabled: Whether to enable SSL/HTTPS
-            domain: Domain name for the SSL certificate and external URLs
+            ssl_key: Path to SSL key file
+            ssl_enabled: Whether to enable SSL
+            domain: Domain name for SSL certificate
         """
         import uvicorn
         
-        # Determine SSL settings from parameters or environment variables
-        self.ssl_enabled = ssl_enabled if ssl_enabled is not None else os.environ.get('SWML_SSL_ENABLED', '').lower() in ('true', '1', 'yes')
-        ssl_cert_path = ssl_cert or os.environ.get('SWML_SSL_CERT_PATH', '')
-        ssl_key_path = ssl_key or os.environ.get('SWML_SSL_KEY_PATH', '')
-        self.domain = domain or os.environ.get('SWML_DOMAIN', '')
+        # Store SSL configuration
+        self.ssl_enabled = ssl_enabled if ssl_enabled is not None else False
+        self.domain = domain
+        
+        # Set SSL paths
+        ssl_cert_path = ssl_cert
+        ssl_key_path = ssl_key
         
         # Validate SSL configuration if enabled
         if self.ssl_enabled:
@@ -817,9 +802,64 @@ class SWMLService:
                 # We'll continue, but URLs might not be correctly generated
         
         if self._app is None:
-            app = FastAPI()
+            # Use redirect_slashes=False to be consistent with AgentBase
+            app = FastAPI(redirect_slashes=False)
             router = self.as_router()
-            app.include_router(router, prefix=self.route)
+            
+            # Normalize the route to ensure it starts with a slash and doesn't end with one
+            # This avoids the FastAPI error about prefixes ending with slashes
+            normalized_route = "/" + self.route.strip("/")
+            
+            # Include router with the normalized prefix
+            app.include_router(router, prefix=normalized_route)
+            
+            # Add a catch-all route handler that will handle both /path and /path/ formats
+            # This provides the same behavior without using a trailing slash in the prefix
+            @app.get("/{full_path:path}")
+            @app.post("/{full_path:path}")
+            async def handle_all_routes(request: Request, response: Response, full_path: str):
+                # Get our route path without leading slash for comparison
+                route_path = normalized_route.lstrip("/")
+                route_with_slash = route_path + "/"
+                
+                # Log the incoming path for debugging
+                print(f"Catch-all received: '{full_path}', route: '{route_path}'")
+                
+                # Check for exact match to our route (without trailing slash)
+                if full_path == route_path:
+                    # This is our exact route - handle it directly
+                    return await self._handle_request(request, response)
+                    
+                # Check for our route with a trailing slash or subpaths
+                elif full_path == route_with_slash or full_path.startswith(route_with_slash):
+                    # This is our route with a trailing slash
+                    # Extract the path after our route prefix
+                    sub_path = full_path[len(route_with_slash):]
+                    
+                    # Forward to the appropriate handler in our router
+                    if not sub_path:
+                        # Root endpoint
+                        return await self._handle_request(request, response)
+                    
+                    # Check for routing callbacks if there are any
+                    if hasattr(self, '_routing_callbacks'):
+                        for callback_path, callback_fn in self._routing_callbacks.items():
+                            cb_path_clean = callback_path.strip("/")
+                            if sub_path == cb_path_clean or sub_path.startswith(cb_path_clean + "/"):
+                                # Store the callback path in request state for handlers to use
+                                request.state.callback_path = callback_path
+                                return await self._handle_request(request, response)
+                
+                # Not our route or not matching our patterns
+                print(f"No match for path: '{full_path}'")
+                return {"error": "Path not found"}
+            
+            # Print all routes for debugging
+            print(f"All routes for {self.name}:")
+            for route in app.routes:
+                if hasattr(route, "path"):
+                    print(f"  {route.path}")
+            
             self._app = app
         
         host = host or self.host
@@ -840,13 +880,14 @@ class SWMLService:
         
         print(f"Service '{self.name}' is available at:")
         print(f"URL: {protocol}://{display_host}{self.route}")
+        print(f"URL with trailing slash: {protocol}://{display_host}{self.route}/")
         print(f"Basic Auth: {username}:{password}")
         
         # Check if SIP routing is enabled and print additional info
         if self._routing_callbacks:
             print(f"Callback endpoints:")
             for path in self._routing_callbacks:
-                print(f"{protocol}://{display_host}{path}")
+                print(f"{protocol}://{display_host}{self.route}{path}")
         
         # Start uvicorn with or without SSL
         if self.ssl_enabled and ssl_cert_path and ssl_key_path:

signalwire_agents/prefabs/concierge.py

@@ -50,6 +50,9 @@ class ConciergeAgent(AgentBase):
         hours_of_operation: Optional[Dict[str, str]] = None,
         special_instructions: Optional[List[str]] = None,
         welcome_message: Optional[str] = None,
+        name: str = "concierge",
+        route: str = "/concierge",
+        enable_state_tracking: bool = True,
         **kwargs
     ):
         """
@@ -62,13 +65,17 @@ class ConciergeAgent(AgentBase):
             hours_of_operation: Optional dictionary of operating hours
             special_instructions: Optional list of special instructions
             welcome_message: Optional custom welcome message
+            name: Agent name for the route
+            route: HTTP route for this agent
+            enable_state_tracking: Whether to enable state tracking (default: True)
             **kwargs: Additional arguments for AgentBase
         """
         # Initialize the base agent
         super().__init__(
-            name="concierge",
-            route="/concierge",
+            name=name,
+            route=route,
             use_pom=True,
+            enable_state_tracking=enable_state_tracking,
             **kwargs
         )
         

signalwire_agents/prefabs/faq_bot.py

@@ -51,6 +51,7 @@ class FAQBotAgent(AgentBase):
         persona: Optional[str] = None,
         name: str = "faq_bot",
         route: str = "/faq",
+        enable_state_tracking: bool = True,  # Enable state tracking by default
         **kwargs
     ):
         """
@@ -65,6 +66,7 @@ class FAQBotAgent(AgentBase):
             persona: Optional custom personality description
             name: Agent name for the route
             route: HTTP route for this agent
+            enable_state_tracking: Whether to enable state tracking (default: True)
             **kwargs: Additional arguments for AgentBase
         """
         # Initialize the base agent
@@ -72,6 +74,7 @@ class FAQBotAgent(AgentBase):
             name=name,
             route=route,
             use_pom=True,
+            enable_state_tracking=enable_state_tracking,  # Pass state tracking parameter to base
             **kwargs
         )