feat: add operation_context kwarg for User-Agent attribution (#178)

## Summary
- Adds an optional `operation_context` keyword argument to
`DataverseClient` that appends a parenthesized comment to the outbound
`User-Agent` header
- Enables callers (e.g. the Dataverse skills plugin) to attribute
traffic they originate, so server-side dashboards can compute MAU/MAT,
skill split, and agent distribution from existing Dataverse server logs
- The context can also be set via
`DataverseConfig(operation_context=...)` for callers using custom config

## Example

```python
client = DataverseClient(
    base_url="https://org.crm.dynamics.com",
    credential=credential,
    operation_context="app=dataverse-skills/1.2.1;skill=dv-data;agent=claude-code",
)
```
Resulting UA: `DataverseSvcPythonClient:0.1.0b10
(app=dataverse-skills/1.2.1;skill=dv-data;agent=claude-code)`

Without `operation_context`, the UA remains unchanged:
`DataverseSvcPythonClient:0.1.0b10`

## Changes

| File | Change |
|---|---|
| `src/.../core/config.py` | Added `operation_context: Optional[str] =
None` to `DataverseConfig` dataclass |
| `src/.../data/_odata.py` | `_headers()` conditionally appends
`(operation_context)` to UA string |
| `src/.../client.py` | Added `operation_context` keyword-only arg to
`DataverseClient.__init__()`. Raises `ValueError` if both `config` and
`operation_context` are provided |
| `tests/unit/test_operation_context.py` | 11 new unit tests covering
config, client kwarg, and UA header behavior |

## Test plan

- [x] `pytest tests/unit/test_operation_context.py -v` — 11 passed
- [x] `pytest tests/unit/ -v` — 1369 passed, 0 regressions
- [ ] Manual: instantiate `DataverseClient` with `operation_context`,
make a request, verify UA in Fiddler/server logs

## Design reference

See `design/plugin-telemetry-design.md` in the `dataverse-cli` repo on
`design/plugin-telemetry-review` branch — section 3.2 (single
operation_context) and Phase 1 in section 5.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

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

Author: arorashivam96

src/PowerPlatform/Dataverse/client.py

@@ -12,7 +12,7 @@
 from azure.core.credentials import TokenCredential
 
 from .core._auth import _AuthManager
-from .core.config import DataverseConfig
+from .core.config import DataverseConfig, OperationContext
 from .data._odata import _ODataClient
 from .operations.dataframe import DataFrameOperations
 from .operations.records import RecordOperations
@@ -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 context: Optional caller-defined context object appended to the
+        outbound ``User-Agent`` header for plugin/tool attribution. Cannot be used
+        together with ``config`` -- pass the context via
+        :class:`~PowerPlatform.Dataverse.core.config.DataverseConfig` instead.
+    :type context: ~PowerPlatform.Dataverse.core.config.OperationContext or None
 
     :raises ValueError: If ``base_url`` is missing or empty after trimming.
+    :raises ValueError: If both ``config`` and ``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,23 @@ def __init__(
         base_url: str,
         credential: TokenCredential,
         config: Optional[DataverseConfig] = None,
+        *,
+        context: Optional[OperationContext] = None,
     ) -> None:
+        if config is not None and context is not None:
+            raise ValueError(
+                "Cannot specify both 'config' and '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 context is not None:
+            self._config = DataverseConfig(operation_context=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

@@ -11,12 +11,50 @@
 
 from __future__ import annotations
 
+import re
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Optional
 
 if TYPE_CHECKING:
     from .log_config import LogConfig
 
+# key=value pairs separated by semicolons.
+# Keys: alphanumeric, hyphens, underscores.
+# Values: alphanumeric, hyphens, underscores, dots, slashes.
+_CONTEXT_PATTERN = re.compile(r"^[a-zA-Z0-9_-]+=[a-zA-Z0-9_./-]+(;[a-zA-Z0-9_-]+=[a-zA-Z0-9_./-]+)*$")
+
+
+@dataclass(frozen=True)
+class OperationContext:
+    """Caller-defined context appended to outbound ``User-Agent`` headers.
+
+    The context string is validated to be semicolon-separated ``key=value`` pairs
+    (e.g. ``"app=myapp/1.0;agent=claude-code"``).  Free-form text, email
+    addresses, and other potentially sensitive strings are rejected.
+
+    :param user_agent_context: Attribution string in ``key=value;key=value`` format.
+    :type user_agent_context: :class:`str`
+
+    :raises ValueError: If the string is empty, contains control characters, or
+        does not match the required ``key=value`` format.
+    """
+
+    user_agent_context: str
+
+    def __post_init__(self) -> None:
+        val = self.user_agent_context
+        if not val:
+            raise ValueError("operation_context must not be empty.")
+        if any(c in val for c in "\r\n\x00"):
+            raise ValueError("operation_context must not contain CR, LF, or NUL characters.")
+        if not _CONTEXT_PATTERN.match(val):
+            raise ValueError(
+                "operation_context must be semicolon-separated key=value pairs "
+                "(e.g. 'app=myapp/1.0;agent=claude-code'). "
+                "Keys and values may contain alphanumerics, hyphens, underscores, "
+                "dots, and slashes."
+            )
+
 
 @dataclass(frozen=True)
 class DataverseConfig:
@@ -35,6 +73,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 object appended to the
+        outbound ``User-Agent`` header as a parenthesized comment. Intended for
+        plugin/tool attribution.
+    :type operation_context: ~PowerPlatform.Dataverse.core.config.OperationContext or None
     """
 
     language_code: int = 1033
@@ -46,6 +88,8 @@ class DataverseConfig:
 
     log_config: Optional["LogConfig"] = None
 
+    operation_context: Optional[OperationContext] = None
+
     @classmethod
     def from_env(cls) -> "DataverseConfig":
         """
@@ -61,4 +105,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,8 @@ def __init__(
             session=session,
             logger=self._http_logger,
         )
+        ctx_obj = self.config.operation_context
+        self._operation_context = ctx_obj.user_agent_context if ctx_obj else None
         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 +243,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/data/test_enum_optionset_payload.py

@@ -25,6 +25,7 @@ def __init__(self, language_code=1033):
         self.http_backoff = 0
         self.http_timeout = 5
         self.log_config = None
+        self.operation_context = None  # None or OperationContext object
 
 
 def _make_client(lang=1033):

tests/unit/test_operation_context.py

@@ -0,0 +1,149 @@
+# 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, OperationContext
+from PowerPlatform.Dataverse.data._odata import _ODataClient, _USER_AGENT
+
+
+class TestOperationContextValidation(unittest.TestCase):
+    """Tests for OperationContext format validation and PII rejection."""
+
+    def test_valid_single_pair(self):
+        ctx = OperationContext(user_agent_context="app=test/1.0")
+        self.assertEqual(ctx.user_agent_context, "app=test/1.0")
+
+    def test_valid_multiple_pairs(self):
+        ctx = OperationContext(user_agent_context="app=test/1.0;skill=dv-data;agent=claude-code")
+        self.assertEqual(ctx.user_agent_context, "app=test/1.0;skill=dv-data;agent=claude-code")
+
+    def test_valid_with_dots_slashes_hyphens(self):
+        ctx = OperationContext(user_agent_context="app=dataverse-skills/1.2.1")
+        self.assertEqual(ctx.user_agent_context, "app=dataverse-skills/1.2.1")
+
+    def test_reject_empty(self):
+        with self.assertRaises(ValueError):
+            OperationContext(user_agent_context="")
+
+    def test_reject_email(self):
+        with self.assertRaises(ValueError):
+            OperationContext(user_agent_context="myname@email.com")
+
+    def test_reject_freeform_text(self):
+        with self.assertRaises(ValueError):
+            OperationContext(user_agent_context="my bank password is 1234")
+
+    def test_reject_control_chars(self):
+        for bad in ["has\rnewline", "has\nnewline", "has\x00null"]:
+            with self.assertRaises(ValueError):
+                OperationContext(user_agent_context=bad)
+
+    def test_reject_spaces(self):
+        with self.assertRaises(ValueError):
+            OperationContext(user_agent_context="app=my app")
+
+    def test_reject_no_equals(self):
+        with self.assertRaises(ValueError):
+            OperationContext(user_agent_context="justaplainstring")
+
+
+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):
+        ctx = OperationContext(user_agent_context="app=test/1.0;agent=claude-code")
+        config = DataverseConfig(operation_context=ctx)
+        self.assertEqual(config.operation_context.user_agent_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 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):
+        ctx = OperationContext(user_agent_context="app=test/1.0;skill=dv-data;agent=claude-code")
+        client = DataverseClient(
+            self.base_url,
+            self.mock_credential,
+            context=ctx,
+        )
+        self.assertEqual(
+            client._config.operation_context.user_agent_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_context_raises(self):
+        ctx = OperationContext(user_agent_context="app=test/1.0")
+        config = DataverseConfig(operation_context=ctx)
+        with self.assertRaises(ValueError):
+            DataverseClient(
+                self.base_url,
+                self.mock_credential,
+                config=config,
+                context=OperationContext(user_agent_context="app=other/2.0"),
+            )
+
+    def test_config_alone_works(self):
+        ctx = OperationContext(user_agent_context="app=test/1.0;agent=copilot")
+        config = DataverseConfig(operation_context=ctx)
+        client = DataverseClient(self.base_url, self.mock_credential, config=config)
+        self.assertEqual(
+            client._config.operation_context.user_agent_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_str = "app=dataverse-skills/1.2.1;skill=dv-data;agent=claude-code"
+        ctx = OperationContext(user_agent_context=ctx_str)
+        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_str})")
+
+    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_rejected_at_creation(self):
+        with self.assertRaises(ValueError):
+            OperationContext(user_agent_context="")