webagents 0.1.0__py3-none-any.whl

webagents/agents/skills/robutler/notifications/__init__.py

@@ -0,0 +1,5 @@
+from .skill import NotificationsSkill
+
+__all__ = ["NotificationsSkill"]
+
+

webagents/agents/skills/robutler/notifications/skill.py

@@ -0,0 +1,141 @@
+import os
+from typing import Any, Dict, Optional, List
+
+import httpx
+
+from webagents.agents.skills.base import Skill
+from webagents.agents.tools.decorators import tool, prompt
+from webagents.server.context.context_vars import get_context
+from webagents.utils.logging import get_logger, log_skill_event, log_tool_execution
+
+
+def _resolve_portal_url() -> str:
+    return os.getenv("ROBUTLER_INTERNAL_API_URL") or os.getenv("ROBUTLER_API_URL", "http://localhost:3000")
+
+
+class NotificationsSkill(Skill):
+    """Send push notifications to the owner of this agent (owner-only).
+
+    This skill exposes a single owner-scoped tool that sends a push notification via the
+    portal notifications API (POST /api/notifications/send). The notification will be
+    targeted to this agent's owner user ID.
+    """
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None) -> None:
+        # Align with other skills (e.g., VectorMemorySkill) for consistent SDK behavior
+        super().__init__(config or {}, scope="all")
+        self.config = config or {}
+        self.logger = None
+
+    async def initialize(self, agent) -> None:
+        self.agent = agent
+        self.logger = get_logger('skill.notifications', agent.name)
+        # Log level is configured globally via setup_logging()
+        log_skill_event(agent.name, 'notifications', 'initialized', {})
+        # Cache agent API key for later use
+        try:
+            self.agent_api_key: Optional[str] = getattr(agent, 'api_key', None)
+        except Exception:
+            self.agent_api_key = None
+
+    @prompt(priority=60, scope=["owner"])  # Owner sees how to use it
+    def get_notifications_prompt(self) -> str:
+        return (
+            "You can use send_notification(title, body, tag?, type?, priority?, requireInteraction?, silent?, ttl?) to send a push notifications to the owner of this agent. Use it only when explicitly asked to do so."
+        )
+
+    def _get_owner_user_id(self) -> Optional[str]:
+        # Prefer agent metadata set by factory
+        try:
+            owner_id = getattr(self.agent, 'owner_user_id', None)
+            if owner_id:
+                return owner_id
+        except Exception:
+            pass
+        # Fallback to auth context if available
+        try:
+            ctx = get_context()
+            auth_ctx = getattr(ctx, 'auth', None) or (ctx and ctx.get('auth'))
+            if auth_ctx and getattr(auth_ctx, 'scope', '').upper() == 'OWNER':
+                # Not strictly the owner ID, but if missing we skip
+                return getattr(auth_ctx, 'user_id', None)
+        except Exception:
+            pass
+        return None
+
+    async def _post_notification(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        base_url = _resolve_portal_url()
+        url = f"{base_url}/api/notifications/send"
+        headers = {
+            'Content-Type': 'application/json'
+        }
+        # Use agent API key only (no service tokens here)
+        api_key = getattr(self, 'agent_api_key', None) or getattr(self.agent, 'api_key', None)
+        if not api_key:
+            raise RuntimeError("Agent API key unavailable for notifications")
+        headers['X-API-Key'] = api_key
+
+        async with httpx.AsyncClient(timeout=20) as client:
+            resp = await client.post(url, json=payload, headers=headers)
+            try:
+                data = resp.json()
+            except Exception:
+                data = {'status': resp.status_code, 'text': resp.text}
+            if resp.status_code >= 400:
+                raise RuntimeError(f"Notification send failed: {resp.status_code} {data}")
+            return data
+
+    @tool(
+        name="send_notification",
+        description=(
+            "Send a push notification. "
+            "Parameters: title (string), body (string). Optional: tag (string), type (chat_message|agent_update|system_announcement|marketing), "
+            "priority (low|normal|high|urgent), requireInteraction (bool), silent (bool), ttl (seconds)."
+        ),
+        scope="owner",
+    )
+    async def send_notification(
+        self,
+        title: str,
+        body: str,
+        tag: Optional[str] = None,
+        type: Optional[str] = "agent_update",
+        priority: Optional[str] = "normal",
+        requireInteraction: Optional[bool] = False,
+        silent: Optional[bool] = False,
+        ttl: Optional[int] = 86400,
+        context: Any = None,
+    ) -> str:
+        owner_id = self._get_owner_user_id()
+        if not owner_id:
+            return "❌ Cannot resolve agent owner user ID"
+
+        payload: Dict[str, Any] = {
+            'title': title,
+            'body': body,
+            'type': type or 'agent_update',
+            'priority': priority or 'normal',
+            'userIds': [owner_id],
+            'requireInteraction': bool(requireInteraction),
+            'silent': bool(silent),
+            'ttl': int(ttl or 86400),
+        }
+        if tag:
+            payload['tag'] = tag
+
+        # Call API
+        try:
+            result = await self._post_notification(payload)
+            log_tool_execution(self.agent.name, 'notifications.send_notification', 'success', {
+                'owner_id': owner_id,
+                'title': title[:50]
+            })
+            return f"✅ Notification queued: {result.get('message', 'ok')}"
+        except Exception as e:
+            log_tool_execution(self.agent.name, 'notifications.send_notification', 'failure', {
+                'owner_id': owner_id,
+                'error': str(e)
+            })
+            return f"❌ Failed to send notification: {e}"
+
+

webagents/agents/skills/robutler/payments/__init__.py

@@ -0,0 +1,41 @@
+"""
+PaymentSkill Package - WebAgents V2.0
+
+Payment processing and billing skill for WebAgents platform.
+Validates payment tokens, calculates costs using LiteLLM, and charges on connection finalization.
+Based on webagents_v1 implementation patterns.
+"""
+
+from .skill import PaymentSkill, PaymentContext, PricingInfo, pricing
+from .exceptions import (
+    PaymentError,
+    PaymentTokenRequiredError,
+    PaymentTokenInvalidError,
+    InsufficientBalanceError,
+    PaymentChargingError,
+    PaymentPlatformUnavailableError,
+    PaymentConfigurationError,
+    # Legacy compatibility
+    PaymentValidationError,
+    PaymentRequiredError
+)
+
+__all__ = [
+    # Main classes
+    "PaymentSkill", 
+    "PaymentContext",
+    # Pricing decorators
+    "PricingInfo",
+    "pricing",
+    # New comprehensive error hierarchy
+    "PaymentError",
+    "PaymentTokenRequiredError",
+    "PaymentTokenInvalidError",
+    "InsufficientBalanceError",
+    "PaymentChargingError",
+    "PaymentPlatformUnavailableError",
+    "PaymentConfigurationError",
+    # Legacy compatibility
+    "PaymentValidationError",
+    "PaymentRequiredError"
+]

webagents/agents/skills/robutler/payments/exceptions.py

@@ -0,0 +1,255 @@
+"""
+Payment Exceptions - WebAgents V2.0 Platform Integration
+
+Comprehensive payment error hierarchy for distinguishing between different 402 payment failure scenarios.
+Provides specific error codes, subcodes, and context for better error handling and user experience.
+"""
+
+from typing import Dict, Any, Optional
+from decimal import Decimal
+
+
+class PaymentError(Exception):
+    """Base payment error with 402 status code and detailed context"""
+    
+    def __init__(self, 
+                 message: str,
+                 error_code: str,
+                 subcode: Optional[str] = None,
+                 context: Optional[Dict[str, Any]] = None,
+                 user_message: Optional[str] = None):
+        super().__init__(message)
+        self.status_code = 402  # Payment Required
+        self.error_code = error_code
+        self.subcode = subcode
+        self.context = context or {}
+        self.user_message = user_message or message
+        
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert error to dictionary for API responses"""
+        return {
+            'error': self.error_code,
+            'subcode': self.subcode,
+            'message': str(self),
+            'user_message': self.user_message,
+            'status_code': self.status_code,
+            'context': self.context
+        }
+    
+    def __str__(self) -> str:
+        parts = [self.error_code]
+        if self.subcode:
+            parts.append(f"({self.subcode})")
+        parts.append(f": {super().__str__()}")
+        return " ".join(parts)
+
+    # FastAPI/Starlette HTTPException expects a `detail` field for structured errors.
+    # Our server checks for `hasattr(e, 'status_code') and hasattr(e, 'detail')` to
+    # map domain errors to HTTP responses. Expose detail dynamically from to_dict().
+    @property
+    def detail(self) -> Dict[str, Any]:
+        return self.to_dict()
+
+
+class PaymentTokenRequiredError(PaymentError):
+    """Raised when payment token is required but not provided"""
+    
+    def __init__(self, agent_name: Optional[str] = None):
+        context = {}
+        if agent_name:
+            context['agent_name'] = agent_name
+            
+        super().__init__(
+            message="Payment token required for billing-enabled agent",
+            error_code="PAYMENT_TOKEN_REQUIRED",
+            context=context,
+            user_message="This agent requires payment. Please provide a valid payment token."
+        )
+
+
+class PaymentTokenInvalidError(PaymentError):
+    """Raised when payment token is invalid or expired"""
+    
+    def __init__(self, 
+                 token_prefix: Optional[str] = None,
+                 reason: Optional[str] = None):
+        context = {}
+        if token_prefix:
+            context['token_prefix'] = token_prefix
+        if reason:
+            context['validation_error'] = reason
+            
+        subcode = None
+        user_message = "Payment token is invalid or expired. Please check your token and try again."
+        
+        if reason:
+            if "expired" in reason.lower():
+                subcode = "TOKEN_EXPIRED"
+                user_message = "Payment token has expired. Please obtain a new token."
+            elif "not found" in reason.lower():
+                subcode = "TOKEN_NOT_FOUND"
+                user_message = "Payment token not found. Please check your token and try again."
+            elif "malformed" in reason.lower():
+                subcode = "TOKEN_MALFORMED"
+                user_message = "Payment token format is invalid. Please check your token."
+            
+        super().__init__(
+            message=f"Payment token validation failed: {reason}" if reason else "Payment token is invalid",
+            error_code="PAYMENT_TOKEN_INVALID",
+            subcode=subcode,
+            context=context,
+            user_message=user_message
+        )
+
+
+class InsufficientBalanceError(PaymentError):
+    """Raised when payment token balance is insufficient"""
+    
+    def __init__(self, 
+                 current_balance: float,
+                 required_balance: float,
+                 token_prefix: Optional[str] = None):
+        context = {
+            'current_balance': current_balance,
+            'required_balance': required_balance,
+            'shortfall': required_balance - current_balance
+        }
+        if token_prefix:
+            context['token_prefix'] = token_prefix
+            
+        super().__init__(
+            message=f"Insufficient balance: ${current_balance:.2f} < ${required_balance:.2f} required",
+            error_code="INSUFFICIENT_BALANCE",
+            context=context,
+            user_message=f"Insufficient credits. You have ${current_balance:.2f} but need ${required_balance:.2f}. Please add more credits to your account."
+        )
+
+
+class PaymentChargingError(PaymentError):
+    """Raised when charging/redeeming payment token fails"""
+    
+    def __init__(self, 
+                 amount: float,
+                 token_prefix: Optional[str] = None,
+                 reason: Optional[str] = None):
+        context = {
+            'charge_amount': amount
+        }
+        if token_prefix:
+            context['token_prefix'] = token_prefix
+        if reason:
+            context['charge_error'] = reason
+            
+        subcode = None
+        user_message = "Payment processing failed. Please try again or contact support."
+        
+        if reason:
+            if "insufficient" in reason.lower():
+                subcode = "INSUFFICIENT_FUNDS"
+                user_message = "Insufficient funds for this transaction. Please add more credits."
+            elif "expired" in reason.lower():
+                subcode = "TOKEN_EXPIRED_DURING_CHARGE"
+                user_message = "Payment token expired during transaction. Please obtain a new token."
+            elif "limit" in reason.lower():
+                subcode = "SPENDING_LIMIT_EXCEEDED"
+                user_message = "Spending limit exceeded. Please check your account limits."
+                
+        super().__init__(
+            message=f"Payment charging failed: {reason}" if reason else f"Failed to charge ${amount:.2f}",
+            error_code="PAYMENT_CHARGING_FAILED",
+            subcode=subcode,
+            context=context,
+            user_message=user_message
+        )
+
+
+class PaymentPlatformUnavailableError(PaymentError):
+    """Raised when payment platform is unavailable"""
+    
+    def __init__(self, operation: Optional[str] = None):
+        context = {}
+        if operation:
+            context['attempted_operation'] = operation
+            
+        super().__init__(
+            message=f"Payment platform unavailable for {operation}" if operation else "Payment platform unavailable",
+            error_code="PAYMENT_PLATFORM_UNAVAILABLE",
+            context=context,
+            user_message="Payment system is temporarily unavailable. Please try again later."
+        )
+
+
+class PaymentConfigurationError(PaymentError):
+    """Raised when payment configuration is invalid"""
+    
+    def __init__(self, 
+                 config_issue: str,
+                 details: Optional[str] = None):
+        context = {
+            'config_issue': config_issue
+        }
+        if details:
+            context['details'] = details
+            
+        super().__init__(
+            message=f"Payment configuration error: {config_issue}",
+            error_code="PAYMENT_CONFIG_ERROR",
+            context=context,
+            user_message="Payment system configuration error. Please contact support."
+        )
+
+
+# Convenience functions for common error scenarios
+def create_token_required_error(agent_name: Optional[str] = None) -> PaymentTokenRequiredError:
+    """Create a payment token required error"""
+    return PaymentTokenRequiredError(agent_name=agent_name)
+
+
+def create_token_invalid_error(token_prefix: Optional[str] = None, 
+                              reason: Optional[str] = None) -> PaymentTokenInvalidError:
+    """Create a payment token invalid error"""
+    return PaymentTokenInvalidError(token_prefix=token_prefix, reason=reason)
+
+
+def create_insufficient_balance_error(current_balance: float,
+                                    required_balance: float,
+                                    token_prefix: Optional[str] = None) -> InsufficientBalanceError:
+    """Create an insufficient balance error"""
+    return InsufficientBalanceError(
+        current_balance=current_balance,
+        required_balance=required_balance,
+        token_prefix=token_prefix
+    )
+
+
+def create_charging_error(amount: float,
+                         token_prefix: Optional[str] = None,
+                         reason: Optional[str] = None) -> PaymentChargingError:
+    """Create a payment charging error"""
+    return PaymentChargingError(
+        amount=amount,
+        token_prefix=token_prefix,
+        reason=reason
+    )
+
+
+def create_platform_unavailable_error(operation: Optional[str] = None) -> PaymentPlatformUnavailableError:
+    """Create a payment platform unavailable error"""
+    return PaymentPlatformUnavailableError(operation=operation)
+
+
+def create_config_error(config_issue: str,
+                       details: Optional[str] = None) -> PaymentConfigurationError:
+    """Create a payment configuration error"""
+    return PaymentConfigurationError(config_issue=config_issue, details=details)
+
+
+# Legacy compatibility - keep existing exception names but inherit from new hierarchy
+class PaymentValidationError(PaymentTokenInvalidError):
+    """Legacy compatibility - use PaymentTokenInvalidError instead"""
+    pass
+
+
+class PaymentRequiredError(PaymentTokenRequiredError):
+    """Legacy compatibility - use PaymentTokenRequiredError instead"""
+    pass