fix(lib): tighten TemporalACPConfig + concise comments + import order

- Add `model_validator(mode="after")` on `TemporalACPConfig` that rejects
  setting both `payload_codec` and `data_converter`, mirroring the
  `get_temporal_client` ambiguity guard at config-construction time
  (consistent with the existing `plugins` / `interceptors` validators).
- Collapse multi-line comments in `worker.py` and `clients/temporal/utils.py`
  to single-line context — the PR description carries the long-form rationale.
- Ruff import-order autofixes on touched files (resolves CI lint).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: matteolibrizzi-scale

src/agentex/lib/core/clients/temporal/temporal_client.py

@@ -7,7 +7,7 @@
 from temporalio.client import Client, WorkflowExecutionStatus
 from temporalio.common import RetryPolicy as TemporalRetryPolicy, WorkflowIDReusePolicy
 from temporalio.service import RPCError, RPCStatusCode
-from temporalio.converter import DataConverter, PayloadCodec
+from temporalio.converter import PayloadCodec, DataConverter
 
 from agentex.lib.utils.logging import make_logger
 from agentex.lib.utils.model_utils import BaseModel

src/agentex/lib/core/clients/temporal/utils.py

@@ -6,7 +6,7 @@
 from temporalio.client import Client, Plugin as ClientPlugin
 from temporalio.worker import Interceptor
 from temporalio.runtime import Runtime, TelemetryConfig, OpenTelemetryConfig
-from temporalio.converter import DataConverter, PayloadCodec
+from temporalio.converter import PayloadCodec, DataConverter
 from temporalio.contrib.pydantic import pydantic_data_converter
 
 # class DateTimeJSONEncoder(AdvancedJSONEncoder):
@@ -118,17 +118,11 @@ async def get_temporal_client(
             "kwarg. Specifying both is ambiguous."
         )
 
-    # Check if OpenAI plugin is present - it needs to configure its own data converter
     # Lazy import to avoid pulling in opentelemetry.sdk for non-Temporal agents
     from temporalio.contrib.openai_agents import OpenAIAgentsPlugin
 
     has_openai_plugin = any(isinstance(p, OpenAIAgentsPlugin) for p in (plugins or []))
 
-    # When the OpenAI plugin is present, its `_data_converter` transformer
-    # builds a fresh DataConverter (without any codec) if none is supplied,
-    # so a standalone `payload_codec` kwarg would be silently dropped and
-    # payloads would land in Temporal in plain text. Guide the caller to
-    # the working composition path instead.
     if has_openai_plugin and payload_codec is not None and data_converter is None:
         raise ValueError(
             "payload_codec passed as a kwarg alongside OpenAIAgentsPlugin would "
@@ -145,10 +139,6 @@ async def get_temporal_client(
     }
 
     if data_converter is not None:
-        # Caller supplied a pre-built converter. With the OpenAI plugin present
-        # and `payload_converter_class=OpenAIPayloadConverter` (or subclass),
-        # the plugin's `_data_converter` transformer passes it through intact,
-        # preserving any payload_codec.
         connect_kwargs["data_converter"] = data_converter
     elif not has_openai_plugin:
         dc = pydantic_data_converter

src/agentex/lib/core/temporal/workers/worker.py

@@ -107,17 +107,11 @@ async def get_temporal_client(
             "kwarg. Specifying both is ambiguous."
         )
 
-    # Check if OpenAI plugin is present - it needs to configure its own data converter
     # Lazy import to avoid pulling in opentelemetry.sdk for non-Temporal agents
     from temporalio.contrib.openai_agents import OpenAIAgentsPlugin
 
     has_openai_plugin = any(isinstance(p, OpenAIAgentsPlugin) for p in (plugins or []))
 
-    # When the OpenAI plugin is present, its `_data_converter` transformer
-    # builds a fresh DataConverter (without any codec) if none is supplied,
-    # so a standalone `payload_codec` kwarg would be silently dropped and
-    # payloads would land in Temporal in plain text. Guide the caller to
-    # the working composition path instead.
     if has_openai_plugin and payload_codec is not None and data_converter is None:
         raise ValueError(
             "payload_codec passed as a kwarg alongside OpenAIAgentsPlugin would "
@@ -134,10 +128,6 @@ async def get_temporal_client(
     }
 
     if data_converter is not None:
-        # Caller supplied a pre-built converter. With the OpenAI plugin present
-        # and `payload_converter_class=OpenAIPayloadConverter` (or subclass),
-        # the plugin's `_data_converter` transformer passes it through intact,
-        # preserving any payload_codec.
         connect_kwargs["data_converter"] = data_converter
     elif not has_openai_plugin:
         dc = custom_data_converter

src/agentex/lib/sdk/fastacp/impl/temporal_acp.py

@@ -4,7 +4,7 @@
 from contextlib import asynccontextmanager
 
 from fastapi import FastAPI
-from temporalio.converter import DataConverter, PayloadCodec
+from temporalio.converter import PayloadCodec, DataConverter
 
 from agentex.protocol.acp import (
     SendEventParams,

src/agentex/lib/types/fastacp.py

@@ -2,7 +2,7 @@
 
 from typing import Any, Literal
 
-from pydantic import Field, BaseModel, field_validator
+from pydantic import Field, BaseModel, field_validator, model_validator
 
 from agentex.lib.core.clients.temporal.utils import validate_client_plugins, validate_worker_interceptors
 
@@ -89,6 +89,16 @@ def validate_interceptors(cls, v: list[Any]) -> list[Any]:
         validate_worker_interceptors(v)
         return v
 
+    @model_validator(mode="after")
+    def _validate_codec_and_data_converter_mutually_exclusive(self) -> "TemporalACPConfig":
+        if self.payload_codec is not None and self.data_converter is not None:
+            raise ValueError(
+                "Pass payload_codec inside `data_converter` "
+                "(DataConverter(..., payload_codec=...)) instead of as a separate "
+                "field. Specifying both is ambiguous."
+            )
+        return self
+
 
 class AsyncBaseACPConfig(AsyncACPConfig):
     """Configuration for AsyncBaseACP implementation

tests/lib/test_payload_codec.py

@@ -6,8 +6,8 @@
 import pytest
 from temporalio.client import Client, Plugin as ClientPlugin
 from temporalio.converter import (
-    DataConverter,
     PayloadCodec,
+    DataConverter,
     DefaultPayloadConverter,
 )
 from temporalio.contrib.pydantic import pydantic_data_converter
@@ -354,6 +354,16 @@ def test_config_accepts_data_converter(self):
         dc = DataConverter(payload_codec=_NoopCodec())
         assert TemporalACPConfig(data_converter=dc).data_converter is dc
 
+    def test_config_rejects_codec_and_data_converter_together(self):
+        from pydantic import ValidationError
+
+        from agentex.lib.types.fastacp import TemporalACPConfig
+
+        codec = _NoopCodec()
+        dc = DataConverter(payload_codec=codec)
+        with pytest.raises(ValidationError, match="Pass payload_codec inside `data_converter`"):
+            TemporalACPConfig(payload_codec=codec, data_converter=dc)
+
     def test_fastacp_forwards_data_converter_from_config(self):
         from agentex.lib.types.fastacp import TemporalACPConfig
         from agentex.lib.sdk.fastacp.fastacp import FastACP