Centralize agent start payload serialization helper

cursoragent · shrisukhani · cursoragent · commit 9b9dda153bb2 · 2026-02-14T11:37:41.000Z
Co-authored-by: Shri Sukhani &lt;shrisukhani@users.noreply.github.com&gt;
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -76,6 +76,7 @@ This runs lint, format checks, compile checks, tests, and package build.
 - Keep sync/async behavior in parity where applicable.
 - Prefer deterministic unit tests over network-dependent tests.
 - Preserve architectural guardrails with focused tests. Current guard suites include:
+  - `tests/test_agent_payload_helper_usage.py` (shared agent start-payload helper usage enforcement),
   - `tests/test_agent_terminal_status_helper_usage.py` (shared agent terminal-status helper usage enforcement),
   - `tests/test_architecture_marker_usage.py` (architecture marker coverage across guard modules),
   - `tests/test_binary_file_open_helper_usage.py` (shared binary file open helper usage enforcement),
diff --git a/hyperbrowser/client/managers/agent_payload_utils.py b/hyperbrowser/client/managers/agent_payload_utils.py
@@ -0,0 +1,10 @@
+from typing import Any, Dict
+
+from .serialization_utils import serialize_model_dump_to_dict
+
+
+def build_agent_start_payload(params: Any, *, error_message: str) -> Dict[str, Any]:
+    return serialize_model_dump_to_dict(
+        params,
+        error_message=error_message,
+    )
diff --git a/hyperbrowser/client/managers/async_manager/agents/claude_computer_use.py b/hyperbrowser/client/managers/async_manager/agents/claude_computer_use.py
@@ -1,9 +1,9 @@
 from typing import Optional
 
 from ....polling import wait_for_job_result_async
+from ...agent_payload_utils import build_agent_start_payload
 from ...agent_status_utils import is_agent_terminal_status
 from ...response_utils import parse_response_model
-from ...serialization_utils import serialize_model_dump_to_dict
 from ...start_job_utils import build_started_job_context
 
 from .....models import (
@@ -23,7 +23,7 @@ def __init__(self, client):
     async def start(
         self, params: StartClaudeComputerUseTaskParams
     ) -> StartClaudeComputerUseTaskResponse:
-        payload = serialize_model_dump_to_dict(
+        payload = build_agent_start_payload(
             params,
             error_message="Failed to serialize Claude Computer Use start params",
         )
diff --git a/hyperbrowser/client/managers/async_manager/agents/cua.py b/hyperbrowser/client/managers/async_manager/agents/cua.py
@@ -1,9 +1,9 @@
 from typing import Optional
 
 from ....polling import wait_for_job_result_async
+from ...agent_payload_utils import build_agent_start_payload
 from ...agent_status_utils import is_agent_terminal_status
 from ...response_utils import parse_response_model
-from ...serialization_utils import serialize_model_dump_to_dict
 from ...start_job_utils import build_started_job_context
 
 from .....models import (
@@ -21,7 +21,7 @@ def __init__(self, client):
         self._client = client
 
     async def start(self, params: StartCuaTaskParams) -> StartCuaTaskResponse:
-        payload = serialize_model_dump_to_dict(
+        payload = build_agent_start_payload(
             params,
             error_message="Failed to serialize CUA start params",
         )
diff --git a/hyperbrowser/client/managers/async_manager/agents/gemini_computer_use.py b/hyperbrowser/client/managers/async_manager/agents/gemini_computer_use.py
@@ -1,9 +1,9 @@
 from typing import Optional
 
 from ....polling import wait_for_job_result_async
+from ...agent_payload_utils import build_agent_start_payload
 from ...agent_status_utils import is_agent_terminal_status
 from ...response_utils import parse_response_model
-from ...serialization_utils import serialize_model_dump_to_dict
 from ...start_job_utils import build_started_job_context
 
 from .....models import (
@@ -23,7 +23,7 @@ def __init__(self, client):
     async def start(
         self, params: StartGeminiComputerUseTaskParams
     ) -> StartGeminiComputerUseTaskResponse:
-        payload = serialize_model_dump_to_dict(
+        payload = build_agent_start_payload(
             params,
             error_message="Failed to serialize Gemini Computer Use start params",
         )
diff --git a/hyperbrowser/client/managers/async_manager/agents/hyper_agent.py b/hyperbrowser/client/managers/async_manager/agents/hyper_agent.py
@@ -1,9 +1,9 @@
 from typing import Optional
 
 from ....polling import wait_for_job_result_async
+from ...agent_payload_utils import build_agent_start_payload
 from ...agent_status_utils import is_agent_terminal_status
 from ...response_utils import parse_response_model
-from ...serialization_utils import serialize_model_dump_to_dict
 from ...start_job_utils import build_started_job_context
 
 from .....models import (
@@ -23,7 +23,7 @@ def __init__(self, client):
     async def start(
         self, params: StartHyperAgentTaskParams
     ) -> StartHyperAgentTaskResponse:
-        payload = serialize_model_dump_to_dict(
+        payload = build_agent_start_payload(
             params,
             error_message="Failed to serialize HyperAgent start params",
         )
diff --git a/hyperbrowser/client/managers/sync_manager/agents/claude_computer_use.py b/hyperbrowser/client/managers/sync_manager/agents/claude_computer_use.py
@@ -1,9 +1,9 @@
 from typing import Optional
 
 from ....polling import wait_for_job_result
+from ...agent_payload_utils import build_agent_start_payload
 from ...agent_status_utils import is_agent_terminal_status
 from ...response_utils import parse_response_model
-from ...serialization_utils import serialize_model_dump_to_dict
 from ...start_job_utils import build_started_job_context
 
 from .....models import (
@@ -23,7 +23,7 @@ def __init__(self, client):
     def start(
         self, params: StartClaudeComputerUseTaskParams
     ) -> StartClaudeComputerUseTaskResponse:
-        payload = serialize_model_dump_to_dict(
+        payload = build_agent_start_payload(
             params,
             error_message="Failed to serialize Claude Computer Use start params",
         )
diff --git a/hyperbrowser/client/managers/sync_manager/agents/cua.py b/hyperbrowser/client/managers/sync_manager/agents/cua.py
@@ -1,9 +1,9 @@
 from typing import Optional
 
 from ....polling import wait_for_job_result
+from ...agent_payload_utils import build_agent_start_payload
 from ...agent_status_utils import is_agent_terminal_status
 from ...response_utils import parse_response_model
-from ...serialization_utils import serialize_model_dump_to_dict
 from ...start_job_utils import build_started_job_context
 
 from .....models import (
@@ -21,7 +21,7 @@ def __init__(self, client):
         self._client = client
 
     def start(self, params: StartCuaTaskParams) -> StartCuaTaskResponse:
-        payload = serialize_model_dump_to_dict(
+        payload = build_agent_start_payload(
             params,
             error_message="Failed to serialize CUA start params",
         )
diff --git a/hyperbrowser/client/managers/sync_manager/agents/gemini_computer_use.py b/hyperbrowser/client/managers/sync_manager/agents/gemini_computer_use.py
@@ -1,9 +1,9 @@
 from typing import Optional
 
 from ....polling import wait_for_job_result
+from ...agent_payload_utils import build_agent_start_payload
 from ...agent_status_utils import is_agent_terminal_status
 from ...response_utils import parse_response_model
-from ...serialization_utils import serialize_model_dump_to_dict
 from ...start_job_utils import build_started_job_context
 
 from .....models import (
@@ -23,7 +23,7 @@ def __init__(self, client):
     def start(
         self, params: StartGeminiComputerUseTaskParams
     ) -> StartGeminiComputerUseTaskResponse:
-        payload = serialize_model_dump_to_dict(
+        payload = build_agent_start_payload(
             params,
             error_message="Failed to serialize Gemini Computer Use start params",
         )
diff --git a/hyperbrowser/client/managers/sync_manager/agents/hyper_agent.py b/hyperbrowser/client/managers/sync_manager/agents/hyper_agent.py
@@ -1,9 +1,9 @@
 from typing import Optional
 
 from ....polling import wait_for_job_result
+from ...agent_payload_utils import build_agent_start_payload
 from ...agent_status_utils import is_agent_terminal_status
 from ...response_utils import parse_response_model
-from ...serialization_utils import serialize_model_dump_to_dict
 from ...start_job_utils import build_started_job_context
 
 from .....models import (
@@ -21,7 +21,7 @@ def __init__(self, client):
         self._client = client
 
     def start(self, params: StartHyperAgentTaskParams) -> StartHyperAgentTaskResponse:
-        payload = serialize_model_dump_to_dict(
+        payload = build_agent_start_payload(
             params,
             error_message="Failed to serialize HyperAgent start params",
         )
diff --git a/tests/test_agent_payload_helper_usage.py b/tests/test_agent_payload_helper_usage.py
@@ -0,0 +1,24 @@
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.architecture
+
+
+MODULES = (
+    "hyperbrowser/client/managers/sync_manager/agents/hyper_agent.py",
+    "hyperbrowser/client/managers/async_manager/agents/hyper_agent.py",
+    "hyperbrowser/client/managers/sync_manager/agents/gemini_computer_use.py",
+    "hyperbrowser/client/managers/async_manager/agents/gemini_computer_use.py",
+    "hyperbrowser/client/managers/sync_manager/agents/claude_computer_use.py",
+    "hyperbrowser/client/managers/async_manager/agents/claude_computer_use.py",
+    "hyperbrowser/client/managers/sync_manager/agents/cua.py",
+    "hyperbrowser/client/managers/async_manager/agents/cua.py",
+)
+
+
+def test_agent_managers_use_shared_start_payload_helper():
+    for module_path in MODULES:
+        module_text = Path(module_path).read_text(encoding="utf-8")
+        assert "build_agent_start_payload(" in module_text
+        assert "serialize_model_dump_to_dict(" not in module_text
diff --git a/tests/test_agent_payload_utils.py b/tests/test_agent_payload_utils.py
@@ -0,0 +1,80 @@
+from types import MappingProxyType
+
+import pytest
+
+from hyperbrowser.client.managers.agent_payload_utils import build_agent_start_payload
+from hyperbrowser.exceptions import HyperbrowserError
+from hyperbrowser.models.agents.cua import StartCuaTaskParams
+
+
+def test_build_agent_start_payload_serializes_model():
+    payload = build_agent_start_payload(
+        StartCuaTaskParams(task="open docs"),
+        error_message="serialize failed",
+    )
+
+    assert payload == {"task": "open docs"}
+
+
+def test_build_agent_start_payload_wraps_runtime_serialization_errors(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    params = StartCuaTaskParams(task="open docs")
+
+    def _raise_model_dump_error(*args, **kwargs):
+        _ = args
+        _ = kwargs
+        raise RuntimeError("broken model_dump")
+
+    monkeypatch.setattr(StartCuaTaskParams, "model_dump", _raise_model_dump_error)
+
+    with pytest.raises(HyperbrowserError, match="serialize failed") as exc_info:
+        build_agent_start_payload(
+            params,
+            error_message="serialize failed",
+        )
+
+    assert isinstance(exc_info.value.original_error, RuntimeError)
+
+
+def test_build_agent_start_payload_preserves_hyperbrowser_serialization_errors(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    params = StartCuaTaskParams(task="open docs")
+
+    def _raise_model_dump_error(*args, **kwargs):
+        _ = args
+        _ = kwargs
+        raise HyperbrowserError("custom model_dump failure")
+
+    monkeypatch.setattr(StartCuaTaskParams, "model_dump", _raise_model_dump_error)
+
+    with pytest.raises(
+        HyperbrowserError, match="custom model_dump failure"
+    ) as exc_info:
+        build_agent_start_payload(
+            params,
+            error_message="serialize failed",
+        )
+
+    assert exc_info.value.original_error is None
+
+
+def test_build_agent_start_payload_rejects_non_dict_payload(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    params = StartCuaTaskParams(task="open docs")
+
+    monkeypatch.setattr(
+        StartCuaTaskParams,
+        "model_dump",
+        lambda *args, **kwargs: MappingProxyType({"task": "open docs"}),
+    )
+
+    with pytest.raises(HyperbrowserError, match="serialize failed") as exc_info:
+        build_agent_start_payload(
+            params,
+            error_message="serialize failed",
+        )
+
+    assert exc_info.value.original_error is None
diff --git a/tests/test_architecture_marker_usage.py b/tests/test_architecture_marker_usage.py
@@ -6,6 +6,7 @@
 
 
 ARCHITECTURE_GUARD_MODULES = (
+    "tests/test_agent_payload_helper_usage.py",
     "tests/test_agent_terminal_status_helper_usage.py",
     "tests/test_guardrail_ast_utils.py",
     "tests/test_manager_model_dump_usage.py",
diff --git a/tests/test_core_type_helper_usage.py b/tests/test_core_type_helper_usage.py
@@ -19,6 +19,7 @@
     "hyperbrowser/transport/error_utils.py",
     "hyperbrowser/mapping_utils.py",
     "hyperbrowser/client/managers/response_utils.py",
+    "hyperbrowser/client/managers/agent_payload_utils.py",
     "hyperbrowser/client/managers/agent_status_utils.py",
     "hyperbrowser/client/managers/browser_use_payload_utils.py",
     "hyperbrowser/client/managers/extension_utils.py",
