morphsdk 0.2.5__py3-none-any.whl

morphsdk/resources/browser.py

@@ -0,0 +1,919 @@
+"""Browser automation resource -- AI-powered browser tasks and recordings."""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Any
+from urllib.parse import parse_qsl, quote, urlencode, urlsplit, urlunsplit
+
+from morphsdk._constants import (
+    BROWSER_BASE_URL,
+    BROWSER_TIMEOUT,
+    DEFAULT_BROWSER_MODEL,
+)
+from morphsdk.types.browser import (
+    BrowserTask,
+    BrowserTaskResult,
+    ErrorsResponse,
+    IframeOptions,
+    LiveSessionOptions,
+    RecordingStatus,
+    WebpResponse,
+)
+
+if TYPE_CHECKING:
+    from morphsdk._base import AsyncBaseClient, BaseClient
+
+
+# Base URL for the browser-use live viewer (mirrors TS live.ts).
+LIVE_BASE_URL = "https://live.browser-use.com"
+
+
+# Preset configurations for common live-session use cases (mirrors TS LIVE_PRESETS).
+LIVE_PRESETS: dict[str, LiveSessionOptions] = {
+    "readonly": LiveSessionOptions(interactive=False),
+    "interactive": LiveSessionOptions(interactive=True),
+    "monitoring": LiveSessionOptions(interactive=False, show_controls=False),
+}
+
+
+def _serialize_structured_output(schema: dict[str, Any] | str) -> str:
+    """Serialize a structured-output schema to the wire ``structured_output`` string.
+
+    The backend expects a JSON string (matching the TS SDK, which serializes
+    its Zod schema to JSON). A ``dict`` schema is JSON-encoded; a ``str`` is
+    assumed already-serialized and passed through unchanged.
+    """
+    if isinstance(schema, str):
+        return schema
+    import json
+
+    return json.dumps(schema)
+
+
+def get_structured_output(result: BrowserTaskResult) -> Any | None:
+    """Parse the structured result from a completed browser task.
+
+    Mirrors the TS ``parseStructuredTaskOutput`` JSON-parse step: returns the
+    decoded ``result.output`` (the structured payload as a string of JSON), or
+    ``None`` if there is no output or it is not valid JSON.
+    """
+    if not result.output:
+        return None
+    import json
+
+    try:
+        return json.loads(result.output)
+    except (ValueError, TypeError):
+        return None
+
+
+def _cdp_to_https(ws_url: str) -> str:
+    """Swap a CDP WebSocket scheme to HTTP(S). Mirrors TS ``cdpToHttps``."""
+    if ws_url.startswith("wss://"):
+        return "https://" + ws_url[len("wss://") :]
+    if ws_url.startswith("ws://"):
+        return "http://" + ws_url[len("ws://") :]
+    return ws_url
+
+
+def _normalize_live_url(debug_url: str) -> str:
+    """Normalize any debug URL into a valid browser-use live-viewer URL.
+
+    Mirrors TS ``normalizeLiveUrl`` and handles three input formats:
+      1. Already-correct ``https://live.browser-use.com?wss=https://...`` -- pass through.
+      2. Live viewer URL with wrong scheme in the ``wss`` param -- fix the scheme.
+      3. Raw CDP URL ``wss://UUID.cdpN.browser-use.com`` -- wrap into a live-viewer URL.
+    """
+    trimmed = debug_url.strip()
+    if not trimmed:
+        return trimmed
+
+    # Case 3: raw CDP WebSocket URL -> wrap into live viewer.
+    if trimmed.startswith("wss://") or trimmed.startswith("ws://"):
+        # encodeURIComponent equivalent: percent-encode everything unsafe.
+        encoded = quote(_cdp_to_https(trimmed), safe="")
+        return f"{LIVE_BASE_URL}?wss={encoded}"
+
+    try:
+        parts = urlsplit(trimmed)
+        if not parts.scheme:
+            raise ValueError("relative URL")
+    except ValueError:
+        return trimmed
+
+    # Case 2: live viewer URL with wrong scheme in the wss param -> fix it.
+    query = parse_qsl(parts.query, keep_blank_values=True)
+    wss = next((v for k, v in query if k == "wss"), None)
+    if wss and (wss.startswith("wss://") or wss.startswith("ws://")):
+        query = [(k, _cdp_to_https(v) if k == "wss" else v) for k, v in query]
+        new_query = urlencode(query)
+        return urlunsplit(
+            (parts.scheme, parts.netloc, parts.path, new_query, parts.fragment)
+        )
+
+    return trimmed
+
+
+def _resolve_preset(
+    options_or_preset: str | LiveSessionOptions | IframeOptions | None,
+) -> IframeOptions:
+    """Resolve a preset name or options object into :class:`IframeOptions`.
+
+    Mirrors TS ``resolvePreset``.
+    """
+    if options_or_preset is None:
+        return IframeOptions()
+    if isinstance(options_or_preset, str):
+        preset = LIVE_PRESETS.get(options_or_preset)
+        if preset is None:
+            available = ", ".join(LIVE_PRESETS)
+            raise ValueError(
+                f"Unknown preset: {options_or_preset}. Available presets: {available}"
+            )
+        return IframeOptions(**preset.model_dump(exclude_none=True))
+    if isinstance(options_or_preset, IframeOptions):
+        return options_or_preset
+    return IframeOptions(**options_or_preset.model_dump(exclude_none=True))
+
+
+def build_live_url(debug_url: str, options: LiveSessionOptions | None = None) -> str:
+    """Build a live-session URL with query parameters.
+
+    Mirrors TS ``buildLiveUrl``. *debug_url* is the live-session debug URL
+    (e.g. ``BrowserTask.debug_url``). Query-parameter names match TS exactly
+    (``interactive``, ``theme``, ``showControls``, ``pageId``, ``pageIndex``).
+    """
+    if not debug_url:
+        raise ValueError(
+            "debug_url is required. Ensure your backend returns debug_url in the "
+            "task response. Contact support@morphllm.com if you need help."
+        )
+
+    opts = options or LiveSessionOptions()
+    normalized = _normalize_live_url(debug_url)
+    parts = urlsplit(normalized)
+    query = parse_qsl(parts.query, keep_blank_values=True)
+
+    if opts.interactive is not None:
+        query.append(("interactive", "true" if opts.interactive else "false"))
+    if opts.theme is not None:
+        query.append(("theme", opts.theme))
+    if opts.show_controls is not None:
+        query.append(("showControls", "true" if opts.show_controls else "false"))
+    if opts.page_id is not None:
+        query.append(("pageId", opts.page_id))
+    if opts.page_index is not None:
+        query.append(("pageIndex", opts.page_index))
+
+    new_query = urlencode(query)
+    return urlunsplit(
+        (parts.scheme, parts.netloc, parts.path, new_query, parts.fragment)
+    )
+
+
+def build_live_iframe(
+    debug_url: str, options: str | IframeOptions | None = None
+) -> str:
+    """Build iframe HTML for embedding a live session. Mirrors TS ``buildLiveIframe``."""
+    opts = _resolve_preset(options)
+
+    session_opts = LiveSessionOptions(
+        interactive=opts.interactive,
+        theme=opts.theme,
+        show_controls=opts.show_controls,
+        page_id=opts.page_id,
+        page_index=opts.page_index,
+    )
+    src = build_live_url(debug_url, session_opts)
+
+    width_str = f"{opts.width}px" if isinstance(opts.width, int) else opts.width
+    height_str = f"{opts.height}px" if isinstance(opts.height, int) else opts.height
+
+    base_style = f"width: {width_str}; height: {height_str}; border: none;"
+    full_style = f"{base_style} {opts.style}" if opts.style else base_style
+
+    attributes = [f'src="{src}"', f'style="{full_style}"']
+    if opts.class_name:
+        attributes.append(f'class="{opts.class_name}"')
+
+    return f"<iframe {' '.join(attributes)}></iframe>"
+
+
+def build_embed_code(
+    debug_url: str, options: str | IframeOptions | None = None
+) -> str:
+    """Build a copy-paste embed snippet for a live session. Mirrors TS ``buildEmbedCode``."""
+    iframe = build_live_iframe(debug_url, options)
+    return f"<!-- Embed Morph Live Session -->\n{iframe}"
+
+
+def _map_task_result(data: dict[str, Any]) -> BrowserTaskResult:
+    """Map snake_case API response to BrowserTaskResult."""
+    return BrowserTaskResult(
+        result=data.get("result"),
+        error=data.get("error"),
+        steps_taken=data.get("steps_taken"),
+        execution_time_ms=data.get("execution_time_ms"),
+        urls=data.get("urls"),
+        action_names=data.get("action_names"),
+        errors=data.get("errors"),
+        model_actions=data.get("model_actions"),
+        is_done=data.get("is_done"),
+        action_history=data.get("action_history"),
+        action_results=data.get("action_results"),
+        has_errors=data.get("has_errors"),
+        number_of_steps=data.get("number_of_steps"),
+        judgement=data.get("judgement"),
+        is_validated=data.get("is_validated"),
+        replay_id=data.get("replay_id"),
+        replay_url=data.get("replay_url"),
+        recording_id=data.get("recording_id"),
+        recording_status=data.get("recording_status"),
+        task_id=data.get("task_id"),
+        status=data.get("status"),
+        output=data.get("output"),
+        debug_url=data.get("debug_url"),
+    )
+
+
+def _map_recording_status(data: dict[str, Any]) -> RecordingStatus:
+    return RecordingStatus(
+        id=data["id"],
+        status=data["status"],
+        replay_url=data.get("replay_url"),
+        network_url=data.get("network_url"),
+        console_url=data.get("console_url"),
+        video_url=data.get("video_url"),
+        result=data.get("result"),
+        total_events=data.get("total_events"),
+        file_size=data.get("file_size"),
+        duration=data.get("duration"),
+        error=data.get("error"),
+        created_at=data.get("created_at", ""),
+    )
+
+
+def _build_run_body(
+    *,
+    task: str,
+    url: str | None,
+    max_steps: int,
+    model: str,
+    region: str | None,
+    stealth: bool,
+    viewport_width: int,
+    viewport_height: int,
+    record_video: bool,
+    structured_output: dict[str, Any] | str | None,
+    auth: dict[str, Any] | None,
+    profile_id: str | None,
+) -> dict[str, Any]:
+    """Build the synchronous ``/browser-task`` request body."""
+    body: dict[str, Any] = {
+        "task": task,
+        "max_steps": max_steps,
+        "model": model,
+        "viewport_width": viewport_width,
+        "viewport_height": viewport_height,
+        "record_video": record_video,
+    }
+    if url is not None:
+        body["url"] = url
+    if region is not None:
+        body["region"] = region
+    if not stealth:
+        body["stealth"] = False
+    if structured_output is not None:
+        body["structured_output"] = _serialize_structured_output(structured_output)
+    if auth is not None:
+        body["auth"] = auth
+    if profile_id is not None:
+        body["profile_id"] = profile_id
+    return body
+
+
+def _build_create_task_body(
+    *,
+    task: str,
+    url: str | None,
+    max_steps: int,
+    model: str,
+    record_video: bool,
+    viewport_width: int,
+    viewport_height: int,
+    structured_output: dict[str, Any] | str | None,
+    auth: dict[str, Any] | None,
+    profile_id: str | None,
+    extra: dict[str, Any],
+) -> dict[str, Any]:
+    """Build the async ``/browser-task/async`` request body."""
+    body: dict[str, Any] = {
+        "task": task,
+        "max_steps": max_steps,
+        "model": model,
+        "viewport_width": viewport_width,
+        "viewport_height": viewport_height,
+        "record_video": record_video,
+    }
+    if url is not None:
+        body["url"] = url
+    if structured_output is not None:
+        body["structured_output"] = _serialize_structured_output(structured_output)
+    if auth is not None:
+        body["auth"] = auth
+    if profile_id is not None:
+        body["profile_id"] = profile_id
+    body.update(extra)
+    return body
+
+
+def _task_to_browser_task(data: dict[str, Any]) -> BrowserTask:
+    """Map a ``/browser-task/async`` response into a :class:`BrowserTask`."""
+    result = _map_task_result(data)
+    return BrowserTask(
+        task_id=result.task_id or "",
+        live_url=result.debug_url or "",
+        debug_url=result.debug_url or "",
+    )
+
+
+def _build_webp_params(
+    *,
+    width: int | None,
+    fps: int | None,
+    quality: int | None,
+    max_duration: float | None,
+    max_size_mb: float | None,
+) -> dict[str, str]:
+    """Build query params for the recordings WebP endpoint."""
+    params: dict[str, str] = {}
+    if width is not None:
+        params["width"] = str(width)
+    if fps is not None:
+        params["fps"] = str(fps)
+    if quality is not None:
+        params["quality"] = str(quality)
+    if max_duration is not None:
+        params["max_duration"] = str(max_duration)
+    if max_size_mb is not None:
+        params["max_size_mb"] = str(max_size_mb)
+    return params
+
+
+def _parse_webp(data: dict[str, Any]) -> WebpResponse:
+    """Parse a recordings WebP response."""
+    return WebpResponse(
+        webp_url=data["webp_url"],
+        cached=data["cached"],
+        width=data["width"],
+        fps=data["fps"],
+        max_duration=data.get("max_duration"),
+        file_size=data.get("file_size"),
+        max_size_mb=data.get("max_size_mb"),
+        budget_met=data.get("budget_met"),
+        quality_used=data.get("quality_used"),
+        attempts=data.get("attempts"),
+    )
+
+
+def _health_payload(data: dict[str, Any]) -> dict[str, Any]:
+    """Map a healthy ``/health`` response into the public dict shape."""
+    return {
+        "ok": True,
+        "google_configured": data.get("google_configured", False),
+        "database_configured": data.get("database_configured", False),
+        "s3_configured": data.get("s3_configured", False),
+    }
+
+
+def _health_error(exc: Exception) -> dict[str, Any]:
+    """Map a failed health check into the public dict shape."""
+    return {
+        "ok": False,
+        "google_configured": False,
+        "database_configured": False,
+        "s3_configured": False,
+        "error": str(exc),
+    }
+
+
+class ProfilesResource:
+    """Browser profile management (login state persistence)."""
+
+    def __init__(self, client: BaseClient) -> None:
+        self._client = client
+
+    def create(
+        self,
+        *,
+        name: str,
+        repo_id: str,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        """Create a new browser profile and return its metadata."""
+        response = self._client._request(
+            "POST",
+            f"{BROWSER_BASE_URL}/profiles",
+            json={"name": name, "repo_id": repo_id},
+            timeout=timeout,
+        )
+        return response.json()  # type: ignore[no-any-return]
+
+    def list(
+        self,
+        *,
+        repo_id: str | None = None,
+        timeout: float | None = None,
+    ) -> list[dict[str, Any]]:
+        """List all browser profiles."""
+        params: dict[str, str] = {}
+        if repo_id is not None:
+            params["repo_id"] = repo_id
+
+        response = self._client._request(
+            "GET",
+            f"{BROWSER_BASE_URL}/profiles",
+            params=params or None,
+            timeout=timeout,
+        )
+        data = response.json()
+        return data.get("profiles", [])  # type: ignore[no-any-return]
+
+    def get(self, profile_id: str, *, timeout: float | None = None) -> dict[str, Any]:
+        """Get a single profile by ID."""
+        response = self._client._request(
+            "GET",
+            f"{BROWSER_BASE_URL}/profiles/{profile_id}",
+            timeout=timeout,
+        )
+        return response.json()  # type: ignore[no-any-return]
+
+    def delete(self, profile_id: str, *, timeout: float | None = None) -> None:
+        """Delete a browser profile."""
+        self._client._request(
+            "DELETE",
+            f"{BROWSER_BASE_URL}/profiles/{profile_id}",
+            timeout=timeout,
+        )
+
+
+class BrowserResource:
+    """AI-powered browser automation."""
+
+    def __init__(self, client: BaseClient) -> None:
+        self._client = client
+        self.profiles = ProfilesResource(client)
+
+    def run(
+        self,
+        *,
+        task: str,
+        url: str | None = None,
+        max_steps: int = 10,
+        model: str = DEFAULT_BROWSER_MODEL,
+        region: str | None = None,
+        stealth: bool = True,
+        viewport_width: int = 1280,
+        viewport_height: int = 720,
+        record_video: bool = False,
+        structured_output: dict[str, Any] | str | None = None,
+        auth: dict[str, Any] | None = None,
+        profile_id: str | None = None,
+        timeout: float | None = None,
+    ) -> BrowserTaskResult:
+        """Execute a synchronous browser automation task.
+
+        Blocks until the task completes and returns the full result
+        including agent history, errors, and optional recording info.
+
+        Pass *structured_output* (a JSON-schema ``dict`` or pre-serialized
+        ``str``) to request a structured result; retrieve it from the
+        completed result via :func:`get_structured_output`.
+        """
+        body = _build_run_body(
+            task=task,
+            url=url,
+            max_steps=max_steps,
+            model=model,
+            region=region,
+            stealth=stealth,
+            viewport_width=viewport_width,
+            viewport_height=viewport_height,
+            record_video=record_video,
+            structured_output=structured_output,
+            auth=auth,
+            profile_id=profile_id,
+        )
+
+        response = self._client._request(
+            "POST",
+            f"{BROWSER_BASE_URL}/browser-task",
+            json=body,
+            timeout=timeout or BROWSER_TIMEOUT,
+        )
+
+        return _map_task_result(response.json())
+
+    def create_task(
+        self,
+        *,
+        task: str,
+        url: str | None = None,
+        max_steps: int = 10,
+        model: str = DEFAULT_BROWSER_MODEL,
+        record_video: bool = False,
+        viewport_width: int = 1280,
+        viewport_height: int = 720,
+        structured_output: dict[str, Any] | str | None = None,
+        auth: dict[str, Any] | None = None,
+        profile_id: str | None = None,
+        timeout: float | None = None,
+        **kwargs: Any,
+    ) -> BrowserTask:
+        """Create an async browser task and return immediately.
+
+        Returns a ``BrowserTask`` with ``task_id`` and ``debug_url``
+        for live viewing.  Poll via ``get_recording`` or use
+        ``wait_for_recording`` to block until completion.
+
+        Pass *structured_output* (a JSON-schema ``dict`` or pre-serialized
+        ``str``) to request a structured result; once the task completes,
+        retrieve it via :func:`get_structured_output`.
+        """
+        body = _build_create_task_body(
+            task=task,
+            url=url,
+            max_steps=max_steps,
+            model=model,
+            record_video=record_video,
+            viewport_width=viewport_width,
+            viewport_height=viewport_height,
+            structured_output=structured_output,
+            auth=auth,
+            profile_id=profile_id,
+            extra=kwargs,
+        )
+
+        response = self._client._request(
+            "POST",
+            f"{BROWSER_BASE_URL}/browser-task/async",
+            json=body,
+            timeout=timeout or BROWSER_TIMEOUT,
+        )
+
+        return _task_to_browser_task(response.json())
+
+    def get_recording(
+        self,
+        recording_id: str,
+        *,
+        timeout: float | None = None,
+    ) -> RecordingStatus:
+        """Get recording status and URLs."""
+        response = self._client._request(
+            "GET",
+            f"{BROWSER_BASE_URL}/recordings/{recording_id}",
+            timeout=timeout,
+        )
+        return _map_recording_status(response.json())
+
+    def wait_for_recording(
+        self,
+        recording_id: str,
+        *,
+        timeout: float = 60.0,
+        poll_interval: float = 2.0,
+    ) -> RecordingStatus:
+        """Poll ``get_recording`` until COMPLETED or ERROR."""
+        start = time.monotonic()
+        while time.monotonic() - start < timeout:
+            status = self.get_recording(recording_id)
+            if status.status in ("COMPLETED", "ERROR"):
+                return status
+            time.sleep(poll_interval)
+
+        from morphsdk._errors import APITimeoutError
+
+        raise APITimeoutError(
+            f"Recording {recording_id} did not complete within {timeout}s"
+        )
+
+    def get_webp(
+        self,
+        recording_id: str,
+        *,
+        width: int | None = None,
+        fps: int | None = None,
+        quality: int | None = None,
+        max_duration: float | None = None,
+        max_size_mb: float | None = None,
+        timeout: float | None = None,
+    ) -> WebpResponse:
+        """Get an animated WebP preview of a recording."""
+        params = _build_webp_params(
+            width=width,
+            fps=fps,
+            quality=quality,
+            max_duration=max_duration,
+            max_size_mb=max_size_mb,
+        )
+
+        response = self._client._request(
+            "GET",
+            f"{BROWSER_BASE_URL}/recordings/{recording_id}/webp",
+            params=params or None,
+            timeout=timeout,
+        )
+
+        return _parse_webp(response.json())
+
+    def get_errors(
+        self,
+        recording_id: str,
+        *,
+        timeout: float | None = None,
+    ) -> ErrorsResponse:
+        """Get errors from a recording with screenshots."""
+        response = self._client._request(
+            "GET",
+            f"{BROWSER_BASE_URL}/recordings/{recording_id}/errors",
+            timeout=timeout,
+        )
+
+        data = response.json()
+        return ErrorsResponse.model_validate(data)
+
+    def check_health(self, *, timeout: float | None = None) -> dict[str, Any]:
+        """Check if the browser worker service is healthy."""
+        try:
+            response = self._client._request(
+                "GET",
+                f"{BROWSER_BASE_URL}/health",
+                timeout=timeout or 5.0,
+            )
+            return _health_payload(response.json())
+        except Exception as exc:
+            return _health_error(exc)
+
+
+class AsyncProfilesResource:
+    """Async browser profile management (login state persistence)."""
+
+    def __init__(self, client: AsyncBaseClient) -> None:
+        self._client = client
+
+    async def create(
+        self,
+        *,
+        name: str,
+        repo_id: str,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        """Create a new browser profile and return its metadata."""
+        response = await self._client._request(
+            "POST",
+            f"{BROWSER_BASE_URL}/profiles",
+            json={"name": name, "repo_id": repo_id},
+            timeout=timeout,
+        )
+        return response.json()  # type: ignore[no-any-return]
+
+    async def list(
+        self,
+        *,
+        repo_id: str | None = None,
+        timeout: float | None = None,
+    ) -> list[dict[str, Any]]:
+        """List all browser profiles."""
+        params: dict[str, str] = {}
+        if repo_id is not None:
+            params["repo_id"] = repo_id
+
+        response = await self._client._request(
+            "GET",
+            f"{BROWSER_BASE_URL}/profiles",
+            params=params or None,
+            timeout=timeout,
+        )
+        data = response.json()
+        return data.get("profiles", [])  # type: ignore[no-any-return]
+
+    async def get(
+        self, profile_id: str, *, timeout: float | None = None
+    ) -> dict[str, Any]:
+        """Get a single profile by ID."""
+        response = await self._client._request(
+            "GET",
+            f"{BROWSER_BASE_URL}/profiles/{profile_id}",
+            timeout=timeout,
+        )
+        return response.json()  # type: ignore[no-any-return]
+
+    async def delete(self, profile_id: str, *, timeout: float | None = None) -> None:
+        """Delete a browser profile."""
+        await self._client._request(
+            "DELETE",
+            f"{BROWSER_BASE_URL}/profiles/{profile_id}",
+            timeout=timeout,
+        )
+
+
+class AsyncBrowserResource:
+    """Async AI-powered browser automation."""
+
+    def __init__(self, client: AsyncBaseClient) -> None:
+        self._client = client
+        self.profiles = AsyncProfilesResource(client)
+
+    async def run(
+        self,
+        *,
+        task: str,
+        url: str | None = None,
+        max_steps: int = 10,
+        model: str = DEFAULT_BROWSER_MODEL,
+        region: str | None = None,
+        stealth: bool = True,
+        viewport_width: int = 1280,
+        viewport_height: int = 720,
+        record_video: bool = False,
+        structured_output: dict[str, Any] | str | None = None,
+        auth: dict[str, Any] | None = None,
+        profile_id: str | None = None,
+        timeout: float | None = None,
+    ) -> BrowserTaskResult:
+        """Execute a synchronous browser automation task.
+
+        Blocks until the task completes and returns the full result
+        including agent history, errors, and optional recording info.
+
+        Pass *structured_output* (a JSON-schema ``dict`` or pre-serialized
+        ``str``) to request a structured result; retrieve it from the
+        completed result via :func:`get_structured_output`.
+        """
+        body = _build_run_body(
+            task=task,
+            url=url,
+            max_steps=max_steps,
+            model=model,
+            region=region,
+            stealth=stealth,
+            viewport_width=viewport_width,
+            viewport_height=viewport_height,
+            record_video=record_video,
+            structured_output=structured_output,
+            auth=auth,
+            profile_id=profile_id,
+        )
+
+        response = await self._client._request(
+            "POST",
+            f"{BROWSER_BASE_URL}/browser-task",
+            json=body,
+            timeout=timeout or BROWSER_TIMEOUT,
+        )
+
+        return _map_task_result(response.json())
+
+    async def create_task(
+        self,
+        *,
+        task: str,
+        url: str | None = None,
+        max_steps: int = 10,
+        model: str = DEFAULT_BROWSER_MODEL,
+        record_video: bool = False,
+        viewport_width: int = 1280,
+        viewport_height: int = 720,
+        structured_output: dict[str, Any] | str | None = None,
+        auth: dict[str, Any] | None = None,
+        profile_id: str | None = None,
+        timeout: float | None = None,
+        **kwargs: Any,
+    ) -> BrowserTask:
+        """Create an async browser task and return immediately.
+
+        Returns a ``BrowserTask`` with ``task_id`` and ``debug_url``
+        for live viewing.  Poll via ``get_recording`` or use
+        ``wait_for_recording`` to block until completion.
+
+        Pass *structured_output* (a JSON-schema ``dict`` or pre-serialized
+        ``str``) to request a structured result; once the task completes,
+        retrieve it via :func:`get_structured_output`.
+        """
+        body = _build_create_task_body(
+            task=task,
+            url=url,
+            max_steps=max_steps,
+            model=model,
+            record_video=record_video,
+            viewport_width=viewport_width,
+            viewport_height=viewport_height,
+            structured_output=structured_output,
+            auth=auth,
+            profile_id=profile_id,
+            extra=kwargs,
+        )
+
+        response = await self._client._request(
+            "POST",
+            f"{BROWSER_BASE_URL}/browser-task/async",
+            json=body,
+            timeout=timeout or BROWSER_TIMEOUT,
+        )
+
+        return _task_to_browser_task(response.json())
+
+    async def get_recording(
+        self,
+        recording_id: str,
+        *,
+        timeout: float | None = None,
+    ) -> RecordingStatus:
+        """Get recording status and URLs."""
+        response = await self._client._request(
+            "GET",
+            f"{BROWSER_BASE_URL}/recordings/{recording_id}",
+            timeout=timeout,
+        )
+        return _map_recording_status(response.json())
+
+    async def wait_for_recording(
+        self,
+        recording_id: str,
+        *,
+        timeout: float = 60.0,
+        poll_interval: float = 2.0,
+    ) -> RecordingStatus:
+        """Poll ``get_recording`` until COMPLETED or ERROR."""
+        import asyncio
+
+        start = time.monotonic()
+        while time.monotonic() - start < timeout:
+            status = await self.get_recording(recording_id)
+            if status.status in ("COMPLETED", "ERROR"):
+                return status
+            await asyncio.sleep(poll_interval)
+
+        from morphsdk._errors import APITimeoutError
+
+        raise APITimeoutError(
+            f"Recording {recording_id} did not complete within {timeout}s"
+        )
+
+    async def get_webp(
+        self,
+        recording_id: str,
+        *,
+        width: int | None = None,
+        fps: int | None = None,
+        quality: int | None = None,
+        max_duration: float | None = None,
+        max_size_mb: float | None = None,
+        timeout: float | None = None,
+    ) -> WebpResponse:
+        """Get an animated WebP preview of a recording."""
+        params = _build_webp_params(
+            width=width,
+            fps=fps,
+            quality=quality,
+            max_duration=max_duration,
+            max_size_mb=max_size_mb,
+        )
+
+        response = await self._client._request(
+            "GET",
+            f"{BROWSER_BASE_URL}/recordings/{recording_id}/webp",
+            params=params or None,
+            timeout=timeout,
+        )
+
+        return _parse_webp(response.json())
+
+    async def get_errors(
+        self,
+        recording_id: str,
+        *,
+        timeout: float | None = None,
+    ) -> ErrorsResponse:
+        """Get errors from a recording with screenshots."""
+        response = await self._client._request(
+            "GET",
+            f"{BROWSER_BASE_URL}/recordings/{recording_id}/errors",
+            timeout=timeout,
+        )
+
+        return ErrorsResponse.model_validate(response.json())
+
+    async def check_health(self, *, timeout: float | None = None) -> dict[str, Any]:
+        """Check if the browser worker service is healthy."""
+        try:
+            response = await self._client._request(
+                "GET",
+                f"{BROWSER_BASE_URL}/health",
+                timeout=timeout or 5.0,
+            )
+            return _health_payload(response.json())
+        except Exception as exc:
+            return _health_error(exc)