solace-agent-mesh 1.7.1__py3-none-any.whl → 1.13.2__py3-none-any.whl

solace_agent_mesh/gateway/base/component.py

@@ -4,6 +4,7 @@ Base Component class for Gateway implementations in the Solace AI Connector.
 
 import logging
 import asyncio
+import base64
 import queue
 import re
 import uuid
@@ -21,7 +22,9 @@ from ...common.services.identity_service import (
     create_identity_service,
 )
 from .task_context import TaskContextManager
+from .auth_interface import AuthHandler
 from ...common.a2a.types import ContentPart
+from ...common.utils.rbac_utils import validate_agent_access
 from a2a.types import (
     Message as A2AMessage,
     AgentCard,
@@ -33,6 +36,7 @@ from a2a.types import (
     TextPart,
     DataPart,
     FilePart,
+    FileWithBytes,
     Artifact as A2AArtifact,
 )
 from ...common import a2a
@@ -41,12 +45,14 @@ from ...common.utils.embeds import (
     evaluate_embed,
     LATE_EMBED_TYPES,
     EARLY_EMBED_TYPES,
+    resolve_embeds_recursively_in_string,
 )
 from ...common.utils.embeds.types import ResolutionMode
 from ...agent.utils.artifact_helpers import (
     load_artifact_content_or_metadata,
     format_artifact_uri,
 )
+from ...common.utils.mime_helpers import is_text_based_mime_type
 from solace_ai_connector.common.message import (
     Message as SolaceMessage,
 )
@@ -164,7 +170,9 @@ class BaseGatewayComponent(SamComponentBase):
 
         self.agent_registry: AgentRegistry = AgentRegistry()
         self.core_a2a_service: CoreA2AService = CoreA2AService(
-            agent_registry=self.agent_registry, namespace=self.namespace
+            agent_registry=self.agent_registry,
+            namespace=self.namespace,
+            component_id="WebUI"
         )
         self.shared_artifact_service: Optional[BaseArtifactService] = (
             initialize_artifact_service(self)
@@ -184,10 +192,65 @@ class BaseGatewayComponent(SamComponentBase):
             self.log_identifier,
         )
 
+        # Authentication handler (optional, enterprise feature)
+        self.auth_handler: Optional[AuthHandler] = None
+
+        # Setup authentication if enabled (subclasses override _setup_auth)
+        self._setup_auth()
+
         log.info(
             "%s Initialized Base Gateway Component.", self.log_identifier
         )
 
+    def _setup_auth(self) -> None:
+        """
+        Setup authentication handler if enabled.
+
+        This method is called during initialization and can be overridden
+        by subclasses to customize auth setup. The default implementation
+        does nothing - subclasses should override to enable auth.
+
+        Example override in subclass:
+            def _setup_auth(self):
+                if self.get_config('enable_auth', False):
+                    from enterprise.auth import SAMOAuth2Handler
+                    self.auth_handler = SAMOAuth2Handler(self.config)
+        """
+        # Base implementation: no auth
+        # Subclasses (like GenericGateway) override to enable auth
+        pass
+
+    async def _inject_auth_headers(self, headers: Dict[str, str]) -> Dict[str, str]:
+        """
+        Inject authentication headers if authenticated.
+
+        This helper method should be called before making outgoing HTTP requests
+        to add authentication headers (e.g., Bearer tokens) to the request.
+
+        Args:
+            headers: Existing headers dictionary
+
+        Returns:
+            Headers dictionary with auth headers added (if authenticated)
+
+        Example:
+            headers = {"Content-Type": "application/json"}
+            headers = await self._inject_auth_headers(headers)
+            # headers now includes Authorization if authenticated
+        """
+        if self.auth_handler:
+            try:
+                auth_headers = await self.auth_handler.get_auth_headers()
+                headers.update(auth_headers)
+            except Exception as e:
+                log.warning(
+                    "%s Failed to get auth headers: %s",
+                    self.log_identifier,
+                    e
+                )
+
+        return headers
+
     async def authenticate_and_enrich_user(
         self, external_event_data: Any
     ) -> Optional[Dict[str, Any]]:
@@ -285,6 +348,17 @@ class BaseGatewayComponent(SamComponentBase):
 
         user_config["user_profile"] = user_identity
 
+        # Validate user has permission to access this target agent
+        validate_agent_access(
+            user_config=user_config,
+            target_agent_name=target_agent_name,
+            validation_context={
+                "gateway_id": self.gateway_id,
+                "source": "gateway_request",
+            },
+            log_identifier=log_id_prefix,
+        )
+
         external_request_context["user_identity"] = user_identity
         external_request_context["a2a_user_config"] = user_config
         external_request_context["api_version"] = api_version
@@ -328,6 +402,15 @@ class BaseGatewayComponent(SamComponentBase):
             "system_purpose": system_purpose,
             "response_format": response_format,
         }
+
+        # Add session behavior if provided by adapter
+        session_behavior = external_request_context.get("session_behavior")
+        if session_behavior:
+            a2a_metadata["sessionBehavior"] = session_behavior
+            log.debug(
+                "%s Setting sessionBehavior to: %s", log_id_prefix, session_behavior
+            )
+
         invoked_artifacts = external_request_context.get("invoked_with_artifacts")
         if invoked_artifacts:
             a2a_metadata["invoked_with_artifacts"] = invoked_artifacts
@@ -628,11 +711,24 @@ class BaseGatewayComponent(SamComponentBase):
                             )
                             continue
 
+                        # Resolve any late embeds inside the artifact content before returning.
+                        content_bytes = await self._resolve_embeds_in_artifact_content(
+                            content_bytes=content_bytes,
+                            mime_type=artifact_data.get("metadata", {}).get(
+                                "mime_type"
+                            ),
+                            filename=filename,
+                            external_request_context=external_request_context,
+                            log_id_prefix=log_id_prefix,
+                        )
+
                         # Create FilePart with bytes for legacy gateway to upload
                         file_part = a2a.create_file_part_from_bytes(
                             content_bytes=content_bytes,
                             name=filename,
-                            mime_type=artifact_data.get("metadata", {}).get("mime_type"),
+                            mime_type=artifact_data.get("metadata", {}).get(
+                                "mime_type"
+                            ),
                         )
 
                         # Create artifact with the file part
@@ -792,6 +888,123 @@ class BaseGatewayComponent(SamComponentBase):
                         log.exception(
                             "%s Error sending artifact creation completion signal: %s", log_id_prefix, e
                         )
+                elif signal_type == "SIGNAL_DEEP_RESEARCH_REPORT":
+                    # Handle deep research report signal for legacy gateways
+                    # For legacy gateways, we send the report as a file attachment
+                    if is_finalizing_context:
+                        log.debug(
+                            "%s Suppressing SIGNAL_DEEP_RESEARCH_REPORT during finalizing context to avoid duplicate: %s",
+                            log_id_prefix,
+                            signal_data,
+                        )
+                        continue
+
+                    try:
+                        filename = signal_data.get("filename")
+                        version = signal_data.get("version")
+
+                        if not filename:
+                            log.error(
+                                "%s SIGNAL_DEEP_RESEARCH_REPORT missing filename. Skipping.",
+                                log_id_prefix,
+                            )
+                            continue
+
+                        # Load artifact content for legacy gateways
+                        artifact_data = await load_artifact_content_or_metadata(
+                            self.shared_artifact_service,
+                            app_name=external_request_context.get(
+                                "app_name_for_artifacts", self.gateway_id
+                            ),
+                            user_id=external_request_context.get("user_id_for_artifacts"),
+                            session_id=external_request_context.get("a2a_session_id"),
+                            filename=filename,
+                            version=version,
+                            load_metadata_only=False,
+                        )
+
+                        if artifact_data.get("status") != "success":
+                            log.error(
+                                "%s Failed to load deep research report content for %s v%s",
+                                log_id_prefix,
+                                filename,
+                                version,
+                            )
+                            continue
+
+                        content = artifact_data.get("content")
+                        if not content:
+                            log.error(
+                                "%s No content found in deep research report %s v%s",
+                                log_id_prefix,
+                                filename,
+                                version,
+                            )
+                            continue
+
+                        # Convert to bytes if it's a string
+                        if isinstance(content, str):
+                            content_bytes = content.encode("utf-8")
+                        elif isinstance(content, bytes):
+                            content_bytes = content
+                        else:
+                            log.error(
+                                "%s Deep research report content is neither string nor bytes: %s",
+                                log_id_prefix,
+                                type(content),
+                            )
+                            continue
+
+                        # Create FilePart with bytes for legacy gateway to upload
+                        file_part = a2a.create_file_part_from_bytes(
+                            content_bytes=content_bytes,
+                            name=filename,
+                            mime_type=artifact_data.get("metadata", {}).get(
+                                "mime_type", "text/markdown"
+                            ),
+                        )
+
+                        # Create artifact with the file part
+                        from a2a.types import Artifact, Part
+                        artifact = Artifact(
+                            artifact_id=str(uuid.uuid4().hex),
+                            parts=[Part(root=file_part)],
+                            name=filename,
+                            description=f"Deep Research Report: {filename}",
+                        )
+
+                        # Send as TaskArtifactUpdateEvent
+                        a2a_task_id_for_signal = external_request_context.get(
+                            "a2a_task_id_for_event", original_rpc_id
+                        )
+
+                        if not a2a_task_id_for_signal:
+                            log.error(
+                                "%s Cannot determine A2A task ID for deep research report signal. Skipping.",
+                                log_id_prefix,
+                            )
+                            continue
+
+                        artifact_event = a2a.create_artifact_update(
+                            task_id=a2a_task_id_for_signal,
+                            context_id=external_request_context.get("a2a_session_id"),
+                            artifact=artifact,
+                        )
+
+                        await self._send_update_to_external(
+                            external_request_context=external_request_context,
+                            event_data=artifact_event,
+                            is_final_chunk_of_update=False,
+                        )
+                        log.info(
+                            "%s Sent deep research report as TaskArtifactUpdateEvent for %s",
+                            log_id_prefix,
+                            filename,
+                        )
+                    except Exception as e:
+                        log.exception(
+                            "%s Error sending deep research report signal: %s", log_id_prefix, e
+                        )
                 else:
                     log.warning(
                         "%s Received unhandled signal type during embed resolution: %s",
@@ -799,10 +1012,80 @@ class BaseGatewayComponent(SamComponentBase):
                         signal_type,
                     )
 
-    async def _resolve_uri_in_file_part(self, file_part: FilePart):
+    async def _resolve_embeds_in_artifact_content(
+        self,
+        content_bytes: bytes,
+        mime_type: Optional[str],
+        filename: str,
+        external_request_context: Dict[str, Any],
+        log_id_prefix: str,
+    ) -> bytes:
+        """
+        Checks if content is text-based and, if so, resolves late embeds within it.
+        Returns the (potentially modified) content as bytes.
+        """
+        if is_text_based_mime_type(mime_type):
+            log.info(
+                "%s Artifact '%s' is text-based (%s). Resolving late embeds.",
+                log_id_prefix,
+                filename,
+                mime_type,
+            )
+            try:
+                decoded_content = content_bytes.decode("utf-8")
+
+                # Construct context and config for the resolver
+                embed_eval_context = {
+                    "artifact_service": self.shared_artifact_service,
+                    "session_context": {
+                        "app_name": external_request_context.get(
+                            "app_name_for_artifacts", self.gateway_id
+                        ),
+                        "user_id": external_request_context.get(
+                            "user_id_for_artifacts"
+                        ),
+                        "session_id": external_request_context.get("a2a_session_id"),
+                    },
+                }
+                embed_eval_config = {
+                    "gateway_max_artifact_resolve_size_bytes": self.gateway_max_artifact_resolve_size_bytes,
+                    "gateway_recursive_embed_depth": self.gateway_recursive_embed_depth,
+                }
+
+                resolved_string = await resolve_embeds_recursively_in_string(
+                    text=decoded_content,
+                    context=embed_eval_context,
+                    resolver_func=evaluate_embed,
+                    types_to_resolve=LATE_EMBED_TYPES,
+                    resolution_mode=ResolutionMode.RECURSIVE_ARTIFACT_CONTENT,
+                    log_identifier=f"{log_id_prefix}[RecursiveResolve]",
+                    config=embed_eval_config,
+                    max_depth=self.gateway_recursive_embed_depth,
+                )
+                resolved_bytes = resolved_string.encode("utf-8")
+                log.info(
+                    "%s Successfully resolved embeds in '%s'. New size: %d bytes.",
+                    log_id_prefix,
+                    filename,
+                    len(resolved_bytes),
+                )
+                return resolved_bytes
+            except Exception as resolve_err:
+                log.error(
+                    "%s Failed to resolve embeds within artifact '%s': %s. Returning raw content.",
+                    log_id_prefix,
+                    filename,
+                    resolve_err,
+                )
+        return content_bytes
+
+    async def _resolve_uri_in_file_part(
+        self, file_part: FilePart, external_request_context: Dict[str, Any]
+    ):
         """
         Checks if a FilePart has a resolvable URI and, if so,
         resolves it and mutates the part in-place by calling the common utility.
+        After resolving the URI, it also resolves any late embeds within the content.
         """
         await a2a.resolve_file_part_uri(
             part=file_part,
@@ -810,15 +1093,43 @@ class BaseGatewayComponent(SamComponentBase):
             log_identifier=self.log_identifier,
         )
 
-    async def _resolve_uris_in_parts_list(self, parts: List[ContentPart]):
+        # After resolving the URI to get the content, resolve any late embeds inside it.
+        if file_part.file and isinstance(file_part.file, FileWithBytes):
+            # The content is a base64 encoded string in the `bytes` attribute.
+            # We need to decode it to raw bytes for processing.
+            try:
+                content_bytes = base64.b64decode(file_part.file.bytes)
+            except Exception as e:
+                log.error(
+                    "%s Failed to base64 decode file content for embed resolution: %s",
+                    f"{self.log_identifier}[UriResolve]",
+                    e,
+                )
+                return
+
+            resolved_bytes = await self._resolve_embeds_in_artifact_content(
+                content_bytes=content_bytes,
+                mime_type=file_part.file.mime_type,
+                filename=file_part.file.name,
+                external_request_context=external_request_context,
+                log_id_prefix=f"{self.log_identifier}[UriResolve]",
+            )
+            # Re-encode the resolved content back to a base64 string for the FileWithBytes model.
+            file_part.file.bytes = base64.b64encode(resolved_bytes).decode("utf-8")
+
+    async def _resolve_uris_in_parts_list(
+        self, parts: List[ContentPart], external_request_context: Dict[str, Any]
+    ):
         """Iterates over a list of part objects and resolves any FilePart URIs."""
         if not parts:
             return
         for part in parts:
             if isinstance(part, FilePart):
-                await self._resolve_uri_in_file_part(part)
+                await self._resolve_uri_in_file_part(part, external_request_context)
 
-    async def _resolve_uris_in_payload(self, parsed_event: Any):
+    async def _resolve_uris_in_payload(
+        self, parsed_event: Any, external_request_context: Dict[str, Any]
+    ):
         """
         Dispatcher that calls the appropriate targeted URI resolver based on the
         Pydantic model type of the event.
@@ -842,7 +1153,9 @@ class BaseGatewayComponent(SamComponentBase):
                     parts_to_resolve.extend(a2a.get_parts_from_artifact(artifact))
 
         if parts_to_resolve:
-            await self._resolve_uris_in_parts_list(parts_to_resolve)
+            await self._resolve_uris_in_parts_list(
+                parts_to_resolve, external_request_context
+            )
         else:
             log.debug(
                 "%s Payload type '%s' did not yield any parts for URI resolution. Skipping.",
@@ -1095,6 +1408,69 @@ class BaseGatewayComponent(SamComponentBase):
                                 else:
                                     # Legacy gateway mode: pass signal through for gateway to handle
                                     other_signals.append(signal_tuple)
+                            elif signal_type == "SIGNAL_DEEP_RESEARCH_REPORT":
+                                # Deep research reports should be rendered by the frontend component
+                                # For modern gateways (HTTP SSE), create a DataPart with artifact reference
+                                # For legacy gateways, pass through as signal
+                                if self.supports_inline_artifact_resolution:
+                                    try:
+                                        filename = signal_data["filename"]
+                                        version = signal_data["version"]
+                                        log.info(
+                                            "%s Converting SIGNAL_DEEP_RESEARCH_REPORT to DataPart for frontend rendering: %s v%s",
+                                            log_id_prefix,
+                                            filename,
+                                            version,
+                                        )
+                                        # Create a DataPart that the frontend can use to render DeepResearchReportBubble
+                                        # The frontend will fetch the artifact content separately
+                                        artifact_data = (
+                                            await load_artifact_content_or_metadata(
+                                                self.shared_artifact_service,
+                                                **embed_eval_context["session_context"],
+                                                filename=filename,
+                                                version=version,
+                                                load_metadata_only=True,
+                                            )
+                                        )
+                                        if artifact_data.get("status") == "success":
+                                            uri = format_artifact_uri(
+                                                **embed_eval_context["session_context"],
+                                                filename=filename,
+                                                version=artifact_data.get("version"),
+                                            )
+                                            # Create a DataPart with deep_research_report type
+                                            # This will be rendered by DeepResearchReportBubble in the frontend
+                                            data_part = a2a.create_data_part(
+                                                data={
+                                                    "type": "deep_research_report",
+                                                    "filename": filename,
+                                                    "version": artifact_data.get("version"),
+                                                    "uri": uri,
+                                                },
+                                                metadata={"source": "deep_research_tool"},
+                                            )
+                                            new_parts.append(data_part)
+                                        else:
+                                            new_parts.append(
+                                                a2a.create_text_part(
+                                                    f"[Error: Deep research report '{filename}' v{version} not found.]"
+                                                )
+                                            )
+                                    except Exception as e:
+                                        log.exception(
+                                            "%s Error handling SIGNAL_DEEP_RESEARCH_REPORT: %s",
+                                            log_id_prefix,
+                                            e,
+                                        )
+                                        new_parts.append(
+                                            a2a.create_text_part(
+                                                f"[Error: Could not retrieve deep research report '{signal_data.get('filename')}'.]"
+                                            )
+                                        )
+                                else:
+                                    # Legacy gateway mode: pass signal through for gateway to handle
+                                    other_signals.append(signal_tuple)
                             elif signal_type == "SIGNAL_INLINE_BINARY_CONTENT":
                                 signal_data["content_bytes"] = signal_data.get("bytes")
                                 del signal_data["bytes"]
@@ -1135,9 +1511,72 @@ class BaseGatewayComponent(SamComponentBase):
                 # Handle recursive embeds in text-based FileParts
                 new_parts.append(part)  # Placeholder for now
             elif isinstance(part, DataPart):
-                # Handle artifact creation progress DataParts for legacy gateways
+                # Handle special DataPart types
                 data_type = part.data.get("type") if part.data else None
-                if (
+
+                if data_type == "template_block":
+                    # Resolve template block and replace with resolved text
+                    try:
+                        from ...common.utils.templates import resolve_template_blocks_in_string
+
+                        # Reconstruct the template block syntax
+                        data_artifact = part.data.get("data_artifact", "")
+                        jsonpath = part.data.get("jsonpath")
+                        limit = part.data.get("limit")
+                        template_content = part.data.get("template_content", "")
+
+                        # Build params string
+                        params_parts = [f'data="{data_artifact}"']
+                        if jsonpath:
+                            params_parts.append(f'jsonpath="{jsonpath}"')
+                        if limit is not None:
+                            params_parts.append(f'limit="{limit}"')
+                        params_str = " ".join(params_parts)
+
+                        # Reconstruct full template block
+                        template_block = f"«««template: {params_str}\n{template_content}\n»»»"
+
+                        log.debug(
+                            "%s Resolving template block inline: data=%s",
+                            log_id_prefix,
+                            data_artifact,
+                        )
+
+                        # Resolve the template
+                        resolved_text = await resolve_template_blocks_in_string(
+                            text=template_block,
+                            artifact_service=self.shared_artifact_service,
+                            session_context={
+                                "app_name": external_request_context.get(
+                                    "app_name_for_artifacts", self.gateway_id
+                                ),
+                                "user_id": external_request_context.get("user_id_for_artifacts"),
+                                "session_id": external_request_context.get("a2a_session_id"),
+                            },
+                            log_identifier=f"{log_id_prefix}[TemplateResolve]",
+                        )
+
+                        log.info(
+                            "%s Template resolved successfully. Output length: %d",
+                            log_id_prefix,
+                            len(resolved_text),
+                        )
+
+                        # Replace the DataPart with a TextPart containing the resolved content
+                        new_parts.append(a2a.create_text_part(text=resolved_text))
+
+                    except Exception as e:
+                        log.error(
+                            "%s Failed to resolve template block: %s",
+                            log_id_prefix,
+                            e,
+                            exc_info=True,
+                        )
+                        # Send error message as TextPart
+                        error_text = f"[Template rendering error: {str(e)}]"
+                        new_parts.append(a2a.create_text_part(text=error_text))
+
+                elif (
                     data_type == "artifact_creation_progress"
                     and not self.supports_inline_artifact_resolution
                 ):
@@ -1264,7 +1703,9 @@ class BaseGatewayComponent(SamComponentBase):
                     "%s Resolving artifact URIs before sending to external...",
                     log_id_prefix,
                 )
-                await self._resolve_uris_in_payload(parsed_event)
+                await self._resolve_uris_in_payload(
+                    parsed_event, external_request_context
+                )
 
             send_this_event_to_external = True
             is_final_chunk_of_status_update = False