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

solace_agent_mesh/agent/adk/stream_parser.py

@@ -3,18 +3,30 @@ A stateful stream parser for identifying and extracting fenced artifact blocks
 from an LLM's text stream.
 """
 
+import logging
 import re
 from enum import Enum, auto
 from dataclasses import dataclass, field
 from typing import List, Dict, Any
 
+from ...common.utils.embeds.constants import (
+    EMBED_DELIMITER_OPEN,
+    EMBED_DELIMITER_CLOSE,
+)
+
+log = logging.getLogger(__name__)
+
 # --- Constants ---
 # These are duplicated from callbacks for now to keep the parser self-contained.
 # They should eventually live in a shared constants module.
 ARTIFACT_BLOCK_DELIMITER_OPEN = "«««"
 ARTIFACT_BLOCK_DELIMITER_CLOSE = "»»»"
-# The full sequence that must be matched to start a block.
-BLOCK_START_SEQUENCE = f"{ARTIFACT_BLOCK_DELIMITER_OPEN}save_artifact:"
+# The full sequences that must be matched to start a block.
+SAVE_ARTIFACT_START_SEQUENCE = f"{ARTIFACT_BLOCK_DELIMITER_OPEN}save_artifact:"
+TEMPLATE_START_SEQUENCE = f"{ARTIFACT_BLOCK_DELIMITER_OPEN}template:"
+TEMPLATE_LIQUID_START_SEQUENCE = f"{ARTIFACT_BLOCK_DELIMITER_OPEN}template_liquid:"
+# For backward compatibility
+BLOCK_START_SEQUENCE = SAVE_ARTIFACT_START_SEQUENCE
 # Regex to parse parameters from a confirmed start line.
 PARAMS_REGEX = re.compile(r'(\w+)\s*=\s*"(.*?)"')
 
@@ -66,6 +78,21 @@ class BlockInvalidatedEvent(ParserEvent):
     rolled_back_text: str
 
 
+@dataclass
+class TemplateBlockStartedEvent(ParserEvent):
+    """Emitted when a template block's start is confirmed."""
+
+    params: Dict[str, Any]
+
+
+@dataclass
+class TemplateBlockCompletedEvent(ParserEvent):
+    """Emitted when a template block is successfully closed."""
+
+    params: Dict[str, Any]
+    template_content: str
+
+
 @dataclass
 class ParserResult:
     """The result of processing a single text chunk."""
@@ -93,6 +120,14 @@ class FencedBlockStreamParser:
         self._block_params: Dict[str, Any] = {}
         self._progress_update_interval = progress_update_interval_bytes
         self._last_progress_update_size = 0
+        self._last_progress_chunk_end = 0  # Character position in buffer where last chunk ended
+        # Track block type and nesting for template handling
+        self._current_block_type: str = None  # "save_artifact" or "template"
+        self._nesting_depth = 0  # Track if we're inside a block
+        self._previous_state: ParserState = None  # Track state before POTENTIAL_BLOCK
+        # Safety limit: force emission after this many pending bytes (to handle unclosed embeds)
+        # Use minimum of 8KB to handle long templates/embeds
+        self._max_pending_bytes = max(progress_update_interval_bytes * 4, 8192)  # Min 8KB
 
     def _reset_state(self):
         """Resets the parser to its initial IDLE state."""
@@ -101,6 +136,36 @@ class FencedBlockStreamParser:
         self._artifact_buffer = ""
         self._block_params = {}
         self._last_progress_update_size = 0
+        self._last_progress_chunk_end = 0
+        self._current_block_type = None
+        self._nesting_depth = 0
+        self._previous_state = None
+
+    def _is_safe_to_emit_chunk(self) -> bool:
+        """
+        Check if current buffer position is safe for chunking (not inside an embed).
+
+        Looks at the content since the last chunk emission to see if there's an
+        unclosed embed delimiter. If so, waits until the embed is closed before emitting.
+
+        Returns:
+            True if safe to emit chunk (no partial embeds), False otherwise.
+        """
+        # Check the portion of buffer we're about to emit
+        buffer_to_check = self._artifact_buffer[self._last_progress_chunk_end:]
+
+        # Find last occurrence of opening delimiter
+        last_open = buffer_to_check.rfind(EMBED_DELIMITER_OPEN)
+
+        if last_open == -1:
+            # No embed delimiter found in this portion
+            return True
+
+        # Found an opening delimiter - check if it's closed
+        last_close = buffer_to_check.rfind(EMBED_DELIMITER_CLOSE, last_open)
+
+        # Safe only if there's a closing delimiter after the opening one
+        return last_close > last_open
 
     def process_chunk(self, text_chunk: str) -> ParserResult:
         """
@@ -142,14 +207,28 @@ class FencedBlockStreamParser:
             events.append(BlockInvalidatedEvent(rolled_back_text=rolled_back_text))
         elif self._state == ParserState.IN_BLOCK:
             # The turn ended while inside a block. This is an error/failure.
-            # The orchestrator (callback) will see this and know to fail the artifact.
-            # We emit a BlockCompletedEvent so the orchestrator knows what was buffered.
+            # The orchestrator (callback) will see this and know to fail the artifact/template.
+            # We emit the appropriate completion event so the orchestrator knows what was buffered.
             # The orchestrator is responsible for interpreting this as a failure.
-            events.append(
-                BlockCompletedEvent(
-                    params=self._block_params, content=self._artifact_buffer
-                )
+            log.warning(
+                "[StreamParser] finalize() found unterminated block! Type: %s, buffer length: %d, nesting_depth: %d",
+                self._current_block_type,
+                len(self._artifact_buffer),
+                self._nesting_depth,
             )
+            if self._current_block_type == "template":
+                events.append(
+                    TemplateBlockCompletedEvent(
+                        params=self._block_params,
+                        template_content=self._artifact_buffer,
+                    )
+                )
+            else:
+                events.append(
+                    BlockCompletedEvent(
+                        params=self._block_params, content=self._artifact_buffer
+                    )
+                )
 
         self._reset_state()
         return ParserResult("".join(user_text_parts), events)
@@ -157,6 +236,7 @@ class FencedBlockStreamParser:
     def _process_idle(self, char: str, user_text_parts: List[str]):
         """State handler for when the parser is outside any block."""
         if char == BLOCK_START_SEQUENCE[0]:
+            self._previous_state = ParserState.IDLE
             self._state = ParserState.POTENTIAL_BLOCK
             self._speculative_buffer += char
         else:
@@ -168,59 +248,168 @@ class FencedBlockStreamParser:
         """State handler for when a block might be starting."""
         self._speculative_buffer += char
 
-        # If we have the full start sequence, we are now looking for the newline.
-        if self._speculative_buffer.startswith(BLOCK_START_SEQUENCE):
+        # Check if we match save_artifact or template start sequences
+        matched_sequence = None
+        matched_type = None
+
+        if self._speculative_buffer.startswith(SAVE_ARTIFACT_START_SEQUENCE):
+            matched_sequence = SAVE_ARTIFACT_START_SEQUENCE
+            matched_type = "save_artifact"
+        elif self._speculative_buffer.startswith(TEMPLATE_LIQUID_START_SEQUENCE):
+            matched_sequence = TEMPLATE_LIQUID_START_SEQUENCE
+            matched_type = "template"
+        elif self._speculative_buffer.startswith(TEMPLATE_START_SEQUENCE):
+            matched_sequence = TEMPLATE_START_SEQUENCE
+            matched_type = "template"
+
+        if matched_sequence:
             if char == "\n":
                 # We found the newline, the block is officially started.
+
+                # If we're already inside a save_artifact block and this is a template,
+                # we need to pass it through as literal text (preserve nesting)
+                if self._nesting_depth > 0 and matched_type == "template":
+                    # Preserve template literally inside artifact
+                    self._artifact_buffer += self._speculative_buffer
+                    # Increment nesting depth so we know to skip the next »»»
+                    # (it will close the nested template, not the outer artifact)
+                    self._nesting_depth += 1
+                    # Don't reset state! We're still inside the save_artifact block.
+                    # Just clear the speculative buffer and stay IN_BLOCK to continue
+                    # buffering the rest of the artifact content.
+                    self._speculative_buffer = ""
+                    self._state = ParserState.IN_BLOCK
+                    return
+
                 self._state = ParserState.IN_BLOCK
+                self._current_block_type = matched_type
+                self._nesting_depth += 1
+
                 # Extract the parameters string between the start sequence and the newline
-                params_str = self._speculative_buffer[len(BLOCK_START_SEQUENCE) : -1]
+                params_str = self._speculative_buffer[len(matched_sequence) : -1]
                 self._block_params = dict(PARAMS_REGEX.findall(params_str))
-                events.append(BlockStartedEvent(params=self._block_params))
+
+                if matched_type == "save_artifact":
+                    events.append(BlockStartedEvent(params=self._block_params))
+                elif matched_type == "template":
+                    events.append(TemplateBlockStartedEvent(params=self._block_params))
+
                 self._speculative_buffer = ""  # Clear buffer, we are done with it.
             # else, we are still buffering the parameters line.
             return
 
-        # If we are still building up the start sequence itself
-        if BLOCK_START_SEQUENCE.startswith(self._speculative_buffer):
+        # If we are still building up a start sequence (could be either)
+        if (SAVE_ARTIFACT_START_SEQUENCE.startswith(self._speculative_buffer) or
+            TEMPLATE_LIQUID_START_SEQUENCE.startswith(self._speculative_buffer) or
+            TEMPLATE_START_SEQUENCE.startswith(self._speculative_buffer)):
             # It's still a potential match. Continue buffering.
             return
 
         # If we've reached here, the sequence is invalid.
         # Rollback: The sequence was invalid.
         rolled_back_text = self._speculative_buffer
-        user_text_parts.append(rolled_back_text)
-        events.append(BlockInvalidatedEvent(rolled_back_text=rolled_back_text))
-        self._reset_state()
+
+        # Check if we were IN_BLOCK before transitioning to POTENTIAL_BLOCK
+        # If so, add the rolled-back text to the artifact buffer, not user-visible text
+        if self._previous_state == ParserState.IN_BLOCK:
+            log.debug(
+                "[StreamParser] Invalid sequence '%s' detected while IN_BLOCK. Adding to artifact buffer.",
+                repr(rolled_back_text),
+            )
+            self._artifact_buffer += rolled_back_text
+            self._speculative_buffer = ""
+            self._state = ParserState.IN_BLOCK
+            # Don't emit BlockInvalidatedEvent - this is just normal artifact content
+        else:
+            # We were IDLE, so this is user-facing text
+            user_text_parts.append(rolled_back_text)
+            events.append(BlockInvalidatedEvent(rolled_back_text=rolled_back_text))
+            self._speculative_buffer = ""
+            self._state = ParserState.IDLE
+
+        self._previous_state = None
 
     def _process_in_block(self, char: str, events: List[ParserEvent]):
         """State handler for when the parser is inside a block, buffering content."""
+        # Check if this might be the start of a nested block
+        if char == BLOCK_START_SEQUENCE[0]:
+            # This might be the start of a nested template block
+            # Transition to POTENTIAL_BLOCK to check
+            self._previous_state = ParserState.IN_BLOCK
+            self._state = ParserState.POTENTIAL_BLOCK
+            self._speculative_buffer += char
+            return
+
         self._artifact_buffer += char
 
         # Check for the closing delimiter
         if self._artifact_buffer.endswith(ARTIFACT_BLOCK_DELIMITER_CLOSE):
-            # Block is complete.
-            final_content = self._artifact_buffer[
-                : -len(ARTIFACT_BLOCK_DELIMITER_CLOSE)
-            ]
-            events.append(
-                BlockCompletedEvent(params=self._block_params, content=final_content)
-            )
-            self._reset_state()
-        else:
-            # Check if we should emit a progress update
-            current_size = len(self._artifact_buffer.encode("utf-8"))
-            if (
-                current_size - self._last_progress_update_size
-            ) >= self._progress_update_interval:
-                new_chunk = self._artifact_buffer[
-                    self._last_progress_update_size : current_size
+            # Check if this is closing a nested block or the current block
+            if self._nesting_depth > 1:
+                # This »»» is closing a nested template block, not the outer save_artifact
+                # Keep it in the buffer and just decrement nesting
+                self._nesting_depth -= 1
+                # Don't emit events, don't strip the delimiter, just continue buffering
+            else:
+                # This is closing the outermost block (nesting_depth == 1)
+                # Block is complete.
+                final_content = self._artifact_buffer[
+                    : -len(ARTIFACT_BLOCK_DELIMITER_CLOSE)
                 ]
-                events.append(
-                    BlockProgressedEvent(
-                        params=self._block_params,
-                        buffered_size=current_size,
-                        chunk=new_chunk,
+
+                # Emit the appropriate completion event based on block type
+                if self._current_block_type == "template":
+                    events.append(
+                        TemplateBlockCompletedEvent(
+                            params=self._block_params, template_content=final_content
+                        )
                     )
-                )
-                self._last_progress_update_size = current_size
+                else:
+                    # Default to save_artifact behavior
+                    events.append(
+                        BlockCompletedEvent(
+                            params=self._block_params, content=final_content
+                        )
+                    )
+
+                # Decrement nesting depth
+                self._nesting_depth = max(0, self._nesting_depth - 1)
+                self._reset_state()
+        else:
+            # Check if we should emit a progress update (only for save_artifact blocks)
+            if self._current_block_type == "save_artifact":
+                # Calculate current total size in bytes (for threshold check)
+                current_size_bytes = len(self._artifact_buffer.encode("utf-8"))
+
+                # Check if we've accumulated enough new bytes since last update
+                bytes_since_last = current_size_bytes - self._last_progress_update_size
+                if bytes_since_last >= self._progress_update_interval:
+                    # Check if it's safe to emit (not inside an embed)
+                    # OR force emit if we've exceeded safety limit (very long unclosed embed)
+                    force_emit = bytes_since_last >= self._max_pending_bytes
+
+                    if force_emit:
+                        log.warning(
+                            "[StreamParser] Forcing chunk emission due to safety limit (%d bytes pending). "
+                            "Possible unclosed embed or very long embed.",
+                            bytes_since_last
+                        )
+
+                    if self._is_safe_to_emit_chunk() or force_emit:
+                        # Extract all new content since last progress update
+                        # Slice by character position (not bytes) to avoid UTF-8 issues
+                        current_char_position = len(self._artifact_buffer)
+                        new_chunk = self._artifact_buffer[self._last_progress_chunk_end:]
+
+                        events.append(
+                            BlockProgressedEvent(
+                                params=self._block_params,
+                                buffered_size=current_size_bytes,  # Total bytes accumulated so far
+                                chunk=new_chunk,  # All new content since last update
+                            )
+                        )
+
+                        # Update tracking: character position for slicing, bytes for threshold
+                        self._last_progress_chunk_end = current_char_position
+                        self._last_progress_update_size = current_size_bytes
+                    # else: wait for embed to close before emitting

solace_agent_mesh/agent/protocol/event_handlers.py

@@ -8,6 +8,8 @@ import json
 import logging
 from typing import TYPE_CHECKING, Any, Dict
 
+from litellm.exceptions import BadRequestError
+
 from a2a.types import (
     A2ARequest,
     AgentCapabilities,
@@ -25,11 +27,17 @@ from google.adk.agents import RunConfig
 from google.adk.agents.run_config import StreamingMode
 from solace_ai_connector.common.event import Event, EventType
 from solace_ai_connector.common.message import Message as SolaceMessage
+from sqlalchemy.exc import OperationalError
 
 from ...agent.adk.callbacks import _publish_data_part_status_update
 from ...agent.adk.runner import TaskCancelledError, run_adk_async_task_thread_wrapper
 from ...agent.utils.artifact_helpers import generate_artifact_metadata_summary
 from ...common import a2a
+from ...common.error_handlers import get_error_message
+from ...common.utils.embeds.constants import (
+    EMBED_DELIMITER_OPEN,
+    EMBED_DELIMITER_CLOSE,
+)
 from ...common.a2a import (
     get_agent_request_topic,
     get_agent_response_subscription_topic,
@@ -753,6 +761,7 @@ async def handle_a2a_request(component, message: SolaceMessage):
                 "system_purpose": system_purpose,
                 "response_format": response_format,
                 "host_agent_name": agent_name,
+                "original_message_metadata": task_metadata,  # Store original message metadata for tools
             }
 
             # Store verified user identity claims in a2a_context (not the raw token)
@@ -970,6 +979,101 @@ async def handle_a2a_request(component, message: SolaceMessage):
         component.handle_error(e, Event(EventType.MESSAGE, message))
         return None
 
+    except BadRequestError as e:
+        log.error(
+            "%s Bad Request error handling A2A request: %s", component.log_identifier, e
+        )
+        
+        # Use centralized error handler
+        error_message, is_context_limit = get_error_message(e)
+        
+        if is_context_limit:
+            log.error(
+                "%s Context limit exceeded for task %s",
+                component.log_identifier,
+                logical_task_id,
+            )
+        
+        error_response = a2a.create_invalid_request_error_response(
+            message=error_message,
+            request_id=jsonrpc_request_id,
+            data={"taskId": logical_task_id},
+        )
+        target_topic = reply_topic_from_peer or (
+            get_client_response_topic(namespace, client_id) if client_id else None
+        )
+        if target_topic:
+            component.publish_a2a_message(
+                error_response.model_dump(exclude_none=True),
+                target_topic,
+            )
+
+        try:
+            message.call_negative_acknowledgements()
+            log.warning(
+                "%s NACKed original A2A request due to bad request error.",
+                component.log_identifier,
+            )
+        except Exception as nack_e:
+            log.error(
+                "%s Failed to NACK message after bad request error: %s",
+                component.log_identifier,
+                nack_e,
+            )
+
+        component.handle_error(e, Event(EventType.MESSAGE, message))
+        return None
+
+    except OperationalError as e:
+        log.error(
+            "%s Database error while processing A2A request: %s",
+            component.log_identifier,
+            e,
+        )
+
+        # Check if it's a schema error
+        error_msg = str(e).lower()
+        if "no such column" in error_msg or "no such table" in error_msg:
+            user_message = (
+                "Database schema update required. "
+                "Please contact your administrator to run database migrations."
+            )
+        else:
+            user_message = (
+                "Database error occurred. Please try again or contact support."
+            )
+
+        error_response = a2a.create_internal_error_response(
+            message=user_message,
+            request_id=jsonrpc_request_id,
+            data={"taskId": logical_task_id} if logical_task_id else None,
+        )
+
+        target_topic = reply_topic_from_peer or (
+            get_client_response_topic(namespace, client_id) if client_id else None
+        )
+        if target_topic:
+            component.publish_a2a_message(
+                error_response.model_dump(exclude_none=True),
+                target_topic,
+            )
+
+        try:
+            message.call_negative_acknowledgements()
+            log.warning(
+                "%s NACKed A2A request due to database error.",
+                component.log_identifier,
+            )
+        except Exception as nack_e:
+            log.error(
+                "%s Failed to NACK message after database error: %s",
+                component.log_identifier,
+                nack_e,
+            )
+
+        component.handle_error(e, Event(EventType.MESSAGE, message))
+        return None
+
     except Exception as e:
         log.exception(
             "%s Unexpected error handling A2A request: %s", component.log_identifier, e
@@ -1296,43 +1400,96 @@ async def handle_a2a_response(component, message: SolaceMessage):
                                         peer_agent_name=peer_agent_name,
                                         message=message,
                                     )
+                                    # Reset the timeout since we received a status update
+                                    await component.reset_peer_timeout(sub_task_id)
                                     return
 
+                                # Filter out artifact creation progress from peer agents.
+                                # These are implementation details that should not leak across
+                                # agent boundaries. Artifacts are properly bubbled up in the
+                                # final Task response metadata.
+                                filtered_data_parts = []
+                                has_deep_research_report = False
                                 for data_part in data_parts:
-                                    log.info(
-                                        "%s Received DataPart signal from peer for sub-task %s. Forwarding...",
-                                        component.log_identifier,
-                                        sub_task_id,
-                                    )
+                                    if isinstance(data_part.data, dict):
+                                        data_type = data_part.data.get("type")
+                                        if data_type == "artifact_creation_progress":
+                                            log.debug(
+                                                "%s Filtered out artifact_creation_progress DataPart from peer sub-task %s. Not forwarding to user.",
+                                                component.log_identifier,
+                                                sub_task_id,
+                                            )
+                                            continue
+                                        if data_type == "deep_research_report":
+                                            # Track that we've seen a deep research report
+                                            # This will be used to suppress text content in the final response
+                                            has_deep_research_report = True
+                                            log.info(
+                                                "%s Detected deep_research_report DataPart from peer sub-task %s. Will suppress text in final response.",
+                                                component.log_identifier,
+                                                sub_task_id,
+                                            )
+                                    filtered_data_parts.append(data_part)
+                                
+                                # Store the deep research report flag in correlation data for later use
+                                if has_deep_research_report:
+                                    main_logical_task_id_for_flag = original_task_context.get("logical_task_id")
+                                    with component.active_tasks_lock:
+                                        task_context_for_flag = component.active_tasks.get(main_logical_task_id_for_flag)
+                                        if task_context_for_flag:
+                                            # Store flag in task context to suppress text in final response
+                                            task_context_for_flag.set_flag("peer_sent_deep_research_report", True)
+                                            log.info(
+                                                "%s Set peer_sent_deep_research_report flag for task %s",
+                                                component.log_identifier,
+                                                main_logical_task_id_for_flag,
+                                            )
+
+                                # Only forward if there are non-filtered data parts
+                                if filtered_data_parts:
+                                    for data_part in filtered_data_parts:
+                                        log.info(
+                                            "%s Received DataPart signal from peer for sub-task %s. Forwarding...",
+                                            component.log_identifier,
+                                            sub_task_id,
+                                        )
 
-                                    forwarded_message = a2a.create_agent_parts_message(
-                                        parts=[data_part],
-                                        metadata=event_metadata,
-                                    )
+                                        forwarded_message = a2a.create_agent_parts_message(
+                                            parts=[data_part],
+                                            metadata=event_metadata,
+                                        )
 
-                                    forwarded_event = a2a.create_status_update(
-                                        task_id=main_logical_task_id,
-                                        context_id=main_context_id,
-                                        message=forwarded_message,
-                                        is_final=False,
-                                    )
-                                    if (
-                                        status_event.status
-                                        and status_event.status.timestamp
-                                    ):
-                                        forwarded_event.status.timestamp = (
-                                            status_event.status.timestamp
+                                        forwarded_event = a2a.create_status_update(
+                                            task_id=main_logical_task_id,
+                                            context_id=main_context_id,
+                                            message=forwarded_message,
+                                            is_final=False,
                                         )
-                                    _forward_jsonrpc_response(
-                                        component=component,
-                                        original_jsonrpc_request_id=original_jsonrpc_request_id,
-                                        result_data=forwarded_event,
-                                        target_topic=target_topic_for_forward,
-                                        main_logical_task_id=main_logical_task_id,
-                                        peer_agent_name=peer_agent_name,
-                                        message=message,
-                                    )
+                                        if (
+                                            status_event.status
+                                            and status_event.status.timestamp
+                                        ):
+                                            forwarded_event.status.timestamp = (
+                                                status_event.status.timestamp
+                                            )
+                                        _forward_jsonrpc_response(
+                                            component=component,
+                                            original_jsonrpc_request_id=original_jsonrpc_request_id,
+                                            result_data=forwarded_event,
+                                            target_topic=target_topic_for_forward,
+                                            main_logical_task_id=main_logical_task_id,
+                                            peer_agent_name=peer_agent_name,
+                                            message=message,
+                                        )
+                                    # Reset the timeout since we received a status update
+                                    await component.reset_peer_timeout(sub_task_id)
                                     return
+                                else:
+                                    log.debug(
+                                        "%s All DataParts from peer sub-task %s were filtered. Not forwarding.",
+                                        component.log_identifier,
+                                        sub_task_id,
+                                    )
 
                             payload_to_queue = status_event.model_dump(
                                 by_alias=True, exclude_none=True
@@ -1613,6 +1770,16 @@ async def handle_a2a_response(component, message: SolaceMessage):
                                             header_text=header_text,
                                         )
                                     )
+
+                                    # Add guidance about artifact_return responsibility
+                                    artifact_return_guidance = (
+                                        f"\n\n**Note:** If any of these artifacts fulfill the user's request, "
+                                        f"you should return them directly to the user using the "
+                                        f"{EMBED_DELIMITER_OPEN}artifact_return:filename:version{EMBED_DELIMITER_CLOSE} embed. "
+                                        f"This is more convenient for the user than just describing the artifacts. "
+                                        f"Replace 'filename' and 'version' with the actual values from the artifact metadata above."
+                                    )
+                                    artifact_summary += artifact_return_guidance
                                 else:
                                     log.warning(
                                         "%s Could not generate artifact summary: missing user_id or session_id in correlation data.",
@@ -1633,9 +1800,28 @@ async def handle_a2a_response(component, message: SolaceMessage):
             else:
                 final_text = str(payload_to_queue)
 
-            full_response_text = final_text
-            if artifact_summary:
-                full_response_text = f"{artifact_summary}\n\n{full_response_text}"
+            # Check if a deep research report was sent by the peer agent
+            # If so, suppress the verbose text but keep artifact info to use
+            peer_sent_deep_research = task_context.get_flag("peer_sent_deep_research_report", False)
+            if peer_sent_deep_research:
+                # Clear the flag after using it
+                task_context.set_flag("peer_sent_deep_research_report", False)
+                if artifact_summary:
+                    full_response_text = (
+                        f"{artifact_summary}\n---\n\n"
+                        "SUCCESS: Deep research task completed. The report has been delivered to the user "
+                        "and is being displayed. Use artifact_return to include the artifact reference "
+                        "in your response so users can click on it."
+                    )
+                else:
+                    full_response_text = (
+                        "SUCCESS: Deep research task completed successfully. "
+                        "The research report has been delivered to the user."
+                    )
+            else:
+                full_response_text = final_text
+                if artifact_summary:
+                    full_response_text = f"{artifact_summary}\n---\n\nPeer Agent Response:\n\n{full_response_text}"
 
             await _publish_peer_tool_result_notification(
                 component=component,