add new tool: to_captcha

api/contracts/task_schemas.py

@@ -1,4 +1,4 @@
-from typing import Any
+from typing import Any, Literal
 
 from pydantic import BaseModel, Field
 
@@ -6,38 +6,67 @@ from api.domain.task_status import TaskStatus
 
 
 class BrowserTaskRequest(BaseModel):
-    """Запрос на запуск задачи в browser-use агенте."""
+    """Request to start a browser task."""
 
-    task: str = Field(..., description="Текстовая задача для browser-use агента")
-    timeout: int = Field(300, description="Максимальное время выполнения задачи в секундах")
-    metadata: dict[str, Any] | None = Field(default=None, description="Дополнительные метаданные клиента")
+    task: str = Field(..., description="Text task for the browser-use agent")
+    timeout: int = Field(300, description="Maximum task execution time in seconds")
+    metadata: dict[str, Any] | None = Field(default=None, description="Optional client metadata")
+
+
+class BrowserCaptchaVerification(BaseModel):
+    mode: Literal["dom_url_title"] = "dom_url_title"
+    selectors_absent: list[str] = Field(default_factory=list)
+    challenge_signals_absent: list[str] = Field(default_factory=list)
+    max_wait_seconds: int = Field(..., description="How long the task may stay paused waiting for the user")
+
+
+class BrowserHumanInterventionPayload(BaseModel):
+    status: Literal["awaiting_user_captcha"] = "awaiting_user_captcha"
+    task_id: str
+    session_id: str
+    resume_token: str
+    browser_view_url: str | None = None
+    captcha_type: Literal["cloudflare", "recaptcha", "hcaptcha", "unknown"] = "unknown"
+    instructions: str
+    detected_at: float
+    verification: BrowserCaptchaVerification
+
+
+class BrowserCaptchaReadyRequest(BaseModel):
+    user_response: str | None = Field(default=None, description="Free-form confirmation from the user")
+
+
+class BrowserCaptchaAbortRequest(BaseModel):
+    reason: str | None = Field(default=None, description="Optional reason for aborting the CAPTCHA flow")
 
 
 class BrowserTaskAcceptedResponse(BaseModel):
-    """Ответ о том, что задача принята в обработку."""
+    """Response indicating that a task was accepted for processing."""
 
     task_id: str
     status: TaskStatus
 
 
 class BrowserTaskStatusResponse(BaseModel):
-    """Текущий статус задачи и временные отметки ее выполнения."""
+    """Current task status and timestamps."""
 
     task_id: str
     status: TaskStatus
-    create_at: float = Field(..., description="Время создания задачи в Unix timestamp")
-    started_at: float | None = Field(default=None, description="Время начала выполнения в Unix timestamp")
-    finished_at: float | None = Field(default=None, description="Время завершения выполнения в Unix timestamp")
-    error: str | None = Field(default=None, description="Текст ошибки, если задача завершилась с ошибкой")
+    create_at: float = Field(..., description="Task creation time as a Unix timestamp")
+    started_at: float | None = Field(default=None, description="Task start time as a Unix timestamp")
+    finished_at: float | None = Field(default=None, description="Task completion time as a Unix timestamp")
+    error: str | None = Field(default=None, description="Task error when applicable")
+    human_intervention: BrowserHumanInterventionPayload | None = None
 
 
 class BrowserTaskResultResponse(BaseModel):
-    """Финальный результат выполнения задачи в browser-use."""
+    """Terminal result or meaningful paused state for a browser task."""
 
     task_id: str
     status: TaskStatus
-    success: bool = Field(..., description="Успешно ли выполнена задача")
-    execution_time: float = Field(..., description="Фактическое время выполнения в секундах")
-    result: str | None = Field(default=None, description="Итоговый текстовый результат")
-    error: str | None = Field(default=None, description="Текст ошибки, если выполнение не удалось")
-    raw_response: dict[str, Any] | None = Field(default=None, description="Сырой ответ от browser-use RPC")
+    success: bool = Field(..., description="Whether the task completed successfully")
+    execution_time: float = Field(..., description="Observed execution time in seconds")
+    result: str | None = Field(default=None, description="Final textual result when available")
+    error: str | None = Field(default=None, description="Error text when execution failed")
+    raw_response: dict[str, Any] | None = Field(default=None, description="Raw payload returned by the browser runtime")
+    human_intervention: BrowserHumanInterventionPayload | None = None