Centralize shared agent operation metadata

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

Author: cursoragent

CONTRIBUTING.md

@@ -77,6 +77,7 @@ This runs lint, format checks, compile checks, tests, and package build.
 - Prefer deterministic unit tests over network-dependent tests.
 - Preserve architectural guardrails with focused tests. Current guard suites include:
   - `tests/test_agent_examples_coverage.py` (agent task example coverage enforcement),
+  - `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_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_operation_metadata.py

@@ -0,0 +1,57 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class AgentOperationMetadata:
+    start_operation_name: str
+    task_operation_name: str
+    status_operation_name: str
+    stop_operation_name: str
+    start_error_message: str
+    operation_name_prefix: str
+
+
+BROWSER_USE_OPERATION_METADATA = AgentOperationMetadata(
+    start_operation_name="browser-use start",
+    task_operation_name="browser-use task",
+    status_operation_name="browser-use task status",
+    stop_operation_name="browser-use task stop",
+    start_error_message="Failed to start browser-use task job",
+    operation_name_prefix="browser-use task job ",
+)
+
+HYPER_AGENT_OPERATION_METADATA = AgentOperationMetadata(
+    start_operation_name="hyper agent start",
+    task_operation_name="hyper agent task",
+    status_operation_name="hyper agent task status",
+    stop_operation_name="hyper agent task stop",
+    start_error_message="Failed to start HyperAgent task",
+    operation_name_prefix="HyperAgent task ",
+)
+
+GEMINI_COMPUTER_USE_OPERATION_METADATA = AgentOperationMetadata(
+    start_operation_name="gemini computer use start",
+    task_operation_name="gemini computer use task",
+    status_operation_name="gemini computer use task status",
+    stop_operation_name="gemini computer use task stop",
+    start_error_message="Failed to start Gemini Computer Use task job",
+    operation_name_prefix="Gemini Computer Use task job ",
+)
+
+CLAUDE_COMPUTER_USE_OPERATION_METADATA = AgentOperationMetadata(
+    start_operation_name="claude computer use start",
+    task_operation_name="claude computer use task",
+    status_operation_name="claude computer use task status",
+    stop_operation_name="claude computer use task stop",
+    start_error_message="Failed to start Claude Computer Use task job",
+    operation_name_prefix="Claude Computer Use task job ",
+)
+
+CUA_OPERATION_METADATA = AgentOperationMetadata(
+    start_operation_name="cua start",
+    task_operation_name="cua task",
+    status_operation_name="cua task status",
+    stop_operation_name="cua task stop",
+    start_error_message="Failed to start CUA task job",
+    operation_name_prefix="CUA task job ",
+)

hyperbrowser/client/managers/async_manager/agents/browser_use.py

@@ -2,6 +2,7 @@
 
 from ...agent_status_utils import is_agent_terminal_status
 from ...browser_use_payload_utils import build_browser_use_start_payload
+from ...agent_operation_metadata import BROWSER_USE_OPERATION_METADATA
 from ...agent_route_constants import BROWSER_USE_TASK_ROUTE_PREFIX
 from ...agent_stop_utils import stop_agent_task_async
 from ...agent_task_read_utils import get_agent_task_async, get_agent_task_status_async
@@ -24,6 +25,7 @@
 
 
 class BrowserUseManager:
+    _OPERATION_METADATA = BROWSER_USE_OPERATION_METADATA
     _ROUTE_PREFIX = BROWSER_USE_TASK_ROUTE_PREFIX
 
     def __init__(self, client):
@@ -40,7 +42,7 @@ async def start(
         return parse_response_model(
             response.data,
             model=StartBrowserUseTaskResponse,
-            operation_name="browser-use start",
+            operation_name=self._OPERATION_METADATA.start_operation_name,
         )
 
     async def get(self, job_id: str) -> BrowserUseTaskResponse:
@@ -49,7 +51,7 @@ async def get(self, job_id: str) -> BrowserUseTaskResponse:
             route_prefix=self._ROUTE_PREFIX,
             job_id=job_id,
             model=BrowserUseTaskResponse,
-            operation_name="browser-use task",
+            operation_name=self._OPERATION_METADATA.task_operation_name,
         )
 
     async def get_status(self, job_id: str) -> BrowserUseTaskStatusResponse:
@@ -58,15 +60,15 @@ async def get_status(self, job_id: str) -> BrowserUseTaskStatusResponse:
             route_prefix=self._ROUTE_PREFIX,
             job_id=job_id,
             model=BrowserUseTaskStatusResponse,
-            operation_name="browser-use task status",
+            operation_name=self._OPERATION_METADATA.status_operation_name,
         )
 
     async def stop(self, job_id: str) -> BasicResponse:
         return await stop_agent_task_async(
             client=self._client,
             route_prefix=self._ROUTE_PREFIX,
             job_id=job_id,
-            operation_name="browser-use task stop",
+            operation_name=self._OPERATION_METADATA.stop_operation_name,
         )
 
     async def start_and_wait(
@@ -79,8 +81,8 @@ async def start_and_wait(
         job_start_resp = await self.start(params)
         job_id, operation_name = build_started_job_context(
             started_job_id=job_start_resp.job_id,
-            start_error_message="Failed to start browser-use task job",
-            operation_name_prefix="browser-use task job ",
+            start_error_message=self._OPERATION_METADATA.start_error_message,
+            operation_name_prefix=self._OPERATION_METADATA.operation_name_prefix,
         )
 
         return await wait_for_job_result_with_defaults_async(

hyperbrowser/client/managers/async_manager/agents/claude_computer_use.py

@@ -1,6 +1,7 @@
 from typing import Optional
 
 from ...agent_payload_utils import build_agent_start_payload
+from ...agent_operation_metadata import CLAUDE_COMPUTER_USE_OPERATION_METADATA
 from ...agent_route_constants import CLAUDE_COMPUTER_USE_TASK_ROUTE_PREFIX
 from ...agent_status_utils import is_agent_terminal_status
 from ...agent_stop_utils import stop_agent_task_async
@@ -24,6 +25,7 @@
 
 
 class ClaudeComputerUseManager:
+    _OPERATION_METADATA = CLAUDE_COMPUTER_USE_OPERATION_METADATA
     _ROUTE_PREFIX = CLAUDE_COMPUTER_USE_TASK_ROUTE_PREFIX
 
     def __init__(self, client):
@@ -43,7 +45,7 @@ async def start(
         return parse_response_model(
             response.data,
             model=StartClaudeComputerUseTaskResponse,
-            operation_name="claude computer use start",
+            operation_name=self._OPERATION_METADATA.start_operation_name,
         )
 
     async def get(self, job_id: str) -> ClaudeComputerUseTaskResponse:
@@ -52,7 +54,7 @@ async def get(self, job_id: str) -> ClaudeComputerUseTaskResponse:
             route_prefix=self._ROUTE_PREFIX,
             job_id=job_id,
             model=ClaudeComputerUseTaskResponse,
-            operation_name="claude computer use task",
+            operation_name=self._OPERATION_METADATA.task_operation_name,
         )
 
     async def get_status(self, job_id: str) -> ClaudeComputerUseTaskStatusResponse:
@@ -61,15 +63,15 @@ async def get_status(self, job_id: str) -> ClaudeComputerUseTaskStatusResponse:
             route_prefix=self._ROUTE_PREFIX,
             job_id=job_id,
             model=ClaudeComputerUseTaskStatusResponse,
-            operation_name="claude computer use task status",
+            operation_name=self._OPERATION_METADATA.status_operation_name,
         )
 
     async def stop(self, job_id: str) -> BasicResponse:
         return await stop_agent_task_async(
             client=self._client,
             route_prefix=self._ROUTE_PREFIX,
             job_id=job_id,
-            operation_name="claude computer use task stop",
+            operation_name=self._OPERATION_METADATA.stop_operation_name,
         )
 
     async def start_and_wait(
@@ -82,8 +84,8 @@ async def start_and_wait(
         job_start_resp = await self.start(params)
         job_id, operation_name = build_started_job_context(
             started_job_id=job_start_resp.job_id,
-            start_error_message="Failed to start Claude Computer Use task job",
-            operation_name_prefix="Claude Computer Use task job ",
+            start_error_message=self._OPERATION_METADATA.start_error_message,
+            operation_name_prefix=self._OPERATION_METADATA.operation_name_prefix,
         )
 
         return await wait_for_job_result_with_defaults_async(

hyperbrowser/client/managers/async_manager/agents/cua.py

@@ -1,6 +1,7 @@
 from typing import Optional
 
 from ...agent_payload_utils import build_agent_start_payload
+from ...agent_operation_metadata import CUA_OPERATION_METADATA
 from ...agent_route_constants import CUA_TASK_ROUTE_PREFIX
 from ...agent_status_utils import is_agent_terminal_status
 from ...agent_stop_utils import stop_agent_task_async
@@ -24,6 +25,7 @@
 
 
 class CuaManager:
+    _OPERATION_METADATA = CUA_OPERATION_METADATA
     _ROUTE_PREFIX = CUA_TASK_ROUTE_PREFIX
 
     def __init__(self, client):
@@ -41,7 +43,7 @@ async def start(self, params: StartCuaTaskParams) -> StartCuaTaskResponse:
         return parse_response_model(
             response.data,
             model=StartCuaTaskResponse,
-            operation_name="cua start",
+            operation_name=self._OPERATION_METADATA.start_operation_name,
         )
 
     async def get(self, job_id: str) -> CuaTaskResponse:
@@ -50,7 +52,7 @@ async def get(self, job_id: str) -> CuaTaskResponse:
             route_prefix=self._ROUTE_PREFIX,
             job_id=job_id,
             model=CuaTaskResponse,
-            operation_name="cua task",
+            operation_name=self._OPERATION_METADATA.task_operation_name,
         )
 
     async def get_status(self, job_id: str) -> CuaTaskStatusResponse:
@@ -59,15 +61,15 @@ async def get_status(self, job_id: str) -> CuaTaskStatusResponse:
             route_prefix=self._ROUTE_PREFIX,
             job_id=job_id,
             model=CuaTaskStatusResponse,
-            operation_name="cua task status",
+            operation_name=self._OPERATION_METADATA.status_operation_name,
         )
 
     async def stop(self, job_id: str) -> BasicResponse:
         return await stop_agent_task_async(
             client=self._client,
             route_prefix=self._ROUTE_PREFIX,
             job_id=job_id,
-            operation_name="cua task stop",
+            operation_name=self._OPERATION_METADATA.stop_operation_name,
         )
 
     async def start_and_wait(
@@ -80,8 +82,8 @@ async def start_and_wait(
         job_start_resp = await self.start(params)
         job_id, operation_name = build_started_job_context(
             started_job_id=job_start_resp.job_id,
-            start_error_message="Failed to start CUA task job",
-            operation_name_prefix="CUA task job ",
+            start_error_message=self._OPERATION_METADATA.start_error_message,
+            operation_name_prefix=self._OPERATION_METADATA.operation_name_prefix,
         )
 
         return await wait_for_job_result_with_defaults_async(

hyperbrowser/client/managers/async_manager/agents/gemini_computer_use.py

@@ -1,6 +1,7 @@
 from typing import Optional
 
 from ...agent_payload_utils import build_agent_start_payload
+from ...agent_operation_metadata import GEMINI_COMPUTER_USE_OPERATION_METADATA
 from ...agent_route_constants import GEMINI_COMPUTER_USE_TASK_ROUTE_PREFIX
 from ...agent_status_utils import is_agent_terminal_status
 from ...agent_stop_utils import stop_agent_task_async
@@ -24,6 +25,7 @@
 
 
 class GeminiComputerUseManager:
+    _OPERATION_METADATA = GEMINI_COMPUTER_USE_OPERATION_METADATA
     _ROUTE_PREFIX = GEMINI_COMPUTER_USE_TASK_ROUTE_PREFIX
 
     def __init__(self, client):
@@ -43,7 +45,7 @@ async def start(
         return parse_response_model(
             response.data,
             model=StartGeminiComputerUseTaskResponse,
-            operation_name="gemini computer use start",
+            operation_name=self._OPERATION_METADATA.start_operation_name,
         )
 
     async def get(self, job_id: str) -> GeminiComputerUseTaskResponse:
@@ -52,7 +54,7 @@ async def get(self, job_id: str) -> GeminiComputerUseTaskResponse:
             route_prefix=self._ROUTE_PREFIX,
             job_id=job_id,
             model=GeminiComputerUseTaskResponse,
-            operation_name="gemini computer use task",
+            operation_name=self._OPERATION_METADATA.task_operation_name,
         )
 
     async def get_status(self, job_id: str) -> GeminiComputerUseTaskStatusResponse:
@@ -61,15 +63,15 @@ async def get_status(self, job_id: str) -> GeminiComputerUseTaskStatusResponse:
             route_prefix=self._ROUTE_PREFIX,
             job_id=job_id,
             model=GeminiComputerUseTaskStatusResponse,
-            operation_name="gemini computer use task status",
+            operation_name=self._OPERATION_METADATA.status_operation_name,
         )
 
     async def stop(self, job_id: str) -> BasicResponse:
         return await stop_agent_task_async(
             client=self._client,
             route_prefix=self._ROUTE_PREFIX,
             job_id=job_id,
-            operation_name="gemini computer use task stop",
+            operation_name=self._OPERATION_METADATA.stop_operation_name,
         )
 
     async def start_and_wait(
@@ -82,8 +84,8 @@ async def start_and_wait(
         job_start_resp = await self.start(params)
         job_id, operation_name = build_started_job_context(
             started_job_id=job_start_resp.job_id,
-            start_error_message="Failed to start Gemini Computer Use task job",
-            operation_name_prefix="Gemini Computer Use task job ",
+            start_error_message=self._OPERATION_METADATA.start_error_message,
+            operation_name_prefix=self._OPERATION_METADATA.operation_name_prefix,
         )
 
         return await wait_for_job_result_with_defaults_async(

hyperbrowser/client/managers/async_manager/agents/hyper_agent.py

@@ -1,6 +1,7 @@
 from typing import Optional
 
 from ...agent_payload_utils import build_agent_start_payload
+from ...agent_operation_metadata import HYPER_AGENT_OPERATION_METADATA
 from ...agent_route_constants import HYPER_AGENT_TASK_ROUTE_PREFIX
 from ...agent_status_utils import is_agent_terminal_status
 from ...agent_stop_utils import stop_agent_task_async
@@ -24,6 +25,7 @@
 
 
 class HyperAgentManager:
+    _OPERATION_METADATA = HYPER_AGENT_OPERATION_METADATA
     _ROUTE_PREFIX = HYPER_AGENT_TASK_ROUTE_PREFIX
 
     def __init__(self, client):
@@ -43,7 +45,7 @@ async def start(
         return parse_response_model(
             response.data,
             model=StartHyperAgentTaskResponse,
-            operation_name="hyper agent start",
+            operation_name=self._OPERATION_METADATA.start_operation_name,
         )
 
     async def get(self, job_id: str) -> HyperAgentTaskResponse:
@@ -52,7 +54,7 @@ async def get(self, job_id: str) -> HyperAgentTaskResponse:
             route_prefix=self._ROUTE_PREFIX,
             job_id=job_id,
             model=HyperAgentTaskResponse,
-            operation_name="hyper agent task",
+            operation_name=self._OPERATION_METADATA.task_operation_name,
         )
 
     async def get_status(self, job_id: str) -> HyperAgentTaskStatusResponse:
@@ -61,15 +63,15 @@ async def get_status(self, job_id: str) -> HyperAgentTaskStatusResponse:
             route_prefix=self._ROUTE_PREFIX,
             job_id=job_id,
             model=HyperAgentTaskStatusResponse,
-            operation_name="hyper agent task status",
+            operation_name=self._OPERATION_METADATA.status_operation_name,
         )
 
     async def stop(self, job_id: str) -> BasicResponse:
         return await stop_agent_task_async(
             client=self._client,
             route_prefix=self._ROUTE_PREFIX,
             job_id=job_id,
-            operation_name="hyper agent task stop",
+            operation_name=self._OPERATION_METADATA.stop_operation_name,
         )
 
     async def start_and_wait(
@@ -82,8 +84,8 @@ async def start_and_wait(
         job_start_resp = await self.start(params)
         job_id, operation_name = build_started_job_context(
             started_job_id=job_start_resp.job_id,
-            start_error_message="Failed to start HyperAgent task",
-            operation_name_prefix="HyperAgent task ",
+            start_error_message=self._OPERATION_METADATA.start_error_message,
+            operation_name_prefix=self._OPERATION_METADATA.operation_name_prefix,
         )
 
         return await wait_for_job_result_with_defaults_async(