feat(a365): add front-end plugin and refactor telemetry/tooling modules

Major Features:
- Add complete A365 front-end plugin implementation:
  * A365FrontEndPlugin: Main plugin integrating NAT workflows with Microsoft Agent 365
  * A365FrontEndPluginWorker: Worker pattern implementation (462 lines)
    - Creates AgentApplication with CloudAdapter, MemoryStorage, MsalConnectionManager
    - Sets up message handlers for Teams chat
    - Implements notification handlers for Email, Word, Excel, PowerPoint, lifecycle events
    - Supports separate workflow routing for notifications via notification_workflow config
    - Handles error handling and cleanup
  * A365FrontEndConfig: Configuration with Entra ID auth, log_level, notification settings
  * Supports custom worker classes via runner_class config option
- Add comprehensive test suite (2000+ lines):
  * Front-end integration tests (542 lines)
  * Front-end registration tests (233 lines)
  * Telemetry exporter integration tests (294 lines)
  * Telemetry registration tests (123 lines)
  * Tooling auth integration tests (613 lines)
  * Tooling registration tests (204 lines)

Refactoring & Improvements:
- Add shared exceptions module (A365Error, A365AuthenticationError, A365ConfigurationError,
  A365SDKError, A365WorkflowExecutionError) for consistent error handling
- Refactor tooling module:
  * Extract tooling config to separate tooling_config.py file
  * Update type hints to Python 3.10+ syntax (| instead of Union/Optional)
  * Optimize tool_overrides conversion (move outside loop for efficiency)
  * Improve error handling with A365ConfigurationError for validation failures
  * Add defensive checks for server.mcp_server_name (handle None/empty)
- Enhance telemetry module:
  * Add AuthenticationRef support with proactive token refresh
  * Remove string import path option for token_resolver (use AuthenticationRef only)
  * Improve token resolver implementation with async/sync bridge
- Remove unused notifications module (functionality implemented directly in worker)
- Update docstrings and error messages throughout
- Update dependencies in pyproject.toml and uv.lock

This commit adds a production-ready A365 front-end plugin with comprehensive test coverage
and improves code quality across telemetry and tooling modules.

Author: afourniernv

packages/nvidia_nat_a365/pyproject.toml

@@ -54,9 +54,12 @@ dependencies = [
   # Keep package version constraints as open as possible to avoid conflicts with other packages. Always define a minimum
   # version when adding a new package. If unsure, default to using `~=` instead of `==`. Does not apply to nvidia-nat packages.
   # Keep sorted!!!
+  "microsoft-agents-a365-notifications~=0.1.0",
   "microsoft-agents-a365-observability-core~=0.1.0",
   "microsoft-agents-a365-tooling~=0.1.0",
-  "microsoft-agents-a365-notifications~=0.1.0",
+  "microsoft-agents-activity~=0.7.0",
+  "microsoft-agents-hosting-aiohttp~=0.7.0",
+  "microsoft-agents-hosting-core~=0.7.0",
   "nvidia-nat-core == {version}",
   "nvidia-nat-opentelemetry == {version}",
 ]
@@ -83,3 +86,6 @@ nvidia-nat-test = { path = "../nvidia_nat_test", editable = true }
 [project.entry-points.'nat.components']
 nat_a365 = "nat.plugins.a365.register"
 nat_a365_telemetry = "nat.plugins.a365.telemetry.register"
+
+[project.entry-points.'nat.front_ends']
+nat_a365 = "nat.plugins.a365.front_end.register"

packages/nvidia_nat_a365/src/nat/plugins/a365/__init__.py

@@ -15,3 +15,19 @@
 # limitations under the License.
 
 """Microsoft Agent 365 plugin for NeMo Agent Toolkit."""
+
+from nat.plugins.a365.exceptions import (
+    A365AuthenticationError,
+    A365ConfigurationError,
+    A365Error,
+    A365SDKError,
+    A365WorkflowExecutionError,
+)
+
+__all__ = [
+    "A365Error",
+    "A365AuthenticationError",
+    "A365ConfigurationError",
+    "A365WorkflowExecutionError",
+    "A365SDKError",
+]

packages/nvidia_nat_a365/src/nat/plugins/a365/exceptions.py

@@ -0,0 +1,77 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES.
+# 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.
+
+"""Custom exceptions for A365 plugin (shared across all modules)."""
+
+
+class A365Error(Exception):
+    """Base exception for A365 plugin errors."""
+    pass
+
+
+class A365AuthenticationError(A365Error):
+    """Authentication-related errors.
+    
+    Used for authentication failures across A365 modules:
+    - Front-end: Bot Framework authentication failures
+    - Tooling: A365 Gateway and MCP server authentication failures
+    - Telemetry: Token resolver authentication failures
+    """
+    
+    def __init__(self, message: str, original_error: Exception | None = None):
+        super().__init__(message)
+        self.original_error = original_error
+
+
+class A365ConfigurationError(A365Error):
+    """Configuration-related errors.
+    
+    Used for configuration validation failures across A365 modules:
+    - Front-end: Invalid front-end configuration (missing fields, wrong types)
+    - Tooling: Invalid tooling configuration (reconnect settings, auth config)
+    - Telemetry: Invalid telemetry configuration (token resolver path)
+    """
+    
+    def __init__(self, message: str, original_error: Exception | None = None):
+        super().__init__(message)
+        self.original_error = original_error
+
+
+class A365WorkflowExecutionError(A365Error):
+    """Errors during workflow execution.
+    
+    Used when NAT workflows fail during execution in A365 handlers.
+    """
+    
+    def __init__(self, message: str, workflow_type: str = "workflow", original_error: Exception | None = None):
+        super().__init__(message)
+        self.workflow_type = workflow_type
+        self.original_error = original_error
+
+
+class A365SDKError(A365Error):
+    """Errors related to Microsoft Agents SDK components.
+    
+    Used for SDK-related errors across A365 modules:
+    - Front-end: Microsoft Agents SDK (AgentApplication, CloudAdapter, etc.)
+    - Telemetry: Agent365Exporter SDK errors
+    - Tooling: McpToolServerConfigurationService SDK errors
+    """
+    
+    def __init__(self, message: str, sdk_component: str | None = None, original_error: Exception | None = None):
+        super().__init__(message)
+        self.sdk_component = sdk_component
+        self.original_error = original_error

packages/nvidia_nat_a365/src/nat/plugins/a365/front_end/__init__.py

@@ -0,0 +1,40 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES.
+# 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.
+
+"""Microsoft Agent 365 front-end plugin."""
+
+from nat.plugins.a365.exceptions import (
+    A365AuthenticationError,
+    A365ConfigurationError,
+    A365Error,
+    A365SDKError,
+    A365WorkflowExecutionError,
+)
+
+from .front_end_config import A365FrontEndConfig
+from .plugin import A365FrontEndPlugin
+from .worker import A365FrontEndPluginWorker
+
+__all__ = [
+    "A365FrontEndConfig",
+    "A365FrontEndPlugin",
+    "A365FrontEndPluginWorker",
+    "A365Error",
+    "A365AuthenticationError",
+    "A365ConfigurationError",
+    "A365WorkflowExecutionError",
+    "A365SDKError",
+]

packages/nvidia_nat_a365/src/nat/plugins/a365/front_end/exceptions.py

@@ -0,0 +1,34 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES.
+# 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.
+
+"""Backward compatibility: Import exceptions from shared module."""
+
+# Import from shared exceptions module
+from nat.plugins.a365.exceptions import (
+    A365AuthenticationError,
+    A365ConfigurationError,
+    A365Error,
+    A365SDKError,
+    A365WorkflowExecutionError,
+)
+
+__all__ = [
+    "A365Error",
+    "A365AuthenticationError",
+    "A365ConfigurationError",
+    "A365WorkflowExecutionError",
+    "A365SDKError",
+]

packages/nvidia_nat_a365/src/nat/plugins/a365/front_end/front_end_config.py

@@ -0,0 +1,108 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES.
+# 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.
+
+"""Configuration for Microsoft Agent 365 front-end."""
+
+import logging
+from typing import Literal
+
+from pydantic import Field, model_validator
+
+from nat.data_models.common import OptionalSecretStr
+from nat.data_models.front_end import FrontEndBaseConfig
+
+logger = logging.getLogger(__name__)
+
+
+class A365FrontEndConfig(FrontEndBaseConfig, name="a365"):
+    """Microsoft Agent 365 front-end configuration.
+
+    This front-end integrates NAT workflows with Microsoft Agent 365 hosting framework,
+    enabling workflows to receive notifications from Teams, Email, and Office 365 apps.
+
+    Authentication uses Entra ID (Azure AD) App Registration credentials (`app_id` and `app_password`)
+    created when registering your bot in Azure Portal. The Microsoft Agents SDK authenticates with
+    Entra ID via `MsalConnectionManager` to enable bot communication with Teams and Office 365.
+    """
+
+    host: str = Field(
+        default="localhost",
+        description="Host to bind the server to (default: localhost)"
+    )
+    port: int = Field(
+        default=3978,
+        description="Port to bind the server to (default: 3978)",
+        ge=0,
+        le=65535
+    )
+    app_id: str = Field(
+        ...,
+        description="Entra ID Application (client) ID from your Azure App Registration. "
+                   "This is the Application ID created when registering your bot in Azure Portal."
+    )
+    app_password: OptionalSecretStr = Field(
+        default=None,
+        description="Entra ID client secret (password) from your Azure App Registration. "
+                   "This authenticates your bot with Entra ID via Microsoft Bot Framework. "
+                   "Can also be set via A365_APP_PASSWORD environment variable."
+    )
+    tenant_id: str | None = Field(
+        default=None,
+        description="Azure tenant ID (optional, defaults to 'common' for multi-tenant). "
+                   "Specify your tenant ID for single-tenant apps, or leave None for multi-tenant."
+    )
+    log_level: str = Field(
+        default="INFO",
+        description="Log level for the server (default: INFO)"
+    )
+    enable_notifications: bool = Field(
+        default=True,
+        description="Enable A365 notification handlers (email, Word, Excel, PowerPoint, lifecycle)"
+    )
+    notification_workflow: str | None = Field(
+        default=None,
+        description="Optional workflow name to route notifications to. If not specified, uses the default workflow."
+    )
+    runner_class: str | None = Field(
+        default=None,
+        description="Custom worker class for handling A365 setup (default: built-in worker). "
+                   "Specify as 'module.path.ClassName' to use a custom worker implementation."
+    )
+
+    @model_validator(mode="after")
+    def validate_security_configuration(self):
+        """Validate security configuration to prevent accidental misconfigurations."""
+        localhost_hosts = {"localhost", "127.0.0.1", "::1"}
+        
+        # Warn if binding to non-localhost interface
+        # Note: Microsoft Agents SDK handles authentication, but binding to public interfaces
+        # should be done with caution and proper network security measures
+        if self.host not in localhost_hosts:
+            logger.warning(
+                "A365 front-end is configured to bind to '%s' (non-localhost interface). "
+                "Ensure proper network security measures are in place (firewall rules, "
+                "reverse proxy with TLS, etc.). For local development, consider binding to localhost.",
+                self.host
+            )
+        
+        # Warn about default port in production-like scenarios
+        if self.host not in localhost_hosts and self.port == 3978:
+            logger.warning(
+                "A365 front-end is using default port 3978 on a non-localhost interface. "
+                "Consider using a non-standard port for production deployments."
+            )
+        
+        return self