Share agent terminal-status predicate across managers

cursoragent · shrisukhani · cursoragent · commit 522fdef65767 · 2026-02-14T11:34:01.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_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),
   - `tests/test_browser_use_payload_helper_usage.py` (browser-use payload helper usage enforcement),
diff --git a/hyperbrowser/client/managers/agent_status_utils.py b/hyperbrowser/client/managers/agent_status_utils.py
@@ -0,0 +1,9 @@
+from typing import FrozenSet
+
+AGENT_TERMINAL_STATUSES: FrozenSet[str] = frozenset(
+    {"completed", "failed", "stopped"}
+)
+
+
+def is_agent_terminal_status(status: str) -> bool:
+    return status in AGENT_TERMINAL_STATUSES
diff --git a/hyperbrowser/client/managers/async_manager/agents/browser_use.py b/hyperbrowser/client/managers/async_manager/agents/browser_use.py
@@ -1,6 +1,7 @@
 from typing import Optional
 
 from ....polling import wait_for_job_result_async
+from ...agent_status_utils import is_agent_terminal_status
 from ...browser_use_payload_utils import build_browser_use_start_payload
 from ...response_utils import parse_response_model
 from ...start_job_utils import build_started_job_context
@@ -80,9 +81,7 @@ async def start_and_wait(
         return await wait_for_job_result_async(
             operation_name=operation_name,
             get_status=lambda: self.get_status(job_id).status,
-            is_terminal_status=lambda status: (
-                status in {"completed", "failed", "stopped"}
-            ),
+            is_terminal_status=is_agent_terminal_status,
             fetch_result=lambda: self.get(job_id),
             poll_interval_seconds=poll_interval_seconds,
             max_wait_seconds=max_wait_seconds,
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,6 +1,7 @@
 from typing import Optional
 
 from ....polling import wait_for_job_result_async
+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
@@ -83,9 +84,7 @@ async def start_and_wait(
         return await wait_for_job_result_async(
             operation_name=operation_name,
             get_status=lambda: self.get_status(job_id).status,
-            is_terminal_status=lambda status: (
-                status in {"completed", "failed", "stopped"}
-            ),
+            is_terminal_status=is_agent_terminal_status,
             fetch_result=lambda: self.get(job_id),
             poll_interval_seconds=poll_interval_seconds,
             max_wait_seconds=max_wait_seconds,
diff --git a/hyperbrowser/client/managers/async_manager/agents/cua.py b/hyperbrowser/client/managers/async_manager/agents/cua.py
@@ -1,6 +1,7 @@
 from typing import Optional
 
 from ....polling import wait_for_job_result_async
+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
@@ -81,9 +82,7 @@ async def start_and_wait(
         return await wait_for_job_result_async(
             operation_name=operation_name,
             get_status=lambda: self.get_status(job_id).status,
-            is_terminal_status=lambda status: (
-                status in {"completed", "failed", "stopped"}
-            ),
+            is_terminal_status=is_agent_terminal_status,
             fetch_result=lambda: self.get(job_id),
             poll_interval_seconds=poll_interval_seconds,
             max_wait_seconds=max_wait_seconds,
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,6 +1,7 @@
 from typing import Optional
 
 from ....polling import wait_for_job_result_async
+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
@@ -83,9 +84,7 @@ async def start_and_wait(
         return await wait_for_job_result_async(
             operation_name=operation_name,
             get_status=lambda: self.get_status(job_id).status,
-            is_terminal_status=lambda status: (
-                status in {"completed", "failed", "stopped"}
-            ),
+            is_terminal_status=is_agent_terminal_status,
             fetch_result=lambda: self.get(job_id),
             poll_interval_seconds=poll_interval_seconds,
             max_wait_seconds=max_wait_seconds,
diff --git a/hyperbrowser/client/managers/async_manager/agents/hyper_agent.py b/hyperbrowser/client/managers/async_manager/agents/hyper_agent.py
@@ -1,6 +1,7 @@
 from typing import Optional
 
 from ....polling import wait_for_job_result_async
+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
@@ -83,9 +84,7 @@ async def start_and_wait(
         return await wait_for_job_result_async(
             operation_name=operation_name,
             get_status=lambda: self.get_status(job_id).status,
-            is_terminal_status=lambda status: (
-                status in {"completed", "failed", "stopped"}
-            ),
+            is_terminal_status=is_agent_terminal_status,
             fetch_result=lambda: self.get(job_id),
             poll_interval_seconds=poll_interval_seconds,
             max_wait_seconds=max_wait_seconds,
diff --git a/hyperbrowser/client/managers/sync_manager/agents/browser_use.py b/hyperbrowser/client/managers/sync_manager/agents/browser_use.py
@@ -1,6 +1,7 @@
 from typing import Optional
 
 from ....polling import wait_for_job_result
+from ...agent_status_utils import is_agent_terminal_status
 from ...browser_use_payload_utils import build_browser_use_start_payload
 from ...response_utils import parse_response_model
 from ...start_job_utils import build_started_job_context
@@ -78,9 +79,7 @@ def start_and_wait(
         return wait_for_job_result(
             operation_name=operation_name,
             get_status=lambda: self.get_status(job_id).status,
-            is_terminal_status=lambda status: (
-                status in {"completed", "failed", "stopped"}
-            ),
+            is_terminal_status=is_agent_terminal_status,
             fetch_result=lambda: self.get(job_id),
             poll_interval_seconds=poll_interval_seconds,
             max_wait_seconds=max_wait_seconds,
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,6 +1,7 @@
 from typing import Optional
 
 from ....polling import wait_for_job_result
+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
@@ -83,9 +84,7 @@ def start_and_wait(
         return wait_for_job_result(
             operation_name=operation_name,
             get_status=lambda: self.get_status(job_id).status,
-            is_terminal_status=lambda status: (
-                status in {"completed", "failed", "stopped"}
-            ),
+            is_terminal_status=is_agent_terminal_status,
             fetch_result=lambda: self.get(job_id),
             poll_interval_seconds=poll_interval_seconds,
             max_wait_seconds=max_wait_seconds,
diff --git a/hyperbrowser/client/managers/sync_manager/agents/cua.py b/hyperbrowser/client/managers/sync_manager/agents/cua.py
@@ -1,6 +1,7 @@
 from typing import Optional
 
 from ....polling import wait_for_job_result
+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
@@ -81,9 +82,7 @@ def start_and_wait(
         return wait_for_job_result(
             operation_name=operation_name,
             get_status=lambda: self.get_status(job_id).status,
-            is_terminal_status=lambda status: (
-                status in {"completed", "failed", "stopped"}
-            ),
+            is_terminal_status=is_agent_terminal_status,
             fetch_result=lambda: self.get(job_id),
             poll_interval_seconds=poll_interval_seconds,
             max_wait_seconds=max_wait_seconds,
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,6 +1,7 @@
 from typing import Optional
 
 from ....polling import wait_for_job_result
+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
@@ -83,9 +84,7 @@ def start_and_wait(
         return wait_for_job_result(
             operation_name=operation_name,
             get_status=lambda: self.get_status(job_id).status,
-            is_terminal_status=lambda status: (
-                status in {"completed", "failed", "stopped"}
-            ),
+            is_terminal_status=is_agent_terminal_status,
             fetch_result=lambda: self.get(job_id),
             poll_interval_seconds=poll_interval_seconds,
             max_wait_seconds=max_wait_seconds,
diff --git a/hyperbrowser/client/managers/sync_manager/agents/hyper_agent.py b/hyperbrowser/client/managers/sync_manager/agents/hyper_agent.py
@@ -1,6 +1,7 @@
 from typing import Optional
 
 from ....polling import wait_for_job_result
+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
@@ -81,9 +82,7 @@ def start_and_wait(
         return wait_for_job_result(
             operation_name=operation_name,
             get_status=lambda: self.get_status(job_id).status,
-            is_terminal_status=lambda status: (
-                status in {"completed", "failed", "stopped"}
-            ),
+            is_terminal_status=is_agent_terminal_status,
             fetch_result=lambda: self.get(job_id),
             poll_interval_seconds=poll_interval_seconds,
             max_wait_seconds=max_wait_seconds,
diff --git a/tests/test_agent_status_utils.py b/tests/test_agent_status_utils.py
@@ -0,0 +1,19 @@
+from hyperbrowser.client.managers.agent_status_utils import (
+    AGENT_TERMINAL_STATUSES,
+    is_agent_terminal_status,
+)
+
+
+def test_agent_terminal_statuses_constant_contains_expected_values():
+    assert AGENT_TERMINAL_STATUSES == {"completed", "failed", "stopped"}
+
+
+def test_is_agent_terminal_status_returns_true_for_terminal_values():
+    assert is_agent_terminal_status("completed") is True
+    assert is_agent_terminal_status("failed") is True
+    assert is_agent_terminal_status("stopped") is True
+
+
+def test_is_agent_terminal_status_returns_false_for_non_terminal_values():
+    assert is_agent_terminal_status("running") is False
+    assert is_agent_terminal_status("pending") is False
diff --git a/tests/test_agent_terminal_status_helper_usage.py b/tests/test_agent_terminal_status_helper_usage.py
@@ -0,0 +1,26 @@
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.architecture
+
+
+MODULES = (
+    "hyperbrowser/client/managers/sync_manager/agents/browser_use.py",
+    "hyperbrowser/client/managers/async_manager/agents/browser_use.py",
+    "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_terminal_status_helper():
+    for module_path in MODULES:
+        module_text = Path(module_path).read_text(encoding="utf-8")
+        assert "is_agent_terminal_status" in module_text
+        assert 'status in {"completed", "failed", "stopped"}' not in module_text
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_terminal_status_helper_usage.py",
     "tests/test_guardrail_ast_utils.py",
     "tests/test_manager_model_dump_usage.py",
     "tests/test_mapping_reader_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_status_utils.py",
     "hyperbrowser/client/managers/browser_use_payload_utils.py",
     "hyperbrowser/client/managers/extension_utils.py",
     "hyperbrowser/client/managers/list_parsing_utils.py",
