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

solace_agent_mesh/common/sac/sam_component_base.py

@@ -5,16 +5,19 @@ Base Component class for SAM implementations in the Solace AI Connector.
 import logging
 import abc
 import asyncio
+import concurrent.futures
 import threading
 import functools
+import time
 from typing import Any, Optional
 
 from solace_ai_connector.components.component_base import ComponentBase
 
-from ..exceptions import MessageSizeExceededError
+from ..exceptions import ComponentInitializationError, MessageSizeExceededError
 from ..utils.message_utils import validate_message_size
 
 log = logging.getLogger(__name__)
+trace_logger = logging.getLogger("sam_trace")
 
 
 class SamComponentBase(ComponentBase, abc.ABC):
@@ -64,7 +67,7 @@ class SamComponentBase(ComponentBase, abc.ABC):
         # 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)
+        log.info("%s Initialized SamComponentBase", self.log_identifier)
 
     def add_timer(
         self,
@@ -218,6 +221,50 @@ class SamComponentBase(ComponentBase, abc.ABC):
                     self.log_identifier,
                     timer_id,
                 )
+        elif event.event_type == EventType.CACHE_EXPIRY:  
+            import asyncio
+            import inspect
+
+            cache_data = event.data
+            handler = self.handle_cache_expiry_event
+
+            # Check if the handler is async
+            if inspect.iscoroutinefunction(handler):
+                # Schedule async handler on the event loop
+                if self._async_loop and self._async_loop.is_running():
+                    async def handle_async():
+                        await handler(cache_data)
+
+                    try:
+                        future = asyncio.run_coroutine_threadsafe(
+                            handle_async(),
+                            self._async_loop
+                        )
+
+                        def on_done(f):
+                            try:
+                                f.result()
+                            except Exception as e:
+                                log.error(
+                                    "%s Error in async cache expiry handler: %s",
+                                    self.log_identifier,
+                                    e,
+                                    exc_info=True
+                                )
+                        future.add_done_callback(on_done)
+                    except RuntimeError as e:
+                        log.error(
+                            "%s Failed to schedule async CACHE_EXPIRY handler (event loop may be stopping): %s",
+                            self.log_identifier,
+                            e
+                        )
+                else:
+                    log.error(
+                        "%s Cannot handle async CACHE_EXPIRY: event loop not available",
+                        self.log_identifier
+                    )
+            else:
+                handler(cache_data)
         else:
             # Pass other event types to parent class
             super().process_event(event)
@@ -350,9 +397,18 @@ 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"
             )
 
+            # Create user_properties if it doesn't exist
+            if user_properties is None:
+                user_properties = {}
+            
+            user_properties["timestamp"] = int(time.time() * 1000)
+
             # Validate message size
             is_valid, actual_size = validate_message_size(
                 payload, self.max_message_size_bytes, self.log_identifier
@@ -363,14 +419,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,
@@ -379,7 +435,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)
@@ -391,19 +448,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(
@@ -434,15 +496,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:
@@ -502,6 +560,26 @@ class SamComponentBase(ComponentBase, abc.ABC):
                 "%s Async operations thread already running.", self.log_identifier
             )
 
+        # Monitor async initialization without blocking (critical for multi-agent processes)
+        if hasattr(self, '_async_init_future') and self._async_init_future is not None:
+            log.info("%s Setting up async initialization monitoring...", self.log_identifier)
+
+            def handle_init_completion(future):
+                """Non-blocking callback for initialization completion."""
+                try:
+                    future.result()  # Raises if init failed
+                    log.info("%s Async initialization completed successfully.", self.log_identifier)
+                except Exception as init_error:
+                    error_msg = f"{self.log_identifier} Async initialization failed: {init_error}"
+                    log.error(error_msg, exc_info=init_error)
+                    self.stop_signal.set()
+                    self._async_init_error = ComponentInitializationError(
+                        self.log_identifier, init_error, error_msg
+                    )
+
+            self._async_init_future.add_done_callback(handle_init_completion)
+            log.info("%s Async initialization monitoring active (non-blocking).", self.log_identifier)
+
         super().run()
         log.info("%s SamComponentBase run method finished.", self.log_identifier)
 
@@ -630,7 +708,7 @@ class SamComponentBase(ComponentBase, abc.ABC):
                     event_loop=self.get_async_loop(),
                 )
                 log.info(
-                    "%s Trust Manager initialized successfully", self.log_identifier
+                    "%s Initialized Trust Manager", self.log_identifier
                 )
             except Exception as e:
                 log.error(

solace_agent_mesh/common/sam_events/event_service.py

@@ -45,9 +45,9 @@ class SamEvent:
 @dataclass
 class SessionDeletedEvent(SamEvent):
     """System event for session deletion."""
-    
+
     @classmethod
-    def create(cls, namespace: str, source_component: str, session_id: str, 
+    def create(cls, namespace: str, source_component: str, session_id: str,
                user_id: str, agent_id: str, gateway_id: str) -> "SessionDeletedEvent":
         """Create a session deleted event."""
         data = {

solace_agent_mesh/common/services/employee_service.py

@@ -66,7 +66,7 @@ class BaseEmployeeService(ABC):
         pass
 
     @abstractmethod
-    async def get_time_off_data(self, employee_id: str) -> List[Dict[str, Any]]:
+    async def get_time_off_data(self, employee_id: str, start_date: Optional[str] = None, end_date: Optional[str] = None) -> List[Dict[str, Any]]:
         """
         Retrieves a list of raw time-off entries for an employee.
 

solace_agent_mesh/common/utils/embeds/constants.py

@@ -38,6 +38,7 @@ EARLY_EMBED_TYPES: Set[str] = {
 }
 LATE_EMBED_TYPES: Set[str] = {
     "artifact_content",
+    "artifact_return",
 }
 
 TEXT_CONTAINER_MIME_TYPES: Set[str] = {

solace_agent_mesh/common/utils/embeds/converter.py

@@ -14,12 +14,7 @@ from ..mime_helpers import is_text_based_mime_type
 
 log = logging.getLogger(__name__)
 
-try:
-    import yaml
-
-    PYYAML_AVAILABLE = True
-except ImportError:
-    PYYAML_AVAILABLE = False
+import yaml
 
 
 def _parse_string_to_list_of_dicts(
@@ -63,8 +58,6 @@ def _parse_string_to_list_of_dicts(
             reader = csv.DictReader(string_io)
             return list(reader), None
         elif "yaml" in normalized_mime_type or "yml" in normalized_mime_type:
-            if not PYYAML_AVAILABLE:
-                return None, "YAML parsing skipped: 'PyYAML' not installed."
             parsed_yaml = yaml.safe_load(data_string)
             if isinstance(parsed_yaml, list) and all(
                 isinstance(item, dict) for item in parsed_yaml

solace_agent_mesh/common/utils/embeds/modifiers.py

@@ -10,23 +10,12 @@ from .constants import EARLY_EMBED_TYPES, LATE_EMBED_TYPES
 
 log = logging.getLogger(__name__)
 
-try:
-    from jsonpath_ng.ext import parse as jsonpath_parse
-
-    JSONPATH_NG_AVAILABLE = True
-except ImportError:
-    JSONPATH_NG_AVAILABLE = False
-
-try:
-    import pystache
-
-    PYSTACHE_AVAILABLE = True
-except ImportError:
-    PYSTACHE_AVAILABLE = False
+from jsonpath_ng.ext import parse as jsonpath_parse
+import pystache
 
 from google.adk.artifacts import BaseArtifactService
 
-from .types import DataFormat
+from .types import DataFormat, ResolutionMode
 
 
 def _apply_jsonpath(
@@ -45,13 +34,6 @@ def _apply_jsonpath(
         Tuple: (result_data, original_mime_type, error_string)
                result_data is typically a list of matched values.
     """
-    if not JSONPATH_NG_AVAILABLE:
-        return (
-            current_data,
-            mime_type,
-            "JSONPath modifier skipped: 'jsonpath-ng' not installed.",
-        )
-
     if not isinstance(current_data, (dict, list)):
         return (
             current_data,
@@ -457,13 +439,6 @@ async def _apply_template(
     """
     from .resolver import resolve_embeds_recursively_in_string, evaluate_embed
 
-    if not PYSTACHE_AVAILABLE:
-        return (
-            current_data,
-            mime_type,
-            "Template modifier skipped: 'pystache' not installed.",
-        )
-
     if not isinstance(current_data, (dict, list, str)):
         return (
             current_data,
@@ -661,6 +636,7 @@ async def _apply_template(
             context=context,
             resolver_func=evaluate_embed,
             types_to_resolve=EARLY_EMBED_TYPES.union(LATE_EMBED_TYPES),
+            resolution_mode=ResolutionMode.RECURSIVE_ARTIFACT_CONTENT,
             log_identifier=f"{log_id}[TemplateEmbeds]",
             config=resolver_config,
             max_depth=resolver_config.get("gateway_recursive_embed_depth", 12),

solace_agent_mesh/common/utils/embeds/resolver.py

@@ -5,6 +5,7 @@ Contains the main embed resolution functions, including the chain executor.
 import logging
 import asyncio
 import json
+import uuid
 from typing import Any, Callable, Dict, Optional, Set, Tuple, List, Union
 from .constants import (
     EMBED_REGEX,
@@ -20,16 +21,12 @@ from .converter import (
     serialize_data,
     _parse_string_to_list_of_dicts,
 )
-from .types import DataFormat
+from .types import DataFormat, ResolutionMode
 from ..mime_helpers import is_text_based_mime_type
 
 log = logging.getLogger(__name__)
 
-try:
-    import yaml
-    from .converter import PYYAML_AVAILABLE
-except ImportError:
-    PYYAML_AVAILABLE = False
+import yaml
 
 
 def _log_data_state(
@@ -85,10 +82,11 @@ async def _evaluate_artifact_content_embed_with_chain(
     output_format_from_directive: Optional[str],
     context: Any,
     log_identifier: str,
+    resolution_mode: "ResolutionMode",
     config: Optional[Dict] = None,
     current_depth: int = 0,
     visited_artifacts: Optional[Set[Tuple[str, int]]] = None,
-) -> Tuple[str, Optional[str], int]:
+) -> Union[Tuple[str, Optional[str], int], Tuple[None, str, Any]]:
     """
     Loads artifact content, recursively resolves its internal embeds if text-based,
     applies a chain of modifiers, and serializes the final result.
@@ -167,6 +165,7 @@ async def _evaluate_artifact_content_embed_with_chain(
                 context=context,
                 resolver_func=evaluate_embed,
                 types_to_resolve=EARLY_EMBED_TYPES.union(LATE_EMBED_TYPES),
+                resolution_mode=ResolutionMode.RECURSIVE_ARTIFACT_CONTENT,
                 log_identifier=log_identifier,
                 config=config,
                 max_depth=config.get("gateway_recursive_embed_depth", 12),
@@ -181,7 +180,7 @@ async def _evaluate_artifact_content_embed_with_chain(
             current_format = DataFormat.STRING
             _log_data_state(
                 log_identifier,
-                f"[Depth:{current_depth}] After Recursive Resolution",
+                f"[Depth:{current_depth}] After Recursive Resolution (including templates)",
                 current_data,
                 current_format,
                 original_mime_type,
@@ -229,25 +228,17 @@ async def _evaluate_artifact_content_embed_with_chain(
                     original_mime_type,
                 )
         elif "yaml" in normalized_mime_type or "yml" in normalized_mime_type:
-            if PYYAML_AVAILABLE:
-                try:
-                    current_data = yaml.safe_load(current_data)
-                    current_format = DataFormat.JSON_OBJECT
-                    log.info(
-                        "%s [Depth:%d] Pre-parsed string as YAML (now JSON_OBJECT).",
-                        log_identifier,
-                        current_depth,
-                    )
-                except yaml.YAMLError:
-                    log.warning(
-                        "%s [Depth:%d] Failed to pre-parse as YAML despite MIME type '%s'. Content will be treated as STRING.",
-                        log_identifier,
-                        current_depth,
-                        original_mime_type,
-                    )
-            else:
+            try:
+                current_data = yaml.safe_load(current_data)
+                current_format = DataFormat.JSON_OBJECT
+                log.info(
+                    "%s [Depth:%d] Pre-parsed string as YAML (now JSON_OBJECT).",
+                    log_identifier,
+                    current_depth,
+                )
+            except yaml.YAMLError:
                 log.warning(
-                    "%s [Depth:%d] Skipping YAML pre-parsing for MIME type '%s' because PyYAML is not installed.",
+                    "%s [Depth:%d] Failed to pre-parse as YAML despite MIME type '%s'. Content will be treated as STRING.",
                     log_identifier,
                     current_depth,
                     original_mime_type,
@@ -422,6 +413,26 @@ async def _evaluate_artifact_content_embed_with_chain(
             err_msg = f"Unexpected error in modifier '{prefix}': {mod_err}"
             return f"[Error: {err_msg}]", err_msg, 0
 
+    if (
+        current_format == DataFormat.BYTES
+        and resolution_mode == ResolutionMode.A2A_MESSAGE_TO_USER
+    ):
+        log.info(
+            "%s [Depth:%d] Result is binary data in A2A_MESSAGE_TO_USER mode. Signaling for inline binary content.",
+            log_identifier,
+            current_depth,
+        )
+        filename_for_signal = artifact_spec_from_directive.split(":", 1)[0]
+        return (
+            None,
+            "SIGNAL_INLINE_BINARY_CONTENT",
+            {
+                "bytes": current_data,
+                "mime_type": original_mime_type,
+                "name": filename_for_signal,
+            },
+        )
+
     target_string_format = output_format_from_directive
     if target_string_format is None:
         log.warning(
@@ -486,9 +497,10 @@ async def resolve_embeds_in_string(
         ..., Union[Tuple[str, Optional[str], int], Tuple[None, str, Any]]
     ],
     types_to_resolve: Set[str],
+    resolution_mode: "ResolutionMode",
     log_identifier: str = "[EmbedUtil]",
     config: Optional[Dict[str, Any]] = None,
-) -> Tuple[str, int, List[Tuple[int, Any]]]:
+) -> Tuple[str, int, List[Tuple[int, Any, str]]]:
     """
     Resolves specified embed types within a string using a provided resolver function.
     This is the TOP-LEVEL resolver called by gateways. It handles signals and buffering.
@@ -520,7 +532,7 @@ async def resolve_embeds_in_string(
           The index corresponds to the start index of the embed directive in the original string.
     """
     resolved_parts = []
-    signals_found: List[Tuple[int, Any]] = []
+    signals_found: List[Tuple[int, Any, str]] = []
     last_end = 0
     original_length = len(text)
 
@@ -550,6 +562,7 @@ async def resolve_embeds_in_string(
                 format_spec,
                 context,
                 log_identifier,
+                resolution_mode,
                 config,
             )
 
@@ -566,10 +579,13 @@ async def resolve_embeds_in_string(
                     signal_type,
                     start,
                 )
+                placeholder = f"__EMBED_SIGNAL_{uuid.uuid4().hex}__"
+                resolved_parts.append(placeholder)
                 signals_found.append(
                     (
                         start,
                         resolved_value,
+                        placeholder,
                     )
                 )
             elif (
@@ -649,6 +665,34 @@ async def resolve_embeds_in_string(
             len(final_text),
         )
 
+    # If resolving late embeds, also resolve template blocks
+    # Templates are considered late embeds since they need artifact service access
+    if LATE_EMBED_TYPES.intersection(types_to_resolve):
+        try:
+            from ..templates import resolve_template_blocks_in_string
+
+            artifact_service = context.get("artifact_service")
+            session_context = context.get("session_context")
+
+            if artifact_service and session_context:
+                log.debug(
+                    "%s Resolving template blocks after late embed resolution.",
+                    log_identifier,
+                )
+                final_text = await resolve_template_blocks_in_string(
+                    text=final_text,
+                    artifact_service=artifact_service,
+                    session_context=session_context,
+                    log_identifier=f"{log_identifier}[TemplateResolve]",
+                )
+        except Exception as template_err:
+            log.warning(
+                "%s Failed to resolve template blocks: %s",
+                log_identifier,
+                template_err,
+            )
+            # Continue with final_text as-is
+
     return final_text, processed_until_index, signals_found
 
 
@@ -657,6 +701,7 @@ async def resolve_embeds_recursively_in_string(
     context: Any,
     resolver_func: Callable[..., Tuple[str, Optional[str], int]],
     types_to_resolve: Set[str],
+    resolution_mode: "ResolutionMode",
     log_identifier: str,
     config: Optional[Dict],
     max_depth: int,
@@ -709,6 +754,7 @@ async def resolve_embeds_recursively_in_string(
             format_spec,
             context,
             log_identifier,
+            resolution_mode,
             config,
             current_depth,
             visited_artifacts,
@@ -767,7 +813,39 @@ async def resolve_embeds_recursively_in_string(
         last_end = end
 
     resolved_parts.append(text[last_end:])
-    return "".join(resolved_parts)
+    result_text = "".join(resolved_parts)
+
+    # If resolving late embeds, also resolve template blocks
+    # Templates are considered late embeds since they need artifact service access
+    if LATE_EMBED_TYPES.intersection(types_to_resolve):
+        try:
+            from ..templates import resolve_template_blocks_in_string
+
+            artifact_service = context.get("artifact_service")
+            session_context = context.get("session_context")
+
+            if artifact_service and session_context:
+                log.debug(
+                    "%s [Depth:%d] Resolving template blocks after late embed resolution.",
+                    log_identifier,
+                    current_depth,
+                )
+                result_text = await resolve_template_blocks_in_string(
+                    text=result_text,
+                    artifact_service=artifact_service,
+                    session_context=session_context,
+                    log_identifier=f"{log_identifier}[TemplateResolve]",
+                )
+        except Exception as template_err:
+            log.warning(
+                "%s [Depth:%d] Failed to resolve template blocks: %s",
+                log_identifier,
+                current_depth,
+                template_err,
+            )
+            # Continue with result_text as-is
+
+    return result_text
 
 
 async def evaluate_embed(
@@ -776,6 +854,7 @@ async def evaluate_embed(
     format_spec: Optional[str],
     context: Dict[str, Any],
     log_identifier: str,
+    resolution_mode: "ResolutionMode",
     config: Optional[Dict] = None,
     current_depth: int = 0,
     visited_artifacts: Optional[Set[Tuple[str, int]]] = None,
@@ -812,6 +891,26 @@ async def evaluate_embed(
         log.info("%s Detected 'status_update' embed. Signaling.", log_identifier)
         return (None, "SIGNAL_STATUS_UPDATE", status_text)
 
+    elif embed_type == "artifact_return":
+        if resolution_mode == ResolutionMode.A2A_MESSAGE_TO_USER:
+            parts = expression.strip().split(":", 1)
+            filename = parts[0]
+            version = parts[1] if len(parts) > 1 else "latest"
+            log.info("%s Detected 'artifact_return' embed. Signaling.", log_identifier)
+            return (
+                None,
+                "SIGNAL_ARTIFACT_RETURN",
+                {"filename": filename, "version": version},
+            )
+        else:
+            log.warning(
+                "%s Ignoring 'artifact_return' embed in unsupported context: %s",
+                log_identifier,
+                resolution_mode.name,
+            )
+            original_embed_text = f"«{embed_type}:{expression}»"
+            return original_embed_text, None, len(original_embed_text.encode("utf-8"))
+
     elif embed_type == "artifact_content":
         artifact_spec, modifiers, output_format = _parse_modifier_chain(expression)
         if output_format is None and format_spec is not None:
@@ -822,17 +921,39 @@ async def evaluate_embed(
             )
             output_format = format_spec
 
-        final_string, error, size = await _evaluate_artifact_content_embed_with_chain(
+        # Check if this is a deep research report artifact
+        # Deep research reports should be rendered by the frontend component, not resolved inline
+        filename_part = artifact_spec.split(":")[0] if ":" in artifact_spec else artifact_spec
+        is_deep_research_report = filename_part.lower().endswith("_report.md")
+        
+        if is_deep_research_report and resolution_mode == ResolutionMode.A2A_MESSAGE_TO_USER:
+            # Parse version from artifact_spec
+            parts = artifact_spec.strip().split(":", 1)
+            filename = parts[0]
+            version = parts[1] if len(parts) > 1 else "latest"
+            log.info(
+                "%s Detected deep research report artifact '%s'. Signaling for frontend rendering instead of inline resolution.",
+                log_identifier,
+                filename,
+            )
+            return (
+                None,
+                "SIGNAL_DEEP_RESEARCH_REPORT",
+                {"filename": filename, "version": version},
+            )
+
+        result = await _evaluate_artifact_content_embed_with_chain(
             artifact_spec_from_directive=artifact_spec,
             modifiers_from_directive=modifiers,
             output_format_from_directive=output_format,
             context=context,
             log_identifier=log_identifier,
+            resolution_mode=resolution_mode,
             config=config,
             current_depth=current_depth,
             visited_artifacts=visited_artifacts or set(),
         )
-        return final_string, error, size
+        return result
 
     else:
         evaluator = EMBED_EVALUATORS.get(embed_type)

solace_agent_mesh/common/utils/embeds/types.py

@@ -5,6 +5,15 @@ Defines types used within the embed processing system, like DataFormat.
 from enum import Enum, auto
 
 
+class ResolutionMode(Enum):
+    """Defines the context in which embed resolution is occurring."""
+
+    A2A_MESSAGE_TO_USER = auto()
+    TOOL_PARAMETER = auto()
+    RECURSIVE_ARTIFACT_CONTENT = auto()
+    ARTIFACT_STREAMING = auto()  # For streaming artifact chunks to browser
+
+
 class DataFormat(Enum):
     """Represents internal data formats during modifier chain execution."""