solace-agent-mesh 1.5.1__py3-none-any.whl → 1.6.1__py3-none-any.whl

solace_agent_mesh/common/sac/sam_component_base.py

@@ -6,7 +6,8 @@ import logging
 import abc
 import asyncio
 import threading
-from typing import Any
+import functools
+from typing import Any, Optional
 
 from solace_ai_connector.components.component_base import ComponentBase
 
@@ -15,6 +16,7 @@ from ..utils.message_utils import validate_message_size
 
 log = logging.getLogger(__name__)
 
+
 class SamComponentBase(ComponentBase, abc.ABC):
     """
     Abstract base class for high-level SAM components (Agents, Gateways).
@@ -54,8 +56,294 @@ class SamComponentBase(ComponentBase, abc.ABC):
 
         self._async_loop: asyncio.AbstractEventLoop | None = None
         self._async_thread: threading.Thread | None = None
+
+        # Timer callback registry
+        self._timer_callbacks: dict[str, Any] = {}
+        self._timer_callbacks_lock = threading.Lock()
+
+        # Trust Manager integration (enterprise feature) - initialized as part of _late_init
+        self.trust_manager: Optional[Any] = None
+
         log.info("%s SamComponentBase initialized successfully.", self.log_identifier)
 
+    def add_timer(
+        self,
+        delay_ms: int,
+        timer_id: str,
+        interval_ms: int = 0,
+        callback: Optional[Any] = None,
+    ):
+        """
+        Add a timer with optional callback.
+
+        Args:
+            delay_ms: Initial delay in milliseconds
+            timer_id: Unique timer identifier
+            interval_ms: Repeat interval in milliseconds (0 for one-shot)
+            callback: Optional callback function to invoke when timer fires.
+                     If provided, callback will be invoked when timer event occurs.
+                     Callback receives timer_data dict as argument.
+                     Callback should be thread-safe or schedule work appropriately.
+        """
+        # Register callback if provided
+        if callback:
+            with self._timer_callbacks_lock:
+                if timer_id in self._timer_callbacks:
+                    log.warning(
+                        "%s Timer ID '%s' already has a registered callback. Overwriting.",
+                        self.log_identifier,
+                        timer_id,
+                    )
+                self._timer_callbacks[timer_id] = callback
+                log.debug(
+                    "%s Registered callback for timer: %s",
+                    self.log_identifier,
+                    timer_id,
+                )
+
+        # Call parent implementation to actually create the timer
+        super().add_timer(delay_ms=delay_ms, timer_id=timer_id, interval_ms=interval_ms)
+
+    def cancel_timer(self, timer_id: str):
+        """
+        Cancel a timer and remove its callback if registered.
+
+        Args:
+            timer_id: Timer identifier to cancel
+        """
+        # Remove callback registration
+        with self._timer_callbacks_lock:
+            if timer_id in self._timer_callbacks:
+                del self._timer_callbacks[timer_id]
+                log.debug(
+                    "%s Unregistered callback for timer: %s",
+                    self.log_identifier,
+                    timer_id,
+                )
+
+        # Call parent implementation to actually cancel the timer
+        super().cancel_timer(timer_id)
+
+    def process_event(self, event):
+        """
+        Process incoming events by routing to appropriate handlers.
+
+        This base implementation handles MESSAGE and TIMER events:
+        - MESSAGE events are routed to _handle_message() abstract method
+        - TIMER events are routed to registered callbacks
+        - Other events are passed to parent class
+
+        Args:
+            event: Event object from SAC framework
+        """
+        from solace_ai_connector.common.event import Event, EventType
+        from solace_ai_connector.common.message import Message as SolaceMessage
+
+        if event.event_type == EventType.MESSAGE:
+            message: SolaceMessage = event.data
+            topic = message.get_topic()
+
+            if not topic:
+                log.warning(
+                    "%s Received message without topic. Ignoring.",
+                    self.log_identifier,
+                )
+                try:
+                    message.call_negative_acknowledgements()
+                except Exception as nack_e:
+                    log.error(
+                        "%s Failed to NACK message without topic: %s",
+                        self.log_identifier,
+                        nack_e,
+                    )
+                return
+
+            try:
+                # Delegate to abstract method implemented by subclass
+                self._handle_message(message, topic)
+            except Exception as e:
+                log.error(
+                    "%s Error in _handle_message for topic %s: %s",
+                    self.log_identifier,
+                    topic,
+                    e,
+                    exc_info=True,
+                )
+                try:
+                    message.call_negative_acknowledgements()
+                except Exception as nack_e:
+                    log.error(
+                        "%s Failed to NACK message after error: %s",
+                        self.log_identifier,
+                        nack_e,
+                    )
+                self.handle_error(e, event)
+
+        elif event.event_type == EventType.TIMER:
+            # Handle timer events via callback registry
+            timer_data = event.data
+            timer_id = timer_data.get("timer_id")
+
+            if not timer_id:
+                log.warning(
+                    "%s Timer event missing timer_id: %s",
+                    self.log_identifier,
+                    timer_data,
+                )
+                return
+
+            # Look up registered callback
+            with self._timer_callbacks_lock:
+                callback = self._timer_callbacks.get(timer_id)
+
+            if callback:
+                try:
+                    log.debug(
+                        "%s Invoking registered callback for timer: %s",
+                        self.log_identifier,
+                        timer_id,
+                    )
+                    callback(timer_data)
+                except Exception as e:
+                    log.error(
+                        "%s Error in timer callback for %s: %s",
+                        self.log_identifier,
+                        timer_id,
+                        e,
+                        exc_info=True,
+                    )
+            else:
+                log.warning(
+                    "%s No callback registered for timer: %s. Timer event ignored.",
+                    self.log_identifier,
+                    timer_id,
+                )
+        else:
+            # Pass other event types to parent class
+            super().process_event(event)
+
+    def _handle_message(self, message, topic: str) -> None:
+        """
+        Handle an incoming message by routing to async handler.
+
+        This base implementation schedules async processing on the component's
+        event loop. Subclasses can override this for custom sync handling,
+        or implement _handle_message_async() for async handling.
+
+        Args:
+            message: The Solace message (SolaceMessage instance)
+            topic: The topic the message was received on
+        """
+        loop = self.get_async_loop()
+        if loop and loop.is_running():
+            # Schedule async processing
+            coro = self._handle_message_async(message, topic)
+            future = asyncio.run_coroutine_threadsafe(coro, loop)
+            future.add_done_callback(
+                functools.partial(self._handle_async_message_completion, topic=topic)
+            )
+        else:
+            log.error(
+                "%s Async loop not available. Cannot process message on topic: %s",
+                self.log_identifier,
+                topic,
+            )
+            raise RuntimeError("Async loop not available for message processing")
+
+    def _handle_async_message_completion(self, future: asyncio.Future, topic: str):
+        """Callback to handle completion of async message processing."""
+        try:
+            if future.cancelled():
+                log.warning(
+                    "%s Message processing for topic %s was cancelled.",
+                    self.log_identifier,
+                    topic,
+                )
+            elif future.done():
+                exception = future.exception()
+                if exception is not None:
+                    log.error(
+                        "%s Message processing for topic %s failed: %s",
+                        self.log_identifier,
+                        topic,
+                        exception,
+                        exc_info=exception,
+                    )
+                else:
+                    # Handle successful completion
+                    try:
+                        _ = future.result()
+                        log.debug(
+                            "%s Message processing for topic %s completed successfully.",
+                            self.log_identifier,
+                            topic,
+                        )
+                        # Optional: Process the result if needed
+                        # self._process_successful_result(result, topic)
+                    except Exception as result_exception:
+                        # This catches exceptions that might occur when getting the result
+                        log.error(
+                            "%s Error retrieving result for topic %s: %s",
+                            self.log_identifier,
+                            topic,
+                            result_exception,
+                            exc_info=result_exception,
+                        )
+            else:
+                # This case shouldn't normally occur in a completion callback,
+                # but it's good defensive programming
+                log.warning(
+                    "%s Future for topic %s is not done in completion handler.",
+                    self.log_identifier,
+                    topic,
+                )
+        except Exception as e:
+            log.error(
+                "%s Error in async message completion handler for topic %s: %s",
+                self.log_identifier,
+                topic,
+                e,
+                exc_info=True,
+            )
+
+    @abc.abstractmethod
+    async def _handle_message_async(self, message, topic: str) -> None:
+        """
+        Async handler for incoming messages.
+
+        Subclasses must implement this to process messages asynchronously.
+        This runs on the component's dedicated async event loop.
+
+        Args:
+            message: The Solace message (SolaceMessage instance)
+            topic: The topic the message was received on
+        """
+        pass
+
+    def _late_init(self):
+        """Late initialization hook called after the component is fully set up."""
+
+        # Setup the Trust Manager if present (enterprise feature)
+        # NOTE: The Trust Manager should use component.get_broker_username() to retrieve
+        # the actual broker client-username for trust card topic construction. This is
+        # critical because trust cards MUST be published on topics that match the actual
+        # authentication identity (client-username) used to connect to the broker.
+        try:
+            from solace_agent_mesh_enterprise.common.trust import (
+                initialize_trust_manager,
+            )
+
+            trust_config = self.get_config("trust_manager")
+            if trust_config and trust_config.get("enabled", False):
+                self.trust_manager = initialize_trust_manager(self)
+                log.info("%s Enterprise Trust Manager initialized", self.log_identifier)
+        except ImportError:
+            log.debug("%s Enterprise Trust Manager not available", self.log_identifier)
+        except Exception as e:
+            log.error(
+                "%s Failed to initialize Trust Manager: %s", self.log_identifier, e
+            )
+
     def publish_a2a_message(
         self, payload: dict, topic: str, user_properties: dict | None = None
     ):
@@ -197,6 +485,10 @@ class SamComponentBase(ComponentBase, abc.ABC):
     def run(self):
         """Starts the component's dedicated async thread."""
         log.info("%s Starting SamComponentBase run method.", self.log_identifier)
+
+        # Do all initialization that needs to be done after we are fully setup
+        self._late_init()
+
         if not self._async_thread or not self._async_thread.is_alive():
             self._async_thread = threading.Thread(
                 target=self._run_async_operations,
@@ -256,14 +548,101 @@ class SamComponentBase(ComponentBase, abc.ABC):
         """Returns the dedicated asyncio event loop for this component's async tasks."""
         return self._async_loop
 
+    def get_broker_username(self) -> Optional[str]:
+        """
+        Returns the broker username (client-username) that this component uses
+        to authenticate with the Solace broker.
+
+        This is critical for trust card publishing and verification, as the
+        trust card topic must match the actual authentication identity.
+
+        Returns:
+            The broker username if available, None otherwise.
+        """
+        try:
+            app = self.get_app()
+            if app and hasattr(app, "app_info"):
+                broker_config = app.app_info.get("broker", {})
+                broker_username = broker_config.get("broker_username")
+                if broker_username:
+                    log.debug(
+                        "%s Retrieved broker username: %s",
+                        self.log_identifier,
+                        broker_username,
+                    )
+                    return broker_username
+                else:
+                    log.warning(
+                        "%s Broker username not found in broker configuration",
+                        self.log_identifier,
+                    )
+            else:
+                log.warning(
+                    "%s Unable to access app or app_info to retrieve broker username",
+                    self.log_identifier,
+                )
+        except Exception as e:
+            log.error(
+                "%s Error retrieving broker username: %s",
+                self.log_identifier,
+                e,
+                exc_info=True,
+            )
+        return None
+
     @abc.abstractmethod
-    async def _async_setup_and_run(self) -> None:
+    def _get_component_id(self) -> str:
+        """
+        Returns unique identifier for this component instance.
+        Must be implemented by subclasses.
+
+        Returns:
+            Unique component identifier (e.g., agent_name, gateway_id)
         """
-        Abstract method for subclasses to implement their main asynchronous logic.
-        This coroutine is executed within the managed event loop.
+        pass
+
+    @abc.abstractmethod
+    def _get_component_type(self) -> str:
+        """
+        Returns component type string.
+        Must be implemented by subclasses.
+
+        Returns:
+            Component type ("gateway", "agent", etc.)
         """
         pass
 
+    async def _async_setup_and_run(self) -> None:
+        """
+        Base async setup that initializes Trust Manager if present.
+        Subclasses should override and call super() first, then add their logic.
+        """
+        # Initialize Trust Manager if present (ENTERPRISE FEATURE)
+        if self.trust_manager:
+            try:
+                log.info(
+                    "%s Initializing Trust Manager with periodic publishing...",
+                    self.log_identifier,
+                )
+                # Pass event loop and add_timer method to Trust Manager
+                await self.trust_manager.initialize(
+                    add_timer_callback=self.add_timer,
+                    event_loop=self.get_async_loop(),
+                )
+                log.info(
+                    "%s Trust Manager initialized successfully", self.log_identifier
+                )
+            except Exception as e:
+                log.error(
+                    "%s Failed to initialize Trust Manager: %s",
+                    self.log_identifier,
+                    e,
+                    exc_info=True,
+                )
+                # Trust Manager failure should not prevent component startup
+                # Set to None to disable trust manager for this session
+                self.trust_manager = None
+
     @abc.abstractmethod
     def _pre_async_cleanup(self) -> None:
         """

solace_agent_mesh/common/utils/pydantic_utils.py

@@ -58,3 +58,15 @@ class SamConfigBase(BaseModel):
     def __iter__(self):
         """Provides dict-like iteration over keys."""
         return iter(self.model_dump())
+    
+    def pop(self, key: str, default: Any = None) -> Any:
+        """
+        Provides dict-like .pop() method.
+        Removes the attribute and returns its value, or default if not present.
+        """
+        if hasattr(self, key):
+            value = getattr(self, key)
+            # Set to None rather than deleting, as Pydantic models don't support delattr
+            setattr(self, key, None)
+            return value
+        return default

solace_agent_mesh/config_portal/backend/common.py

@@ -34,7 +34,7 @@ AGENT_DEFAULTS = {
     "enable_embed_resolution": True,
     "enable_artifact_content_instruction": True,
     "tools": "[]",
-    "session_service_type": USE_DEFAULT_SHARED_SESSION,
+    "session_service_type": "sql",
     "session_service_behavior": "PERSISTENT",
     "artifact_service_type": USE_DEFAULT_SHARED_ARTIFACT,
     "artifact_service_base_path": "/tmp/samv2",