solace-agent-mesh 1.6.0__py3-none-any.whl → 1.6.2__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
 
@@ -14,6 +15,8 @@ from ..exceptions import MessageSizeExceededError
 from ..utils.message_utils import validate_message_size
 
 log = logging.getLogger(__name__)
+trace_logger = logging.getLogger("sam_trace")
+
 
 class SamComponentBase(ComponentBase, abc.ABC):
     """
@@ -54,7 +57,293 @@ class SamComponentBase(ComponentBase, abc.ABC):
 
         self._async_loop: asyncio.AbstractEventLoop | None = None
         self._async_thread: threading.Thread | None = None
-        log.info("%s SamComponentBase initialized successfully.", self.log_identifier)
+
+        # 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 Initialized SamComponentBase", 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
@@ -62,7 +351,10 @@ class SamComponentBase(ComponentBase, abc.ABC):
         """Helper to publish A2A messages via the SAC App with size validation."""
         try:
             log.debug(
-                f"{self.log_identifier} [publish_a2a_message] Starting - topic: {topic}, payload keys: {list(payload.keys()) if isinstance(payload, dict) else 'not_dict'}"
+                "%s [publish_a2a_message] Starting - topic: %s, payload keys: %s",
+                self.log_identifier,
+                topic,
+                list(payload.keys()) if isinstance(payload, dict) else "not_dict"
             )
 
             # Validate message size
@@ -75,14 +367,14 @@ class SamComponentBase(ComponentBase, abc.ABC):
                     f"Message size validation failed: payload size ({actual_size} bytes) "
                     f"exceeds maximum allowed size ({self.max_message_size_bytes} bytes)"
                 )
-                log.error("%s %s", self.log_identifier, error_msg)
+                log.error("%s [publish_a2a_message] %s", self.log_identifier, error_msg)
                 raise MessageSizeExceededError(
                     actual_size, self.max_message_size_bytes, error_msg
                 )
 
             # Debug logging to show message size when publishing
             log.debug(
-                "%s Publishing message to topic %s (size: %d bytes)",
+                "%s [publish_a2a_message] Publishing message to topic %s (size: %d bytes)",
                 self.log_identifier,
                 topic,
                 actual_size,
@@ -91,7 +383,8 @@ class SamComponentBase(ComponentBase, abc.ABC):
             app = self.get_app()
             if app:
                 log.debug(
-                    f"{self.log_identifier} [publish_a2a_message] Got app instance, about to call app.send_message"
+                    "%s [publish_a2a_message] Got app instance, about to call app.send_message",
+                    self.log_identifier
                 )
 
                 # Conditionally log to invocation monitor if it exists (i.e., on an agent)
@@ -103,19 +396,24 @@ class SamComponentBase(ComponentBase, abc.ABC):
                         component_identifier=self.log_identifier,
                     )
 
-                log.debug(
-                    f"{self.log_identifier} [publish_a2a_message] About to call app.send_message with payload: {payload}"
-                )
-                log.debug(
-                    f"{self.log_identifier} [publish_a2a_message] App send_message params - topic: {topic}, user_properties: {user_properties}"
-                )
+                if trace_logger.isEnabledFor(logging.DEBUG):
+                    trace_logger.debug(
+                        "%s [publish_a2a_message] About to call app.send_message on topic '%s'\nwith payload: %s\nwith user_properties: %s",
+                        self.log_identifier, topic, payload, user_properties
+                    )
+                else:
+                    log.debug(
+                        "%s [publish_a2a_message] About to call app.send_message on topic '%s' (for more details, enable TRACE logging)",
+                        self.log_identifier, topic
+                    )
 
                 app.send_message(
                     payload=payload, topic=topic, user_properties=user_properties
                 )
 
                 log.debug(
-                    f"{self.log_identifier} [publish_a2a_message] Successfully called app.send_message"
+                    "%s [publish_a2a_message] Successfully called app.send_message on topic '%s'",
+                    self.log_identifier, topic
                 )
             else:
                 log.error(
@@ -146,15 +444,11 @@ class SamComponentBase(ComponentBase, abc.ABC):
         main_task = None
         try:
             log.info(
-                "%s Starting _async_setup_and_run as an asyncio task.",
+                "%s Starting _async_setup_and_run as an asyncio task. Will run event loop forever (or until stop_signal).",
                 self.log_identifier,
             )
             main_task = self._async_loop.create_task(self._async_setup_and_run())
 
-            log.info(
-                "%s Running asyncio event loop forever (or until stop_signal).",
-                self.log_identifier,
-            )
             self._async_loop.run_forever()
 
         except Exception as e:
@@ -197,6 +491,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 +554,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:
         """
-        Abstract method for subclasses to implement their main asynchronous logic.
-        This coroutine is executed within the managed event loop.
+        Returns unique identifier for this component instance.
+        Must be implemented by subclasses.
+
+        Returns:
+            Unique component identifier (e.g., agent_name, gateway_id)
         """
         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 Initialized Trust Manager", 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

@@ -1,6 +1,7 @@
 """Provides a Pydantic BaseModel for SAM configuration with dict-like access."""
-from pydantic import BaseModel
-from typing import Any, Dict, Type, TypeVar
+from pydantic import BaseModel, ValidationError
+from typing import Any, TypeVar, Union, get_args, get_origin
+from types import UnionType
 
 T = TypeVar("T", bound="SamConfigBase")
 
@@ -13,7 +14,7 @@ class SamConfigBase(BaseModel):
     """
 
     @classmethod
-    def model_validate_and_clean(cls: Type[T], obj: Any) -> T:
+    def model_validate_and_clean(cls: type[T], obj: Any) -> T:
         """
         Validates a dictionary, first removing any keys with None values.
         This allows Pydantic's default values to be applied correctly when
@@ -24,6 +25,92 @@ class SamConfigBase(BaseModel):
             return cls.model_validate(cleaned_obj)
         return cls.model_validate(obj)
 
+    @classmethod
+    def format_validation_error_message(cls: type[T], error: ValidationError, app_name: str | None, agent_name: str | None = None) -> str:
+        """
+        Formats Pydantic validation error messages into a clear, actionable format.
+
+        Example output:
+        ---- Configuration validation failed for 'my-agent-app' ----
+
+           Agent Name: AgentConfig
+
+        ERROR 1:
+           Missing required field: 'namespace'
+           Location: app_config.namespace
+           Description: Absolute topic prefix for A2A communication (e.g., 'myorg/dev')
+
+        ---- Please update your YAML configuration ----
+        """
+
+        error_lines = [
+            f"\n---- Configuration validation failed for {app_name or 'UNKNOWN'} ----",
+            ""
+        ]
+
+        if agent_name:
+            error_lines.append(f"   Agent Name: {agent_name}\n")
+
+        def get_nested_field_description(model_class: type[BaseModel], path: list[str | int]) -> str | None:
+            """Recursively get field description from nested models"""
+            if not path:
+                return None
+
+            current_field = path[0]
+            if str(current_field) not in model_class.model_fields:
+                return None
+
+            field_info = model_class.model_fields[str(current_field)]
+
+            if len(path) == 1:
+                return field_info.description
+
+            annotation = field_info.annotation
+
+            # Handle Optional/Union types
+            if annotation is not None:
+                origin = get_origin(annotation)
+                if origin is Union or origin is UnionType:
+                    types = get_args(annotation)
+                    annotation = next((t for t in types if t is not type(None)), None)
+                elif origin is list:
+                    inner_type = get_args(annotation)[0]
+                    if len(path) > 1 and isinstance(path[1], int):
+                        if isinstance(inner_type, type) and issubclass(inner_type, BaseModel):
+                            return get_nested_field_description(inner_type, path[2:])
+                        return None
+                    annotation = inner_type
+
+            if annotation is not None and isinstance(annotation, type) and issubclass(annotation, BaseModel):
+                return get_nested_field_description(annotation, path[1:])
+
+            return None
+
+
+        for index, err in enumerate(error.errors()):
+            error_type = err.get('type')
+            loc = err['loc']
+            msg = err['msg']
+
+            error_lines.append(f"ERROR {index + 1}:")
+
+            absolute_path = '.'.join(str(item) for item in loc)
+            description = get_nested_field_description(cls, list(loc))
+            if error_type == 'missing':
+                error_lines.extend([
+                    f"   Missing required field: '{loc[-1]}'",
+                ])
+            else:
+                error_lines.extend([
+                    f"   Error: {msg}",
+                ])
+            error_lines.append(f"   Location: app_config.{absolute_path}")
+            error_lines.append(f"   Description: {description or 'UNKNOWN'}")
+            error_lines.append("")
+
+        error_lines.append('---- Please update your YAML configuration ----')
+        return '\n'.join(error_lines) + "\n"
+
     def get(self, key: str, default: Any = None) -> Any:
         """Provides dict-like .get() method."""
         return getattr(self, key, default)

solace_agent_mesh/gateway/base/app.py

@@ -19,6 +19,7 @@ from ...common.a2a import (
 
 log = logging.getLogger(__name__)
 
+
 class BaseGatewayComponent(ComponentBase):
     pass
 
@@ -244,6 +245,20 @@ class BaseGatewayApp(App):
                 )
             },
         ]
+
+        # Add trust card subscription if trust manager is enabled
+        trust_config = resolved_app_config_block.get("trust_manager")
+        if trust_config and trust_config.get("enabled", False):
+            from ...common.a2a.protocol import get_trust_card_subscription_topic
+
+            trust_card_topic = get_trust_card_subscription_topic(self.namespace)
+            subscriptions.append({"topic": trust_card_topic})
+            log.info(
+                "Trust Manager enabled for gateway '%s', added trust card subscription: %s",
+                self.gateway_id,
+                trust_card_topic,
+            )
+
         log.info(
             "Generated Solace subscriptions for gateway '%s': %s",
             self.gateway_id,