feat: add operation_context kwarg for User-Agent attribution

Accept an optional operation_context parameter on DataverseClient that
appends a parenthesized comment to the outbound User-Agent header. This
enables plugin/tool attribution without changing the existing UA product
token.

The context can be passed as a keyword argument on DataverseClient or via
DataverseConfig. Passing both raises ValueError to avoid ambiguity.

Example UA with context:
  DataverseSvcPythonClient:0.1.0b10 (app=dataverse-skills/1.2.1;skill=dv-data;agent=claude-code)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: arorashivam96

src/PowerPlatform/Dataverse/client.py

@@ -44,8 +44,14 @@ class DataverseClient:
     :param config: Optional configuration for language, timeouts, and retries.
         If not provided, defaults are loaded from :meth:`~PowerPlatform.Dataverse.core.config.DataverseConfig.from_env`.
     :type config: ~PowerPlatform.Dataverse.core.config.DataverseConfig or None
+    :param operation_context: Optional caller-defined context string appended to the
+        outbound ``User-Agent`` header as a parenthesized comment. Cannot be used
+        together with ``config`` -- pass the context via
+        :class:`~PowerPlatform.Dataverse.core.config.DataverseConfig` instead.
+    :type operation_context: :class:`str` or None
 
     :raises ValueError: If ``base_url`` is missing or empty after trimming.
+    :raises ValueError: If both ``config`` and ``operation_context`` are provided.
 
     .. note::
         The client lazily initializes its internal OData client on first use, allowing lightweight construction without immediate network calls.
@@ -95,12 +101,24 @@ def __init__(
         base_url: str,
         credential: TokenCredential,
         config: Optional[DataverseConfig] = None,
+        *,
+        operation_context: Optional[str] = None,
     ) -> None:
+        if config is not None and operation_context is not None:
+            raise ValueError(
+                "Cannot specify both 'config' and 'operation_context'. "
+                "Pass operation_context via DataverseConfig instead."
+            )
         self.auth = _AuthManager(credential)
         self._base_url = (base_url or "").rstrip("/")
         if not self._base_url:
             raise ValueError("base_url is required.")
-        self._config = config or DataverseConfig.from_env()
+        if config is not None:
+            self._config = config
+        elif operation_context is not None:
+            self._config = DataverseConfig(operation_context=operation_context)
+        else:
+            self._config = DataverseConfig.from_env()
         self._odata: Optional[_ODataClient] = None
         self._session: Optional[requests.Session] = None
         self._closed: bool = False

src/PowerPlatform/Dataverse/core/config.py

@@ -35,6 +35,10 @@ class DataverseConfig:
         When provided, all HTTP requests and responses are logged to timestamped
         ``.log`` files with automatic redaction of sensitive headers.
     :type log_config: ~PowerPlatform.Dataverse.core.log_config.LogConfig or None
+    :param operation_context: Optional caller-defined context string appended to the
+        outbound ``User-Agent`` header as a parenthesized comment. Intended for
+        plugin/tool attribution (e.g. ``"app=dataverse-skills/1.2.1;skill=dv-data;agent=claude-code"``).
+    :type operation_context: :class:`str` or None
     """
 
     language_code: int = 1033
@@ -46,6 +50,8 @@ class DataverseConfig:
 
     log_config: Optional["LogConfig"] = None
 
+    operation_context: Optional[str] = None
+
     @classmethod
     def from_env(cls) -> "DataverseConfig":
         """
@@ -61,4 +67,5 @@ def from_env(cls) -> "DataverseConfig":
             http_backoff=None,
             http_timeout=None,
             log_config=None,
+            operation_context=None,
         )

src/PowerPlatform/Dataverse/data/_odata.py

@@ -206,6 +206,7 @@ def __init__(
             session=session,
             logger=self._http_logger,
         )
+        self._operation_context = self.config.operation_context
         self._logical_to_entityset_cache: dict[str, str] = {}
         # Cache: normalized table_schema_name (lowercase) -> primary id attribute (e.g. accountid)
         self._logical_primaryid_cache: dict[str, str] = {}
@@ -241,13 +242,16 @@ def _headers(self) -> Dict[str, str]:
         """Build standard OData headers with bearer auth."""
         scope = f"{self.base_url}/.default"
         token = self.auth._acquire_token(scope).access_token
+        ua = _USER_AGENT
+        if self._operation_context:
+            ua = f"{_USER_AGENT} ({self._operation_context})"
         return {
             "Authorization": f"Bearer {token}",
             "Accept": "application/json",
             "Content-Type": "application/json",
             "OData-MaxVersion": "4.0",
             "OData-Version": "4.0",
-            "User-Agent": _USER_AGENT,
+            "User-Agent": ua,
         }
 
     def _merge_headers(self, headers: Optional[Dict[str, str]] = None) -> Dict[str, str]:

tests/unit/test_operation_context.py

@@ -0,0 +1,97 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Tests for operation_context support on DataverseClient and User-Agent header."""
+
+import unittest
+from unittest.mock import MagicMock
+
+from azure.core.credentials import TokenCredential
+
+from PowerPlatform.Dataverse.client import DataverseClient
+from PowerPlatform.Dataverse.core.config import DataverseConfig
+from PowerPlatform.Dataverse.data._odata import _ODataClient, _USER_AGENT
+
+
+class TestOperationContextConfig(unittest.TestCase):
+    """Tests for operation_context on DataverseConfig."""
+
+    def test_default_is_none(self):
+        config = DataverseConfig.from_env()
+        self.assertIsNone(config.operation_context)
+
+    def test_explicit_value(self):
+        config = DataverseConfig(operation_context="app=test/1.0;agent=claude-code")
+        self.assertEqual(config.operation_context, "app=test/1.0;agent=claude-code")
+
+    def test_default_constructor_is_none(self):
+        config = DataverseConfig()
+        self.assertIsNone(config.operation_context)
+
+
+class TestOperationContextClient(unittest.TestCase):
+    """Tests for operation_context kwarg on DataverseClient."""
+
+    def setUp(self):
+        self.mock_credential = MagicMock(spec=TokenCredential)
+        self.base_url = "https://example.crm.dynamics.com"
+
+    def test_kwarg_sets_config(self):
+        client = DataverseClient(
+            self.base_url, self.mock_credential,
+            operation_context="app=test/1.0;skill=dv-data;agent=claude-code",
+        )
+        self.assertEqual(client._config.operation_context, "app=test/1.0;skill=dv-data;agent=claude-code")
+
+    def test_no_kwarg_leaves_config_default(self):
+        client = DataverseClient(self.base_url, self.mock_credential)
+        self.assertIsNone(client._config.operation_context)
+
+    def test_config_and_kwarg_raises(self):
+        config = DataverseConfig(operation_context="app=test/1.0")
+        with self.assertRaises(ValueError):
+            DataverseClient(
+                self.base_url, self.mock_credential,
+                config=config,
+                operation_context="app=other/2.0",
+            )
+
+    def test_config_alone_works(self):
+        config = DataverseConfig(operation_context="app=test/1.0;agent=copilot")
+        client = DataverseClient(self.base_url, self.mock_credential, config=config)
+        self.assertEqual(client._config.operation_context, "app=test/1.0;agent=copilot")
+
+
+class TestOperationContextUserAgent(unittest.TestCase):
+    """Tests for User-Agent header with operation_context."""
+
+    def setUp(self):
+        self.dummy_auth = MagicMock()
+        token_result = MagicMock()
+        token_result.access_token = "test-token"
+        self.dummy_auth._acquire_token.return_value = token_result
+        self.base_url = "https://org.example.com"
+
+    def test_default_user_agent_unchanged(self):
+        odata = _ODataClient(self.dummy_auth, self.base_url)
+        headers = odata._headers()
+        self.assertEqual(headers["User-Agent"], _USER_AGENT)
+
+    def test_operation_context_appended(self):
+        ctx = "app=dataverse-skills/1.2.1;skill=dv-data;agent=claude-code"
+        config = DataverseConfig(operation_context=ctx)
+        odata = _ODataClient(self.dummy_auth, self.base_url, config=config)
+        headers = odata._headers()
+        self.assertEqual(headers["User-Agent"], f"{_USER_AGENT} ({ctx})")
+
+    def test_none_context_no_parentheses(self):
+        config = DataverseConfig(operation_context=None)
+        odata = _ODataClient(self.dummy_auth, self.base_url, config=config)
+        headers = odata._headers()
+        self.assertNotIn("(", headers["User-Agent"])
+
+    def test_empty_string_context_no_parentheses(self):
+        config = DataverseConfig(operation_context="")
+        odata = _ODataClient(self.dummy_auth, self.base_url, config=config)
+        headers = odata._headers()
+        self.assertNotIn("(", headers["User-Agent"])