Centralize computer action request and metadata handling

Co-authored-by: Shri Sukhani <shrisukhani@users.noreply.github.com>

Author: cursoragent

CONTRIBUTING.md

@@ -89,7 +89,9 @@ This runs lint, format checks, compile checks, tests, and package build.
   - `tests/test_browser_use_payload_helper_usage.py` (browser-use payload helper usage enforcement),
   - `tests/test_ci_workflow_quality_gates.py` (CI guard-stage + make-target enforcement),
   - `tests/test_computer_action_endpoint_helper_usage.py` (computer-action endpoint-normalization helper usage enforcement),
+  - `tests/test_computer_action_operation_metadata_usage.py` (computer-action manager operation-metadata usage enforcement),
   - `tests/test_computer_action_payload_helper_usage.py` (computer-action payload helper usage enforcement),
+  - `tests/test_computer_action_request_helper_usage.py` (computer-action manager request-helper usage enforcement),
   - `tests/test_contributing_architecture_guard_listing.py` (`CONTRIBUTING.md` architecture-guard inventory completeness enforcement),
   - `tests/test_core_type_helper_usage.py` (core transport/config/header/file/polling/session/error/parsing manager+tool module enforcement of shared plain-type helper usage),
   - `tests/test_default_serialization_helper_usage.py` (default optional-query serialization helper usage enforcement),

hyperbrowser/client/managers/async_manager/computer_action.py

@@ -1,9 +1,10 @@
 from typing import Union, List, Optional
 from hyperbrowser.exceptions import HyperbrowserError
 from hyperbrowser.type_utils import is_plain_string, is_string_subclass_instance
+from ..computer_action_operation_metadata import COMPUTER_ACTION_OPERATION_METADATA
+from ..computer_action_request_utils import execute_computer_action_request_async
 from ..computer_action_utils import normalize_computer_action_endpoint
 from ..computer_action_payload_utils import build_computer_action_payload
-from ..response_utils import parse_response_model
 from hyperbrowser.models import (
     SessionDetail,
     ComputerActionParams,
@@ -26,6 +27,8 @@
 
 
 class ComputerActionManager:
+    _OPERATION_METADATA = COMPUTER_ACTION_OPERATION_METADATA
+
     def __init__(self, client):
         self._client = client
 
@@ -45,14 +48,11 @@ async def _execute_request(
 
         payload = build_computer_action_payload(params)
 
-        response = await self._client.transport.post(
-            normalized_computer_action_endpoint,
-            data=payload,
-        )
-        return parse_response_model(
-            response.data,
-            model=ComputerActionResponse,
-            operation_name="computer action",
+        return await execute_computer_action_request_async(
+            client=self._client,
+            endpoint=normalized_computer_action_endpoint,
+            payload=payload,
+            operation_name=self._OPERATION_METADATA.operation_name,
         )
 
     async def click(

hyperbrowser/client/managers/computer_action_operation_metadata.py

@@ -0,0 +1,11 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ComputerActionOperationMetadata:
+    operation_name: str
+
+
+COMPUTER_ACTION_OPERATION_METADATA = ComputerActionOperationMetadata(
+    operation_name="computer action",
+)

hyperbrowser/client/managers/computer_action_request_utils.py

@@ -0,0 +1,41 @@
+from typing import Any
+
+from hyperbrowser.models import ComputerActionResponse
+
+from .response_utils import parse_response_model
+
+
+def execute_computer_action_request(
+    *,
+    client: Any,
+    endpoint: str,
+    payload: dict[str, Any],
+    operation_name: str,
+) -> ComputerActionResponse:
+    response = client.transport.post(
+        endpoint,
+        data=payload,
+    )
+    return parse_response_model(
+        response.data,
+        model=ComputerActionResponse,
+        operation_name=operation_name,
+    )
+
+
+async def execute_computer_action_request_async(
+    *,
+    client: Any,
+    endpoint: str,
+    payload: dict[str, Any],
+    operation_name: str,
+) -> ComputerActionResponse:
+    response = await client.transport.post(
+        endpoint,
+        data=payload,
+    )
+    return parse_response_model(
+        response.data,
+        model=ComputerActionResponse,
+        operation_name=operation_name,
+    )

hyperbrowser/client/managers/sync_manager/computer_action.py

@@ -1,9 +1,10 @@
 from typing import Union, List, Optional
 from hyperbrowser.exceptions import HyperbrowserError
 from hyperbrowser.type_utils import is_plain_string, is_string_subclass_instance
+from ..computer_action_operation_metadata import COMPUTER_ACTION_OPERATION_METADATA
+from ..computer_action_request_utils import execute_computer_action_request
 from ..computer_action_utils import normalize_computer_action_endpoint
 from ..computer_action_payload_utils import build_computer_action_payload
-from ..response_utils import parse_response_model
 from hyperbrowser.models import (
     SessionDetail,
     ComputerActionParams,
@@ -26,6 +27,8 @@
 
 
 class ComputerActionManager:
+    _OPERATION_METADATA = COMPUTER_ACTION_OPERATION_METADATA
+
     def __init__(self, client):
         self._client = client
 
@@ -45,14 +48,11 @@ def _execute_request(
 
         payload = build_computer_action_payload(params)
 
-        response = self._client.transport.post(
-            normalized_computer_action_endpoint,
-            data=payload,
-        )
-        return parse_response_model(
-            response.data,
-            model=ComputerActionResponse,
-            operation_name="computer action",
+        return execute_computer_action_request(
+            client=self._client,
+            endpoint=normalized_computer_action_endpoint,
+            payload=payload,
+            operation_name=self._OPERATION_METADATA.operation_name,
         )
 
     def click(

tests/test_architecture_marker_usage.py

@@ -65,7 +65,9 @@
     "tests/test_example_sync_async_parity.py",
     "tests/test_example_run_instructions.py",
     "tests/test_computer_action_endpoint_helper_usage.py",
+    "tests/test_computer_action_operation_metadata_usage.py",
     "tests/test_computer_action_payload_helper_usage.py",
+    "tests/test_computer_action_request_helper_usage.py",
     "tests/test_schema_injection_helper_usage.py",
     "tests/test_session_operation_metadata_usage.py",
     "tests/test_session_route_constants_usage.py",

tests/test_computer_action_operation_metadata.py

@@ -0,0 +1,7 @@
+from hyperbrowser.client.managers.computer_action_operation_metadata import (
+    COMPUTER_ACTION_OPERATION_METADATA,
+)
+
+
+def test_computer_action_operation_metadata_values():
+    assert COMPUTER_ACTION_OPERATION_METADATA.operation_name == "computer action"

tests/test_computer_action_operation_metadata_usage.py

@@ -0,0 +1,20 @@
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.architecture
+
+
+MODULES = (
+    "hyperbrowser/client/managers/sync_manager/computer_action.py",
+    "hyperbrowser/client/managers/async_manager/computer_action.py",
+)
+
+
+def test_computer_action_managers_use_shared_operation_metadata():
+    for module_path in MODULES:
+        module_text = Path(module_path).read_text(encoding="utf-8")
+        assert "computer_action_operation_metadata import" in module_text
+        assert "_OPERATION_METADATA = " in module_text
+        assert "operation_name=self._OPERATION_METADATA." in module_text
+        assert 'operation_name="computer action"' not in module_text

tests/test_computer_action_request_helper_usage.py

@@ -0,0 +1,23 @@
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.architecture
+
+
+def test_sync_computer_action_manager_uses_request_helper():
+    module_text = Path(
+        "hyperbrowser/client/managers/sync_manager/computer_action.py"
+    ).read_text(encoding="utf-8")
+    assert "execute_computer_action_request(" in module_text
+    assert "_client.transport.post(" not in module_text
+    assert "parse_response_model(" not in module_text
+
+
+def test_async_computer_action_manager_uses_request_helper():
+    module_text = Path(
+        "hyperbrowser/client/managers/async_manager/computer_action.py"
+    ).read_text(encoding="utf-8")
+    assert "execute_computer_action_request_async(" in module_text
+    assert "_client.transport.post(" not in module_text
+    assert "parse_response_model(" not in module_text

tests/test_computer_action_request_utils.py

@@ -0,0 +1,78 @@
+import asyncio
+from types import SimpleNamespace
+
+import hyperbrowser.client.managers.computer_action_request_utils as request_utils
+
+
+def test_execute_computer_action_request_posts_and_parses_response():
+    captured = {}
+
+    class _SyncTransport:
+        def post(self, endpoint, data=None):
+            captured["endpoint"] = endpoint
+            captured["data"] = data
+            return SimpleNamespace(data={"success": True})
+
+    class _Client:
+        transport = _SyncTransport()
+
+    def _fake_parse_response_model(data, **kwargs):
+        captured["parse_data"] = data
+        captured["parse_kwargs"] = kwargs
+        return {"parsed": True}
+
+    original_parse = request_utils.parse_response_model
+    request_utils.parse_response_model = _fake_parse_response_model
+    try:
+        result = request_utils.execute_computer_action_request(
+            client=_Client(),
+            endpoint="https://example.com/cua",
+            payload={"action": {"type": "screenshot"}},
+            operation_name="computer action",
+        )
+    finally:
+        request_utils.parse_response_model = original_parse
+
+    assert result == {"parsed": True}
+    assert captured["endpoint"] == "https://example.com/cua"
+    assert captured["data"] == {"action": {"type": "screenshot"}}
+    assert captured["parse_data"] == {"success": True}
+    assert captured["parse_kwargs"]["operation_name"] == "computer action"
+
+
+def test_execute_computer_action_request_async_posts_and_parses_response():
+    captured = {}
+
+    class _AsyncTransport:
+        async def post(self, endpoint, data=None):
+            captured["endpoint"] = endpoint
+            captured["data"] = data
+            return SimpleNamespace(data={"success": True})
+
+    class _Client:
+        transport = _AsyncTransport()
+
+    def _fake_parse_response_model(data, **kwargs):
+        captured["parse_data"] = data
+        captured["parse_kwargs"] = kwargs
+        return {"parsed": True}
+
+    original_parse = request_utils.parse_response_model
+    request_utils.parse_response_model = _fake_parse_response_model
+    try:
+        result = asyncio.run(
+            request_utils.execute_computer_action_request_async(
+                client=_Client(),
+                endpoint="https://example.com/cua",
+                payload={"action": {"type": "screenshot"}},
+                operation_name="computer action",
+            )
+        )
+    finally:
+        request_utils.parse_response_model = original_parse
+
+    assert result == {"parsed": True}
+    assert captured["endpoint"] == "https://example.com/cua"
+    assert captured["data"] == {"action": {"type": "screenshot"}}
+    assert captured["parse_data"] == {"success": True}
+    assert captured["parse_kwargs"]["operation_name"] == "computer action"