glaip-sdk 0.6.10__py3-none-any.whl → 0.7.27__py3-none-any.whl

glaip_sdk/runner/langgraph.py

@@ -1,3 +1,4 @@
+# pylint: disable=duplicate-code
 """LangGraph-based runner for local agent execution.
 
 This module provides the LangGraphRunner which executes glaip-sdk agents
@@ -19,26 +20,64 @@ from __future__ import annotations
 
 import asyncio
 import inspect
+import logging
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
 
+from gllm_core.utils import LoggerManager
+
+from glaip_sdk.client.run_rendering import AgentRunRenderingManager
+from glaip_sdk.hitl import PauseResumeCallback
+from glaip_sdk.models import DEFAULT_MODEL
 from glaip_sdk.runner.base import BaseRunner
 from glaip_sdk.runner.deps import (
     check_local_runtime_available,
     get_local_runtime_missing_message,
 )
-from glaip_sdk.utils.a2a import A2AEventStreamProcessor
-from gllm_core.utils import LoggerManager
+from glaip_sdk.runner.ptc_adapter import (
+    normalize_ptc_for_aip_agents,
+    validate_ptc_for_local_run,
+)
+from glaip_sdk.utils.tool_storage_provider import build_tool_output_manager
 
 if TYPE_CHECKING:
     from langchain_core.messages import BaseMessage
 
     from glaip_sdk.agents.base import Agent
 
+
+_AIP_LOGS_SWALLOWED = False
+
+
+def _swallow_aip_logs(level: int = logging.ERROR) -> None:
+    """Consume noisy AIPAgents logs once (opt-in via runner flag)."""
+    global _AIP_LOGS_SWALLOWED
+    if _AIP_LOGS_SWALLOWED:
+        return
+    prefixes = ("aip_agents.",)
+
+    def _silence(name: str) -> None:
+        lg = logging.getLogger(name)
+        lg.handlers = [logging.NullHandler()]
+        lg.propagate = False
+        lg.setLevel(level)
+
+    # Silence any already-registered loggers under the given prefixes
+    for logger_name in logging.root.manager.loggerDict:
+        if any(logger_name.startswith(prefix) for prefix in prefixes):
+            _silence(logger_name)
+
+    # Also set the base prefix loggers so future children inherit silence
+    for prefix in prefixes:
+        _silence(prefix.rstrip("."))
+    _AIP_LOGS_SWALLOWED = True
+
+
 logger = LoggerManager().get_logger(__name__)
 
-# Default A2A event processor
-_event_processor = A2AEventStreamProcessor()
+
+# Constants for MCP configuration validation
+_MCP_TRANSPORT_KEYS = {"url", "command", "args", "env", "timeout", "headers"}
 
 
 def _convert_chat_history_to_messages(
@@ -56,7 +95,11 @@ def _convert_chat_history_to_messages(
     if not chat_history:
         return []
 
-    from langchain_core.messages import AIMessage, HumanMessage, SystemMessage  # noqa: PLC0415
+    from langchain_core.messages import (  # noqa: PLC0415
+        AIMessage,
+        HumanMessage,
+        SystemMessage,
+    )
 
     messages: list[BaseMessage] = []
     for msg in chat_history:
@@ -81,16 +124,17 @@ def _convert_chat_history_to_messages(
 class LangGraphRunner(BaseRunner):
     """Runner implementation using aip-agents LangGraphReactAgent.
 
-    MVP scope:
-    - Execute via `LangGraphReactAgent.arun_a2a_stream()`
-    - Extract and return final text from the emitted `final_response` event
+    Current behavior:
+    - Execute via `LangGraphReactAgent.arun_sse_stream()` (normalized SSE-compatible stream)
+    - Route all events through `AgentRunRenderingManager.async_process_stream_events`
+      for unified rendering between local and remote agents
 
     Attributes:
         default_model: Model name to use when agent.model is not set.
             Defaults to "gpt-4o-mini".
     """
 
-    default_model: str = "openai/gpt-4o-mini"
+    default_model: str = DEFAULT_MODEL
 
     def run(
         self,
@@ -99,6 +143,8 @@ class LangGraphRunner(BaseRunner):
         verbose: bool = False,
         runtime_config: dict[str, Any] | None = None,
         chat_history: list[dict[str, str]] | None = None,
+        *,
+        swallow_aip_logs: bool = True,
         **kwargs: Any,
     ) -> str:
         """Execute agent synchronously and return final response text.
@@ -113,6 +159,9 @@ class LangGraphRunner(BaseRunner):
             chat_history: Optional list of prior conversation messages.
                 Each message is a dict with "role" and "content" keys.
                 Defaults to None.
+            swallow_aip_logs: When True (default), silence noisy logs from aip-agents,
+                gllm_inference, OpenAILMInvoker, and httpx. Set to False to honor user
+                logging configuration.
             **kwargs: Additional keyword arguments passed to the backend.
 
         Returns:
@@ -141,6 +190,7 @@ class LangGraphRunner(BaseRunner):
             verbose=verbose,
             runtime_config=runtime_config,
             chat_history=chat_history,
+            swallow_aip_logs=swallow_aip_logs,
             **kwargs,
         )
 
@@ -153,6 +203,8 @@ class LangGraphRunner(BaseRunner):
         verbose: bool = False,
         runtime_config: dict[str, Any] | None = None,
         chat_history: list[dict[str, str]] | None = None,
+        *,
+        swallow_aip_logs: bool = True,
         **kwargs: Any,
     ) -> str:
         """Execute agent asynchronously and return final response text.
@@ -167,6 +219,7 @@ class LangGraphRunner(BaseRunner):
             chat_history: Optional list of prior conversation messages.
                 Each message is a dict with "role" and "content" keys.
                 Defaults to None.
+            swallow_aip_logs: When True (default), silence noisy AIPAgents logs.
             **kwargs: Additional keyword arguments passed to the backend.
 
         Returns:
@@ -181,6 +234,7 @@ class LangGraphRunner(BaseRunner):
             verbose=verbose,
             runtime_config=runtime_config,
             chat_history=chat_history,
+            swallow_aip_logs=swallow_aip_logs,
             **kwargs,
         )
 
@@ -191,6 +245,8 @@ class LangGraphRunner(BaseRunner):
         verbose: bool = False,
         runtime_config: dict[str, Any] | None = None,
         chat_history: list[dict[str, str]] | None = None,
+        *,
+        swallow_aip_logs: bool = True,
         **kwargs: Any,
     ) -> str:
         """Internal async implementation of agent execution.
@@ -201,13 +257,25 @@ class LangGraphRunner(BaseRunner):
             verbose: If True, emit debug trace output during execution.
             runtime_config: Optional runtime configuration for tools, MCPs, etc.
             chat_history: Optional list of prior conversation messages.
+            swallow_aip_logs: When True (default), silence noisy AIPAgents logs.
             **kwargs: Additional keyword arguments passed to the backend.
 
         Returns:
             The final response text from the agent.
         """
+        # Optionally swallow noisy AIPAgents logs
+        if swallow_aip_logs:
+            _swallow_aip_logs()
+
+        # POC/MVP: Create pause/resume callback for interactive HITL input
+        pause_resume_callback = PauseResumeCallback()
+
         # Build the local LangGraphReactAgent from the glaip_sdk Agent
-        local_agent = self.build_langgraph_agent(agent, runtime_config=runtime_config)
+        local_agent = self.build_langgraph_agent(
+            agent,
+            runtime_config=runtime_config,
+            pause_resume_callback=pause_resume_callback,
+        )
 
         # Convert chat history to LangChain messages for the agent
         langchain_messages = _convert_chat_history_to_messages(chat_history)
@@ -219,20 +287,68 @@ class LangGraphRunner(BaseRunner):
                 agent.name,
             )
 
-        # Collect A2AEvents from the stream and extract final response
-        events: list[dict[str, Any]] = []
+        # Use shared render manager for unified processing
+        render_manager = AgentRunRenderingManager(logger)
+        renderer = render_manager.create_renderer(kwargs.get("renderer"), verbose=verbose)
+
+        # POC/MVP: Set renderer on callback so LocalPromptHandler can pause/resume Live
+        pause_resume_callback.set_renderer(renderer)
+
+        meta = render_manager.build_initial_metadata(agent.name, message, kwargs)
+        render_manager.start_renderer(renderer, meta)
+
+        try:
+            # Use shared async stream processor for unified event handling
+            (
+                final_text,
+                stats_usage,
+                started_monotonic,
+                finished_monotonic,
+            ) = await render_manager.async_process_stream_events(
+                local_agent.arun_sse_stream(message, **kwargs),
+                renderer,
+                meta,
+                skip_final_render=True,
+            )
+        except KeyboardInterrupt:
+            try:
+                renderer.close()
+            finally:
+                raise
+        except Exception:
+            try:
+                renderer.close()
+            finally:
+                raise
+        finally:
+            # Cleanup PTC sandbox and MCP sessions
+            # Isolated cleanup steps so one failure doesn't skip the other
+            try:
+                await local_agent.cleanup()
+            except Exception as e:
+                logger.warning("Failed to cleanup agent resources: %s", e)
 
-        async for event in local_agent.arun_a2a_stream(message, **kwargs):
-            if verbose:
-                self._log_event(event)
-            events.append(event)
+        # Use shared finalizer to avoid code duplication
+        from glaip_sdk.client.run_rendering import (  # noqa: PLC0415
+            finalize_render_manager,
+        )
 
-        return _event_processor.extract_final_response(events)
+        return finalize_render_manager(
+            render_manager,
+            renderer,
+            final_text,
+            stats_usage,
+            started_monotonic,
+            finished_monotonic,
+        )
 
     def build_langgraph_agent(
         self,
         agent: Agent,
         runtime_config: dict[str, Any] | None = None,
+        shared_tool_output_manager: Any | None = None,
+        *,
+        pause_resume_callback: Any | None = None,
     ) -> Any:
         """Build a LangGraphReactAgent from a glaip_sdk Agent definition.
 
@@ -240,6 +356,10 @@ class LangGraphRunner(BaseRunner):
             agent: The glaip_sdk Agent to convert.
             runtime_config: Optional runtime configuration with tool_configs,
                 mcp_configs, agent_config, and agent-specific overrides.
+            shared_tool_output_manager: Optional ToolOutputManager to reuse across
+                agents with tool_output_sharing enabled.
+            pause_resume_callback: Optional callback used to pause/resume the renderer
+                during interactive HITL prompts.
 
         Returns:
             A configured LangGraphReactAgent instance.
@@ -249,6 +369,7 @@ class LangGraphRunner(BaseRunner):
             ValueError: If agent has unsupported tools, MCPs, or sub-agents for local mode.
         """
         from aip_agents.agent import LangGraphReactAgent  # noqa: PLC0415
+
         from glaip_sdk.runner.tool_adapter import LangChainToolAdapter  # noqa: PLC0415
 
         # Adapt tools for local execution
@@ -260,9 +381,6 @@ class LangGraphRunner(BaseRunner):
             adapter = LangChainToolAdapter()
             langchain_tools = adapter.adapt_tools(agent.tools)
 
-        # Build sub-agents recursively
-        sub_agent_instances = self._build_sub_agents(agent.agents, runtime_config)
-
         # Normalize runtime config: merge global and agent-specific configs
         normalized_config = self._normalize_runtime_config(runtime_config, agent)
 
@@ -276,15 +394,42 @@ class LangGraphRunner(BaseRunner):
         merged_agent_config = self._merge_agent_config(agent, normalized_config)
         agent_config_params, agent_config_kwargs = self._apply_agent_config(merged_agent_config)
 
-        # Build the LangGraphReactAgent with tools, sub-agents, and configs
+        # Validate and normalize PTC configuration for local runs
+        ptc_config = validate_ptc_for_local_run(
+            agent_ptc=agent.ptc if hasattr(agent, "ptc") else None,
+            agent_config_ptc=None,  # Already validated in _merge_agent_config
+            runtime_config_ptc=None,  # Already validated in _normalize_runtime_config
+        )
+        normalized_ptc = normalize_ptc_for_aip_agents(ptc_config)
+
+        # Resolve model and merge its configuration into agent kwargs
+        model_string = self._resolve_local_model(agent, agent_config_kwargs)
+
+        tool_output_manager = self._resolve_tool_output_manager(
+            agent,
+            merged_agent_config,
+            shared_tool_output_manager,
+        )
+
+        # Build sub-agents recursively, sharing tool output manager when enabled.
+        sub_agent_instances = self._build_sub_agents(
+            agent.agents,
+            runtime_config,
+            shared_tool_output_manager=tool_output_manager,
+        )
+
+        # Build the LangGraphReactAgent with tools, sub-agents, configs, and PTC
         local_agent = LangGraphReactAgent(
             name=agent.name,
             instruction=agent.instruction,
             description=agent.description,
-            model=agent.model or self.default_model,
+            model=model_string,
             tools=langchain_tools,
             agents=sub_agent_instances if sub_agent_instances else None,
             tool_configs=tool_configs if tool_configs else None,
+            tool_output_manager=tool_output_manager,
+            guardrail=agent.guardrail,
+            ptc_config=normalized_ptc,
             **agent_config_params,
             **agent_config_kwargs,
         )
@@ -292,6 +437,11 @@ class LangGraphRunner(BaseRunner):
         # Add MCP servers if configured
         self._add_mcp_servers(local_agent, agent, mcp_configs)
 
+        # Inject local HITL manager only if hitl_enabled is True (master switch).
+        # This matches remote behavior: hitl_enabled gates the HITL plumbing.
+        # Tool-level HITL configs are only enforced when hitl_enabled=True.
+        self._inject_hitl_manager(local_agent, merged_agent_config, agent.name, pause_resume_callback)
+
         logger.debug(
             "Built local LangGraphReactAgent for agent '%s' with %d tools, %d sub-agents, and %d MCPs",
             agent.name,
@@ -301,16 +451,72 @@ class LangGraphRunner(BaseRunner):
         )
         return local_agent
 
+    def _resolve_tool_output_manager(
+        self,
+        agent: Agent,
+        merged_agent_config: dict[str, Any],
+        shared_tool_output_manager: Any | None,
+    ) -> Any | None:
+        """Resolve tool output manager for local agent execution."""
+        tool_output_sharing_enabled = merged_agent_config.get("tool_output_sharing", False)
+        if not tool_output_sharing_enabled:
+            return None
+        if shared_tool_output_manager is not None:
+            return shared_tool_output_manager
+        return build_tool_output_manager(agent.name, merged_agent_config)
+
+    def _inject_hitl_manager(
+        self,
+        local_agent: Any,
+        merged_agent_config: dict[str, Any],
+        agent_name: str,
+        pause_resume_callback: Any | None,
+    ) -> None:
+        """Inject HITL manager when enabled, mirroring remote gating behavior."""
+        hitl_enabled = merged_agent_config.get("hitl_enabled", False)
+        if hitl_enabled:
+            try:
+                from aip_agents.agent.hitl.manager import (  # noqa: PLC0415
+                    ApprovalManager,
+                )
+
+                from glaip_sdk.hitl import LocalPromptHandler  # noqa: PLC0415
+
+                local_agent.hitl_manager = ApprovalManager(
+                    prompt_handler=LocalPromptHandler(pause_resume_callback=pause_resume_callback)
+                )
+                # Store callback reference for setting renderer later
+                if pause_resume_callback:
+                    local_agent._pause_resume_callback = pause_resume_callback
+                logger.debug(
+                    "HITL manager injected for agent '%s' (hitl_enabled=True)",
+                    agent_name,
+                )
+            except ImportError as e:
+                # Missing dependencies - fail fast
+                raise ImportError("Local HITL requires aip_agents. Install with: pip install 'glaip-sdk[local]'") from e
+            except Exception as e:
+                # Other errors during HITL setup - fail fast
+                raise RuntimeError(f"Failed to initialize HITL manager for agent '{agent_name}'") from e
+        else:
+            logger.debug(
+                "HITL manager not injected for agent '%s' (hitl_enabled=False)",
+                agent_name,
+            )
+
     def _build_sub_agents(
         self,
         sub_agents: list[Any] | None,
         runtime_config: dict[str, Any] | None,
+        shared_tool_output_manager: Any | None = None,
     ) -> list[Any]:
         """Build sub-agent instances recursively.
 
         Args:
             sub_agents: List of sub-agent definitions.
             runtime_config: Runtime config to pass to sub-agents.
+            shared_tool_output_manager: Optional ToolOutputManager to reuse across
+                agents with tool_output_sharing enabled.
 
         Returns:
             List of built sub-agent instances.
@@ -324,7 +530,13 @@ class LangGraphRunner(BaseRunner):
         sub_agent_instances = []
         for sub_agent in sub_agents:
             self._validate_sub_agent_for_local_mode(sub_agent)
-            sub_agent_instances.append(self.build_langgraph_agent(sub_agent, runtime_config))
+            sub_agent_instances.append(
+                self.build_langgraph_agent(
+                    sub_agent,
+                    runtime_config,
+                    shared_tool_output_manager=shared_tool_output_manager,
+                )
+            )
         return sub_agent_instances
 
     def _add_mcp_servers(
@@ -385,6 +597,14 @@ class LangGraphRunner(BaseRunner):
         if not runtime_config:
             return {}
 
+        # Check for unsupported runtime_config.ptc (v1 constraint)
+        if "ptc" in runtime_config:
+            validate_ptc_for_local_run(
+                agent_ptc=None,
+                agent_config_ptc=None,
+                runtime_config_ptc=runtime_config["ptc"],
+            )
+
         # 1. Extract global configs and normalize keys
         global_tool_configs = normalize_local_config_keys(runtime_config.get("tool_configs", {}))
         global_mcp_configs = normalize_local_config_keys(runtime_config.get("mcp_configs", {}))
@@ -544,6 +764,14 @@ class LangGraphRunner(BaseRunner):
         # Get runtime agent_config
         runtime_agent_config = normalized_config.get("agent_config", {})
 
+        # Check for unsupported agent_config.ptc (local runs constraint)
+        if "ptc" in agent_agent_config or "ptc" in runtime_agent_config:
+            validate_ptc_for_local_run(
+                agent_ptc=None,
+                agent_config_ptc=agent_agent_config.get("ptc") or runtime_agent_config.get("ptc"),
+                runtime_config_ptc=None,
+            )
+
         # Merge: agent definition < runtime config
         return merge_configs(agent_agent_config, runtime_agent_config)
 
@@ -566,12 +794,20 @@ class LangGraphRunner(BaseRunner):
         """
         direct_params = {}
         kwargs_params = {}
+        config_dict = {}
 
         # Direct constructor parameters
         if "planning" in agent_config:
             direct_params["planning"] = agent_config["planning"]
 
+        if "enable_a2a_token_streaming" in agent_config:
+            direct_params["enable_a2a_token_streaming"] = agent_config["enable_a2a_token_streaming"]
+
         # Kwargs parameters (passed through **kwargs to BaseAgent)
+        if "enable_pii" in agent_config:
+            kwargs_params["enable_pii"] = agent_config["enable_pii"]
+            config_dict["enable_pii"] = agent_config["enable_pii"]
+
         if "memory" in agent_config:
             # Map "memory" to "memory_backend" for aip-agents compatibility
             kwargs_params["memory_backend"] = agent_config["memory"]
@@ -582,8 +818,73 @@ class LangGraphRunner(BaseRunner):
             if key in agent_config:
                 kwargs_params[key] = agent_config[key]
 
+        # Ensure we pass a config dictionary to BaseAgent, which uses it for
+        # LM configuration (api keys, etc.). Memory settings are passed only
+        # via kwargs to avoid leaking into LM invoker config.
+        if config_dict:
+            kwargs_params["config"] = config_dict
+
         return direct_params, kwargs_params
 
+    def _convert_model_for_local(self, model: Any) -> tuple[str, dict[str, Any]]:
+        """Convert model to aip_agents format for local execution.
+
+        Args:
+            model: Model object or string identifier.
+
+        Returns:
+            Tuple of (model_string, config_dict).
+        """
+        from glaip_sdk.models._validation import (  # noqa: PLC0415
+            convert_model_for_local_execution,
+        )
+
+        return convert_model_for_local_execution(model)
+
+    def _resolve_local_model(self, agent: Agent, agent_config_kwargs: dict[str, Any]) -> str:
+        """Resolve model string and merge its configuration into agent kwargs.
+
+        This method extracts model-specific credentials and hyperparameters from a Model
+        object and merges them into the 'config' dictionary within agent_config_kwargs.
+        This is required because BaseAgent expects LM settings (api keys, etc.) to be
+        inside the 'config' parameter, not top-level kwargs.
+
+        Example:
+            If agent has:
+                - model = Model(id="deepinfra/model", credentials="key-123")
+                - agent_config_kwargs = {"enable_pii": True, "config": {"enable_pii": True}}
+
+            _resolve_local_model will:
+                1. Resolve model_string to "openai-compatible/model"
+                2. Extract model_config as {"lm_api_key": "key-123"}
+                3. Update agent_config_kwargs["config"] to:
+                   {"enable_pii": True, "lm_api_key": "key-123"}
+
+        Args:
+            agent: The glaip_sdk Agent.
+            agent_config_kwargs: Agent config kwargs to update (modified in-place).
+
+        Returns:
+            The model identifier string for local execution.
+        """
+        model_to_use = agent.model or self.default_model
+        model_string, model_config = self._convert_model_for_local(model_to_use)
+
+        if model_config:
+            # Normalize config to a dict early to simplify merging
+            config_val = agent_config_kwargs.get("config", {})
+            if hasattr(config_val, "model_dump"):
+                config_val = config_val.model_dump()
+
+            if not isinstance(config_val, dict):
+                config_val = {}
+
+            # Use a single merge path for model configuration
+            config_val.update(model_config)
+            agent_config_kwargs["config"] = config_val
+
+        return model_string
+
     def _apply_runtime_mcp_configs(
         self,
         base_configs: dict[str, Any],
@@ -612,39 +913,126 @@ class LangGraphRunner(BaseRunner):
         base_config: dict[str, Any],
         override: dict[str, Any] | None,
     ) -> dict[str, Any]:
-        """Merge a single MCP config with runtime override.
+        """Merge a single MCP config with a runtime override, handling normalization and parity fixes.
+
+        This method orchestrates the merging of base MCP settings (from the object definition)
+        with runtime overrides. It enforces Platform parity by prioritizing the nested 'config'
+        block while maintaining robustness for local development by auto-fixing flat transport keys.
+
+        The merge follows these priority rules (highest to lowest):
+        1. Misplaced flat keys in the override (e.g., 'url' at top level) - Auto-fixed with warning.
+        2. Nested 'config' block in the override (Matches Platform/Constructor schema).
+        3. Authentication objects in the override (Converted to HTTP headers).
+        4. Structural settings in the override (e.g., 'allowed_tools').
+        5. Base configuration from the MCP object definition.
+
+        Examples:
+            >>> # 1. Strict Nested Style (Recommended)
+            >>> override = {"config": {"url": "https://new.api"}, "allowed_tools": ["t1"]}
+            >>> self._merge_single_mcp_config("mcp", base, override)
+            >>> # Result: {"url": "https://new.api", "allowed_tools": ["t1"], ...}
+
+            >>> # 2. Flat Legacy Style (Auto-fixed with warning)
+            >>> override = {"url": "https://new.api"}
+            >>> self._merge_single_mcp_config("mcp", base, override)
+            >>> # Result: {"url": "https://new.api", ...}
+
+            >>> # 3. Header Merging (Preserves Auth)
+            >>> base = {"headers": {"Authorization": "Bearer token"}}
+            >>> override = {"headers": {"X-Custom": "val"}}
+            >>> self._merge_single_mcp_config("mcp", base, override)
+            >>> # Result: {"headers": {"Authorization": "Bearer token", "X-Custom": "val"}, ...}
 
         Args:
-            server_name: Name of the MCP server.
-            base_config: Base config from adapter.
-            override: Optional runtime override config.
+            server_name: Name of the MCP server being configured.
+            base_config: Base configuration dictionary derived from the MCP object.
+            override: Optional dictionary of runtime overrides.
 
         Returns:
-            Merged config dict.
+            A fully merged and normalized configuration dictionary ready for the local runner.
         """
         merged = base_config.copy()
 
         if not override:
             return merged
 
-        from glaip_sdk.runner.mcp_adapter.mcp_config_builder import (  # noqa: PLC0415
-            MCPConfigBuilder,
-        )
+        # 1. Check for misplaced keys and warn (DX/Parity guidance)
+        self._warn_if_mcp_override_misplaced(server_name, override)
 
-        # Handle authentication override
-        if "authentication" in override:
-            headers = MCPConfigBuilder.build_headers_from_auth(override["authentication"])
-            if headers:
-                merged["headers"] = headers
-                logger.debug("Applied runtime authentication headers for MCP '%s'", server_name)
+        # 2. Apply Authentication (Converted to headers)
+        self._apply_mcp_auth_override(server_name, merged, override)
 
-        # Merge other config keys (excluding authentication since we converted it)
+        # 3. Apply Transport Settings (Nested 'config')
+        if "config" in override and isinstance(override["config"], dict):
+            merged.update(override["config"])
+
+        # 4. Apply Structural Settings (e.g., allowed_tools)
+        if "allowed_tools" in override:
+            merged["allowed_tools"] = override["allowed_tools"]
+
+        # 5. Preserve unknown top-level keys (backward compatibility)
+        known_keys = _MCP_TRANSPORT_KEYS | {"config", "authentication", "allowed_tools"}
         for key, value in override.items():
-            if key != "authentication":
+            if key not in known_keys:
                 merged[key] = value
 
+        # 6. Apply Auto-fix for misplaced keys (Local Success)
+        for key in [k for k in override if k in _MCP_TRANSPORT_KEYS]:
+            val = override[key]
+            # Special case: Merge headers instead of overwriting to preserve auth
+            if key == "headers" and isinstance(val, dict) and isinstance(merged.get("headers"), dict):
+                merged["headers"].update(val)
+            else:
+                merged[key] = val
+
         return merged
 
+    def _warn_if_mcp_override_misplaced(self, server_name: str, override: dict[str, Any]) -> None:
+        """Log a warning if transport keys are found at the top level of an override.
+
+        Args:
+            server_name: Name of the MCP server.
+            override: The raw override dictionary.
+        """
+        misplaced = [k for k in override if k in _MCP_TRANSPORT_KEYS]
+        if misplaced:
+            logger.warning(
+                "MCP '%s' override contains transport keys at the top level: %s. "
+                "This structure is inconsistent with the Platform and MCP constructor. "
+                "Transport settings should be nested within a 'config' dictionary. "
+                "Example: mcp_configs={'%s': {'config': {'%s': '...'}}}. "
+                "Automatically merging top-level keys for local execution parity.",
+                server_name,
+                misplaced,
+                server_name,
+                misplaced[0],
+            )
+
+    def _apply_mcp_auth_override(
+        self,
+        server_name: str,
+        merged_config: dict[str, Any],
+        override: dict[str, Any],
+    ) -> None:
+        """Convert authentication override to headers and apply to config.
+
+        Args:
+            server_name: Name of the MCP server.
+            merged_config: The configuration being built (mutated in place).
+            override: The raw override dictionary.
+        """
+        if "authentication" not in override:
+            return
+
+        from glaip_sdk.runner.mcp_adapter.mcp_config_builder import (  # noqa: PLC0415
+            MCPConfigBuilder,
+        )
+
+        headers = MCPConfigBuilder.build_headers_from_auth(override["authentication"])
+        if headers:
+            merged_config["headers"] = headers
+            logger.debug("Applied runtime authentication headers for MCP '%s'", server_name)
+
     def _validate_sub_agent_for_local_mode(self, sub_agent: Any) -> None:
         """Validate that a sub-agent reference is supported for local execution.