Reuse shared route builders in agent request helpers

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

Author: cursoragent

CONTRIBUTING.md

@@ -80,6 +80,7 @@ This runs lint, format checks, compile checks, tests, and package build.
   - `tests/test_agent_helper_boundary.py` (agent manager boundary enforcement for shared request/response helpers),
   - `tests/test_agent_operation_metadata_usage.py` (shared agent operation-metadata usage enforcement),
   - `tests/test_agent_payload_helper_usage.py` (shared agent start-payload helper usage enforcement),
+  - `tests/test_agent_route_builder_usage.py` (shared agent read/stop route-builder usage enforcement),
   - `tests/test_agent_start_helper_usage.py` (shared agent start-request helper usage enforcement),
   - `tests/test_agent_stop_helper_usage.py` (shared agent stop-request helper usage enforcement),
   - `tests/test_agent_task_read_helper_usage.py` (shared agent task read-helper usage enforcement),

hyperbrowser/client/managers/agent_stop_utils.py

@@ -2,6 +2,7 @@
 
 from hyperbrowser.models import BasicResponse
 
+from .job_route_builders import build_job_action_route
 from .response_utils import parse_response_model
 
 
@@ -13,7 +14,9 @@ def stop_agent_task(
     operation_name: str,
 ) -> BasicResponse:
     response = client.transport.put(
-        client._build_url(f"{route_prefix}/{job_id}/stop"),
+        client._build_url(
+            build_job_action_route(route_prefix, job_id, "/stop"),
+        ),
     )
     return parse_response_model(
         response.data,
@@ -30,7 +33,9 @@ async def stop_agent_task_async(
     operation_name: str,
 ) -> BasicResponse:
     response = await client.transport.put(
-        client._build_url(f"{route_prefix}/{job_id}/stop"),
+        client._build_url(
+            build_job_action_route(route_prefix, job_id, "/stop"),
+        ),
     )
     return parse_response_model(
         response.data,

hyperbrowser/client/managers/agent_task_read_utils.py

@@ -1,5 +1,6 @@
 from typing import Any, Type, TypeVar
 
+from .job_route_builders import build_job_route, build_job_status_route
 from .response_utils import parse_response_model
 
 T = TypeVar("T")
@@ -14,7 +15,7 @@ def get_agent_task(
     operation_name: str,
 ) -> T:
     response = client.transport.get(
-        client._build_url(f"{route_prefix}/{job_id}"),
+        client._build_url(build_job_route(route_prefix, job_id)),
     )
     return parse_response_model(
         response.data,
@@ -32,7 +33,7 @@ def get_agent_task_status(
     operation_name: str,
 ) -> T:
     response = client.transport.get(
-        client._build_url(f"{route_prefix}/{job_id}/status"),
+        client._build_url(build_job_status_route(route_prefix, job_id)),
     )
     return parse_response_model(
         response.data,
@@ -50,7 +51,7 @@ async def get_agent_task_async(
     operation_name: str,
 ) -> T:
     response = await client.transport.get(
-        client._build_url(f"{route_prefix}/{job_id}"),
+        client._build_url(build_job_route(route_prefix, job_id)),
     )
     return parse_response_model(
         response.data,
@@ -68,7 +69,7 @@ async def get_agent_task_status_async(
     operation_name: str,
 ) -> T:
     response = await client.transport.get(
-        client._build_url(f"{route_prefix}/{job_id}/status"),
+        client._build_url(build_job_status_route(route_prefix, job_id)),
     )
     return parse_response_model(
         response.data,

hyperbrowser/client/managers/job_route_builders.py

@@ -10,3 +10,11 @@ def build_job_status_route(
     job_id: str,
 ) -> str:
     return f"{route_prefix}/{job_id}/status"
+
+
+def build_job_action_route(
+    route_prefix: str,
+    job_id: str,
+    action_suffix: str,
+) -> str:
+    return f"{route_prefix}/{job_id}{action_suffix}"

tests/test_agent_route_builder_usage.py

@@ -0,0 +1,25 @@
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.architecture
+
+
+def test_agent_task_read_helpers_use_shared_job_route_builders():
+    module_text = Path(
+        "hyperbrowser/client/managers/agent_task_read_utils.py"
+    ).read_text(encoding="utf-8")
+    assert "job_route_builders import build_job_route, build_job_status_route" in module_text
+    assert "build_job_route(route_prefix, job_id)" in module_text
+    assert "build_job_status_route(route_prefix, job_id)" in module_text
+    assert 'f"{route_prefix}/{job_id}"' not in module_text
+    assert 'f"{route_prefix}/{job_id}/status"' not in module_text
+
+
+def test_agent_stop_helpers_use_shared_job_route_builders():
+    module_text = Path("hyperbrowser/client/managers/agent_stop_utils.py").read_text(
+        encoding="utf-8"
+    )
+    assert "job_route_builders import build_job_action_route" in module_text
+    assert 'build_job_action_route(route_prefix, job_id, "/stop")' in module_text
+    assert 'f"{route_prefix}/{job_id}/stop"' not in module_text

tests/test_architecture_marker_usage.py

@@ -10,6 +10,7 @@
     "tests/test_agent_helper_boundary.py",
     "tests/test_agent_operation_metadata_usage.py",
     "tests/test_agent_payload_helper_usage.py",
+    "tests/test_agent_route_builder_usage.py",
     "tests/test_agent_start_helper_usage.py",
     "tests/test_agent_task_read_helper_usage.py",
     "tests/test_agent_stop_helper_usage.py",

tests/test_job_route_builders.py

@@ -1,4 +1,5 @@
 from hyperbrowser.client.managers.job_route_builders import (
+    build_job_action_route,
     build_job_route,
     build_job_status_route,
 )
@@ -15,3 +16,10 @@ def test_build_job_status_route_composes_job_status_route_path():
         build_job_status_route("/web/crawl", "job_456")
         == "/web/crawl/job_456/status"
     )
+
+
+def test_build_job_action_route_composes_job_action_route_path():
+    assert (
+        build_job_action_route("/task/browser-use", "job_123", "/stop")
+        == "/task/browser-use/job_123/stop"
+    )