workflow-exec-engine 0.0.2__py3-none-any.whl

workflow_engine/client/engine_client.py

@@ -0,0 +1,374 @@
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# All Rights Reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+"""WorkflowEngineClient -- workflow-execution facade over A2ATransport.
+
+Single responsibility: the workflow execution send path. Owns the
+Task-T/Negotiation-T extension handler chain, the Negotiation-T
+auto-loop, the global EventCallback, and the ControlPoint wiring.
+All wire-level work (httpx, auth, SSE consumer) delegates to
+:class:`A2ATransport`.
+
+One-shot pre-positioning sends (Authorization-T / Notification-T) are
+a separate concern and live on :class:`ExtensionSender` -- callers
+that only need pre-positioning hold that lighter facade instead.
+"""
+
+import uuid
+import asyncio
+import time
+from typing import Dict, Any, List, Optional, Callable, Union, Awaitable
+from loguru import logger
+
+import httpx
+
+try:
+    from a2a.types import Task
+    _A2A_AVAILABLE = True
+except ImportError:
+    _A2A_AVAILABLE = False
+
+from workflow_engine.client.a2a_transport import A2ATransport
+from workflow_engine.client.auth_manager import AuthManager
+from workflow_engine.client.extension_handlers import ExtensionRegistry, ExtensionHandler
+from workflow_engine.client.protocol_logger import log_request, log_response
+from workflow_engine.control.control_points import (
+    EventCallback, EventType,
+)
+from workflow_engine.core.models import SendMessageResult
+from workflow_engine.client.extensions import A2ATExtension
+
+# Type alias for the negotiation resolver callback. May be sync (returning
+# str/None) or async (returning an awaitable of str/None). The SDK awaits
+# coroutine results automatically, so an `async def` resolver is supported.
+NegotiationResolver = Union[
+    Callable[[str, str, Dict[str, Any]], Optional[str]],
+    Callable[[str, str, Dict[str, Any]], Awaitable[Optional[str]]],
+]
+
+
+class WorkflowEngineClient:
+    """Workflow-execution send facade built on a shared :class:`A2ATransport`."""
+
+    def __init__(
+        self,
+        transport: A2ATransport,
+        custom_handlers: Optional[List[ExtensionHandler]] = None,
+        event_callback: Optional[EventCallback] = None,
+        max_negotiation_rounds: int = 3,
+    ):
+        self._transport = transport
+        self._extension_registry = ExtensionRegistry()
+        if custom_handlers:
+            for h in custom_handlers:
+                self._extension_registry.register(h)
+        self._control_point = None
+        self._event_callback = event_callback
+        self._max_negotiation_rounds = max_negotiation_rounds
+        logger.info(
+            f"[EngineClient] Initialized over transport "
+            f"({len(self._transport.agent_names)} agent(s)), "
+            f"max_neg={max_negotiation_rounds}"
+        )
+
+    # ------------------------------------------------------------------
+    # Wiring
+    # ------------------------------------------------------------------
+
+    def set_control_point(self, control_point):
+        self._control_point = control_point
+
+    def set_event_callback(self, callback):
+        """Attach an EventCallback so send_message emits agent_request/response."""
+        self._event_callback = callback
+
+    def _emit(self, event_type: str, data: Dict[str, Any]):
+        if self._event_callback:
+            self._event_callback.on_event(event_type, data)
+
+    def _forward_intermediate_event(self, event_type: str, data: Dict[str, Any]):
+        """Forward intermediate SSE events with structured logging (mirrors Java forwardIntermediateEvent)."""
+        agent = data.get("agent", "?")
+        if event_type == EventType.AGENT_STATUS_UPDATE:
+            state = data.get("state", "")
+            is_final = data.get("is_final", False)
+            logger.info(f"[EngineClient] Agent {agent} status update: {state} (final={is_final})")
+        elif event_type == EventType.AGENT_ARTIFACT_UPDATE:
+            art_name = data.get("artifact_name", "")
+            art_id = data.get("artifact_id", "")
+            logger.info(f"[EngineClient] Agent {agent} artifact update: {art_name} ({art_id})")
+        elif event_type == EventType.AGENT_MESSAGE_EVENT:
+            text = data.get("text", "")
+            logger.info(f"[EngineClient] Agent {agent} message event: {len(text)} chars")
+        self._emit(event_type, data)
+
+    def register_handler(self, handler: ExtensionHandler):
+        self._extension_registry.register(handler)
+
+    # ------------------------------------------------------------------
+    # Delegated transport accessors (for convenience)
+    # ------------------------------------------------------------------
+
+    @property
+    def agent_names(self) -> List[str]:
+        return self._transport.agent_names
+
+    @property
+    def httpx_client(self) -> httpx.AsyncClient:
+        return self._transport.httpx_client
+
+    def get_a2at_client(self):
+        return self._transport.get_a2at_client()
+
+    def get_card(self, agent_name: str):
+        return self._transport.get_card(agent_name)
+
+    def update_agent_cards(self, agent_cards: List[Any]):
+        self._transport.update_agent_cards(agent_cards)
+
+    async def close(self):
+        await self._transport.close()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()
+
+    # ------------------------------------------------------------------
+    # Workflow send path
+    # ------------------------------------------------------------------
+
+    async def send_message(
+        self,
+        agent_name: str,
+        message: str,
+        context_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        skip_extensions: bool = False,
+    ) -> SendMessageResult:
+        t_total = time.time()
+        agent_card = self._transport.get_card(agent_name)
+        if not agent_card:
+            logger.error(f"[EngineClient] Agent not found: {agent_name}")
+            raise RuntimeError(f"Agent not found: {agent_name}")
+        logger.info(f"[EngineClient] send_message to {agent_name}: {len(message)} chars")
+        if skip_extensions:
+            logger.info(f"[EngineClient] Skipping A2A-T extensions for {agent_name} (self-loop)")
+        else:
+            t_ext = time.time()
+            metadata = await self._run_before_send_handlers(agent_card, message, metadata)
+            logger.info(f"[Timing] Extensions before_send for {agent_name}: {time.time()-t_ext:.2f}s")
+        logger.info(f"[EngineClient] Emitting agent_request for {agent_name}")
+        self._emit(EventType.AGENT_REQUEST, {"agent": agent_name, "request": message, "metadata": metadata or {}})
+        client = self._transport.create_a2a_client(agent_card)
+        send_req = self._transport.build_send_request(message, context_id, metadata)
+        # Log full protocol request (endpoint + headers + body) after build, before send.
+        endpoint = "?"
+        if hasattr(agent_card, "supported_interfaces") and agent_card.supported_interfaces:
+            endpoint = agent_card.supported_interfaces[0].url or "?"
+        from google.protobuf.json_format import MessageToJson
+        try:
+            body_json = MessageToJson(send_req, ensure_ascii=False, indent=2)
+        except Exception:
+            body_json = str(send_req)
+        # Build HTTP header view: only real headers belong here, not message metadata.
+        # A2A-Extensions is derived from which extension URIs appear as metadata keys.
+        # Authorization is held by the credential service / auth interceptor at send time.
+        ext_uris = [k for k in (metadata or {}) if "tmforum.org" in k]
+        header_view = {}
+        if ext_uris:
+            header_view["A2A-Extensions"] = ",".join(ext_uris)
+        if agent_card.security_schemes and agent_card.security_requirements:
+            header_view["Authorization"] = "Bearer <injected-by-interceptor-at-send-time>"
+        log_request(agent_name, endpoint, body_json, header_view)
+
+        t_stream = time.time()
+        response_text, last_task, last_meta, task_state = (
+            await self._transport.consume_stream(client, send_req, self._forward_intermediate_event, agent_name)
+        )
+        logger.info(f"[Timing] A2A stream for {agent_name}: {time.time()-t_stream:.2f}s")
+
+        if response_text is None and last_task is not None:
+            response_text = str(last_task)
+
+        logger.info(f"[EngineClient] Response from {agent_name}: text={len(response_text or '')} chars, state={task_state}")
+        result = SendMessageResult(
+            text=response_text or "",
+            task=last_task,
+            metadata=last_meta,
+            task_state=task_state,
+        )
+        if skip_extensions:
+            self._emit(EventType.AGENT_RESPONSE, {"agent": agent_name, "response": result.text, "metadata": result.metadata or {}})
+            logger.info(f"[Timing] send_message to {agent_name} total: {time.time()-t_total:.2f}s")
+            return result
+        result = await self._run_after_receive_handlers(agent_card, result)
+        result = await self._auto_negotiate(agent_card, agent_name, message, context_id, result, 1)
+        logger.info(f"[Timing] send_message to {agent_name} total: {time.time()-t_total:.2f}s")
+        return result
+
+    # ------------------------------------------------------------------
+    # Auto-negotiation (integrated into send_message)
+    # ------------------------------------------------------------------
+
+    async def _auto_negotiate(
+        self, agent_card, agent_name, original_message,
+        context_id, result, round_num,
+    ) -> SendMessageResult:
+        if not self._is_negotiation_needed(result) or round_num > self._max_negotiation_rounds:
+            self._emit(EventType.AGENT_RESPONSE, {"agent": agent_name, "response": result.text, "metadata": result.metadata or {}})
+            return result
+        neg_meta = result.metadata or {}
+        neg_text = neg_meta.get("negotiation_message", "") or ""
+        logger.info(f"[Negotiation] Round {round_num} for '{agent_name}': {neg_text}")
+        self._emit(EventType.NEGOTIATION_REQUEST, {
+            "agent": agent_name, "round": round_num, "concern": neg_text,
+        })
+        if self._control_point is not None:
+            try:
+                clarification = self._control_point.on_negotiation(agent_name, neg_text, neg_meta)
+                if asyncio.iscoroutine(clarification):
+                    clarification = await clarification
+            except Exception as e:
+                logger.warning(f"[Negotiation] on_negotiation raised: {e}")
+                clarification = None
+        else:
+            clarification = "Please proceed with the original task using available information."
+        if not clarification:
+            self._emit(EventType.NEGOTIATION_FAILED, {
+                "agent": agent_name, "round": round_num, "reason": "no clarification",
+            })
+            self._emit(EventType.AGENT_RESPONSE, {"agent": agent_name, "response": result.text, "metadata": result.metadata or {}})
+            return result
+        logger.info(f"[Negotiation] Clarification for '{agent_name}' round {round_num}: {clarification}")
+        self._emit(EventType.NEGOTIATION_RESOLVED, {
+            "agent": agent_name, "round": round_num, "clarification": clarification,
+        })
+        follow_up = (
+            "[NEGOTIATION_RESOLUTION]\n"
+            "The engine has reviewed your negotiation request and provides "
+            "the following clarification:\n\n" + clarification + "\n\n"
+            "---\nOriginal Task:\n" + original_message + "\n\n"
+            "Please re-execute the task based on the clarification above."
+        )
+        follow_up_meta = await self._build_negotiation_follow_up_meta(
+            agent_name, neg_meta, clarification)
+        follow_up_meta = await self._run_before_send_handlers(agent_card, follow_up, follow_up_meta)
+        client = self._transport.create_a2a_client(agent_card)
+        send_req = self._transport.build_send_request(follow_up, context_id, follow_up_meta)
+        t_neg_stream = time.time()
+        logger.info(f"[Timing] Negotiation round {round_num} A2A stream to {agent_name}: starting")
+        response_text, last_task, last_meta, task_state = (
+            await self._transport.consume_stream(client, send_req, self._forward_intermediate_event, agent_name)
+        )
+        logger.info(f"[Timing] Negotiation round {round_num} A2A stream to {agent_name}: {time.time()-t_neg_stream:.2f}s")
+        if response_text is None and last_task is not None:
+            response_text = str(last_task)
+        r = SendMessageResult(
+            text=response_text or "", task=last_task,
+            metadata=last_meta, task_state=task_state,
+        )
+        r = await self._run_after_receive_handlers(agent_card, r)
+        return await self._auto_negotiate(agent_card, agent_name, original_message, context_id, r, round_num + 1)
+
+    async def _build_negotiation_follow_up_meta(
+        self, agent_name, neg_meta, clarification,
+    ):
+        """Build follow-up metadata, preferring SDK continue_negotiation.
+
+        Calls a2a-t-sdk continue_negotiation to generate a structured
+        Negotiation-T payload (with DATA-NEGOTIATION-T context). Falls
+        back to manual metadata construction when the SDK is unavailable
+        or the negotiation context is missing.
+        """
+        a2at_client = self._transport.get_a2at_client()
+        if a2at_client:
+            try:
+                receive_result = neg_meta.get("negotiation_context")
+                if isinstance(receive_result, dict):
+                    context_dict = receive_result.get("context")
+                    if isinstance(context_dict, dict):
+                        from a2a_t.negotiation.common.models import (
+                            ContinueNegotiationInput, NegotiationContext,
+                        )
+                        from a2a_t.negotiation.common.enums import NegotiationStatus
+                        context = NegotiationContext.from_context(context_dict)
+                        input_obj = ContinueNegotiationInput(
+                            context=context,
+                            status=NegotiationStatus.AGREED,
+                            content_text=clarification,
+                        )
+                        payload = await asyncio.to_thread(a2at_client.continue_negotiation, input_obj)
+                        logger.info(
+                            f"[Negotiation] SDK continue_negotiation payload "
+                            f"for '{agent_name}': round {context.round} -> AGREED"
+                        )
+                        return dict(payload)
+            except Exception as e:
+                logger.warning(
+                    f"[Negotiation] continue_negotiation failed for "
+                    f"'{agent_name}': {e}; using fallback"
+                )
+        return {
+            A2ATExtension.NEGOTIATION_T.uri:
+                "## Data Return Confirmation\n" + clarification + "\n",
+        }
+    # ------------------------------------------------------------------
+    # Extension handler chain
+    # ------------------------------------------------------------------
+
+    async def _run_before_send_handlers(
+        self, agent_card, message: str,
+        preset_metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        metadata: Dict[str, Any] = dict(preset_metadata) if preset_metadata else {}
+        ext_uris = self._transport._get_extensions(agent_card)
+        handlers = self._extension_registry.get_handlers_for_extensions(ext_uris)
+        agent_name = getattr(agent_card, "name", "?")
+        for handler in handlers:
+            t_h = time.time()
+            metadata = await handler.before_send(
+                agent_card, message, metadata,
+                self._transport.get_a2at_client(), self._control_point,
+            )
+            logger.info(
+                f"[Timing] Handler {type(handler).__name__}.before_send "
+                f"for {agent_name}: {time.time()-t_h:.2f}s"
+            )
+        return metadata
+
+    async def _run_after_receive_handlers(
+        self, agent_card, result: SendMessageResult,
+    ) -> SendMessageResult:
+        ext_uris = self._transport._get_extensions(agent_card)
+        handlers = self._extension_registry.get_handlers_for_extensions(ext_uris)
+        for handler in handlers:
+            result = await handler.after_receive(
+                agent_card, result,
+                self._transport.get_a2at_client(), self._control_point,
+                self._event_callback,
+            )
+        return result
+
+    # ------------------------------------------------------------------
+    # Negotiation helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _is_negotiation_needed(result: SendMessageResult) -> bool:
+        return bool(result.task_state and "INPUT_REQUIRED" in result.task_state)

workflow_engine/client/env_file_loader.py

@@ -0,0 +1,68 @@
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# All Rights Reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+"""Loads key-value pairs from a ``.env`` file into ``os.environ``.
+
+Only sets keys that are not already present in the OS environment. This
+bridges the gap between the A2A-T SDK's internal ``.env`` loading and
+engine components that read configuration values like ``A2AT_CRED_KEY``.
+Mirrors the Java SDK's ``EnvFileLoader``.
+"""
+
+import os
+from pathlib import Path
+from typing import Optional, Union
+
+from loguru import logger
+
+
+def load_to_environ(env_file_path: Optional[Union[str, Path]]) -> int:
+    """Parse a ``.env`` file and set each key as an env var unless already set.
+
+    Returns the number of keys loaded.
+    """
+    if env_file_path is None:
+        return 0
+    p = Path(env_file_path)
+    if not p.exists():
+        logger.debug(f"[EnvLoader] File not found: {p}")
+        return 0
+    try:
+        lines = p.read_text(encoding="utf-8").splitlines()
+    except Exception as e:
+        logger.warning(f"[EnvLoader] Failed to read {p}: {e}")
+        return 0
+    count = 0
+    for line in lines:
+        trimmed = line.strip()
+        if not trimmed or trimmed.startswith("#"):
+            continue
+        eq = trimmed.find("=")
+        if eq <= 0:
+            continue
+        key = trimmed[:eq].strip()
+        value = trimmed[eq + 1:].strip()
+        # Strip surrounding quotes
+        if len(value) >= 2 and value.startswith('"') and value.endswith('"'):
+            value = value[1:-1]
+        if key in os.environ:
+            continue
+        os.environ[key] = value
+        count += 1
+    if count > 0:
+        logger.info(f"[EnvLoader] Loaded {count} env var(s) from {p}")
+    return count

workflow_engine/client/extension_handlers.py

@@ -0,0 +1,197 @@
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# All Rights Reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+"""Extension handler registry for A2A-T extensions (SDK-internal).
+
+The in-workflow handler chain registers Task-T and Negotiation-T. Task-T
+generates the structured task prompt on send; Negotiation-T extracts the
+negotiation context on receive and feeds the auto-loop.
+
+Authorization-T and Notification-T are pre-positioning concerns handled
+once before the workflow starts via ExtensionSender, not part of this
+in-workflow handler chain.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional, List, TYPE_CHECKING
+from loguru import logger
+
+if TYPE_CHECKING:
+    from workflow_engine.control.control_points import ControlPoint
+
+from workflow_engine.core.models import SendMessageResult
+
+
+class ExtensionHandler(ABC):
+    extension_keyword: str = ""
+
+    @abstractmethod
+    async def before_send(self, agent_card, message_text, metadata,
+                          a2at_client=None, control_point=None) -> Dict[str, Any]:
+        ...
+
+    @abstractmethod
+    async def after_receive(self, agent_card, result, a2at_client=None,
+                            control_point=None, event_callback=None) -> SendMessageResult:
+        ...
+
+
+class TaskTHandler(ExtensionHandler):
+    extension_keyword = "Task-T"
+
+    def __init__(self):
+        self._prompt_cache: Dict[str, str] = {}
+
+    async def before_send(self, agent_card, message_text, metadata, a2at_client=None, control_point=None):
+        if not a2at_client:
+            return metadata
+        if "[NEGOTIATION_RESOLUTION]" in message_text:
+            logger.info("[Task-T] Skipping prompt generation for negotiation follow-up")
+            return metadata
+        task_t_uri = None
+        extensions = getattr(getattr(agent_card, "capabilities", None), "extensions", None) or []
+        for ext in extensions:
+            uri = getattr(ext, "uri", "") or ""
+            if "Task-T" in uri:
+                task_t_uri = uri
+                break
+        if not task_t_uri:
+            return metadata
+        if task_t_uri in metadata:
+            logger.info(f"[Task-T] Metadata already preset, skipping generation")
+            return metadata
+        cache_key = message_text
+        if cache_key in self._prompt_cache:
+            cached = self._prompt_cache[cache_key]
+            metadata[task_t_uri] = cached
+            logger.info(
+                f"[Task-T] Cache hit for '{getattr(agent_card, 'name', '?')}', "
+                f"{len(cached)} chars"
+            )
+            return metadata
+        try:
+            import asyncio
+            prompt_result = await asyncio.to_thread(a2at_client.generate_task_prompt, message_text)
+            if hasattr(prompt_result, "success") and prompt_result.success:
+                if hasattr(prompt_result, "prompt_text") and prompt_result.prompt_text:
+                    metadata[task_t_uri] = prompt_result.prompt_text
+                    self._prompt_cache[cache_key] = prompt_result.prompt_text
+                    logger.info(f"[Task-T] Generated prompt for '{getattr(agent_card, 'name', '?')}', {len(prompt_result.prompt_text)} chars")
+                    logger.debug(f"[Task-T] Prompt content: [{prompt_result.prompt_text}]")
+            else:
+                failure = getattr(prompt_result, "failure", None)
+                if failure:
+                    logger.warning(f"[Task-T] Prompt generation failed: {getattr(failure, 'message', '')}")
+                    logger.info(f"[Task-T] Failure detail: {failure}")
+        except Exception as e:
+            logger.warning(f"[Task-T] Failed: {e}")
+        return metadata
+
+    async def after_receive(self, agent_card, result, a2at_client=None, control_point=None, event_callback=None):
+        return result
+
+
+class NegotiationTHandler(ExtensionHandler):
+    extension_keyword = "Negotiation-T"
+
+    async def before_send(self, agent_card, message_text, metadata, a2at_client=None, control_point=None):
+        return metadata
+
+    async def after_receive(self, agent_card, result, a2at_client=None, control_point=None, event_callback=None):
+        if not a2at_client:
+            return result
+        if not result.task_state or "INPUT_REQUIRED" not in result.task_state:
+            return result
+        extensions = getattr(getattr(agent_card, "capabilities", None), "extensions", None) or []
+        supports_neg = any("NEGOTIATION-T" in (getattr(ext, "uri", "") or "") for ext in extensions)
+        if not supports_neg:
+            return result
+        metadata = dict(result.metadata) if result.metadata else {}
+        context_map = self._extract_negotiation_context(metadata)
+        if context_map is None:
+            context_map = metadata
+        try:
+            import asyncio as _aio
+            receive_result = await _aio.to_thread(
+                a2at_client.receive_negotiation, message=result.text, context=context_map)
+            if receive_result.get("needResponse", False):
+                result.metadata["negotiation_message"] = receive_result.get("message", "")
+                result.metadata["negotiation_context"] = receive_result
+                logger.info(f"[Negotiation-T] Agent '{getattr(agent_card, 'name', '?')}' requested negotiation: {result.metadata['negotiation_message']}")
+        except Exception as e:
+            msg = str(e) if e else ""
+            if "Unsupported negotiation type" in msg:
+                logger.debug(f"[Negotiation-T] SDK receiveNegotiation unavailable for '{getattr(agent_card, 'name', '?')}' ({msg}), using fallback")
+            else:
+                logger.warning(f"[Negotiation-T] receiveNegotiation failed for '{getattr(agent_card, 'name', '?')}': {msg}, using fallback")
+            fallback_text = self._extract_negotiation_text(metadata)
+            if fallback_text:
+                result.metadata["negotiation_message"] = fallback_text
+                logger.info(f"[Negotiation-T] Agent '{getattr(agent_card, 'name', '?')}' requested negotiation (fallback): {fallback_text}")
+        result.metadata = metadata
+        return result
+
+    @staticmethod
+    def _extract_negotiation_context(metadata):
+        if not metadata:
+            return None
+        for key, value in metadata.items():
+            if "DATA-NEGOTIATION-T" in str(key) and isinstance(value, dict):
+                return value
+        return None
+
+    @staticmethod
+    def _extract_negotiation_text(metadata):
+        if not metadata:
+            return None
+        for key, value in metadata.items():
+            key_str = str(key)
+            if "NEGOTIATION-T" in key_str and "DATA-NEGOTIATION-T" not in key_str and isinstance(value, str):
+                return value
+        return None
+
+
+class ExtensionRegistry:
+    """Registry of in-workflow extension handlers.
+
+    Pre-registers the Task-T and Negotiation-T handlers, which participate
+    in every send_message lifecycle. Authorization-T / Notification-T are
+    excluded by design: they are one-shot pre-positioning operations
+    (see ExtensionSender), not in-workflow handlers.
+    """
+
+    def __init__(self):
+        self._handlers: Dict[str, ExtensionHandler] = {}
+        self.register(TaskTHandler())
+        self.register(NegotiationTHandler())
+
+    def register(self, handler: ExtensionHandler):
+        self._handlers[handler.extension_keyword] = handler
+
+    def get_handlers_for_extensions(self, extension_uris: List[str]) -> List[ExtensionHandler]:
+        matched = []
+        seen = set()
+        for uri in extension_uris:
+            for keyword, handler in self._handlers.items():
+                # Case-insensitive match: extension URIs commonly use
+                # uppercase (e.g. "NEGOTIATION-T") while the handler keyword
+                # uses mixed case ("Negotiation-T").
+                if keyword.lower() in uri.lower() and keyword not in seen:
+                    matched.append(handler)
+                    seen.add(keyword)
+                    break
+        return matched