bobby-browser 0.17.0__tar.gz

bobby_browser-0.17.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: bobby-browser
+Version: 0.17.0
+Summary: Typed client for the authenticated Bobby Browser runtime interface
+Author: Sasan Sotoodehfar
+License: MIT
+Project-URL: Homepage, https://cavi-ai.xyz/docs/bobby-browser
+Project-URL: Repository, https://github.com/cavi-ai/bobby-browser
+Project-URL: Issues, https://github.com/cavi-ai/bobby-browser/issues
+Keywords: browser-automation,cdp,mcp,playwright,puppeteer,bobby-browser
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# bobby-browser (Python SDK)
+
+Typed HTTP client for the authenticated Bobby Browser `/v1` runtime
+interface. Stdlib only (`urllib`, `json`, `dataclasses`, `typing`) -- no
+third-party HTTP client dependency. Python >= 3.10.
+
+Mirrors `@cavi-ai/bobby-browser` (TypeScript,
+`packages/typescript-sdk`) and `bobby-browser-client` (Rust,
+`crates/bobby-browser-client`): same auth header contract, idempotency-key
+passthrough, and `CommandOutcome` status discriminator.
+
+## Install
+
+```bash
+pip install bobby-browser
+```
+
+From a bobby-browser checkout: `pip install -e packages/python-sdk`.
+
+`bobby install --skill-hermes` copies `skill/hermes/SKILL.md` into
+`$HERMES_HOME/skills/bobby-browser/` (else `~/.hermes/skills/`).
+
+## Use
+
+```python
+import os
+from bobby_browser import BrowserRuntimeClient
+
+client = BrowserRuntimeClient("http://127.0.0.1:7777", os.environ["AUTOMATION_RUNTIME_TOKEN"])
+```
+
+Full method catalog, headers, and error shape:
+[docs/bobby-browser/source/pages/surfaces/python-sdk.md](../../docs/bobby-browser/source/pages/surfaces/python-sdk.md).
+
+## Test
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+`tests/test_live_runtime.py` additionally starts the real `bobby` runtime
+from this worktree's release build and skips cleanly when
+`BOBBY_CHROME_EXECUTABLE` is unset.

bobby_browser-0.17.0/README.md

@@ -0,0 +1,43 @@
+# bobby-browser (Python SDK)
+
+Typed HTTP client for the authenticated Bobby Browser `/v1` runtime
+interface. Stdlib only (`urllib`, `json`, `dataclasses`, `typing`) -- no
+third-party HTTP client dependency. Python >= 3.10.
+
+Mirrors `@cavi-ai/bobby-browser` (TypeScript,
+`packages/typescript-sdk`) and `bobby-browser-client` (Rust,
+`crates/bobby-browser-client`): same auth header contract, idempotency-key
+passthrough, and `CommandOutcome` status discriminator.
+
+## Install
+
+```bash
+pip install bobby-browser
+```
+
+From a bobby-browser checkout: `pip install -e packages/python-sdk`.
+
+`bobby install --skill-hermes` copies `skill/hermes/SKILL.md` into
+`$HERMES_HOME/skills/bobby-browser/` (else `~/.hermes/skills/`).
+
+## Use
+
+```python
+import os
+from bobby_browser import BrowserRuntimeClient
+
+client = BrowserRuntimeClient("http://127.0.0.1:7777", os.environ["AUTOMATION_RUNTIME_TOKEN"])
+```
+
+Full method catalog, headers, and error shape:
+[docs/bobby-browser/source/pages/surfaces/python-sdk.md](../../docs/bobby-browser/source/pages/surfaces/python-sdk.md).
+
+## Test
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+`tests/test_live_runtime.py` additionally starts the real `bobby` runtime
+from this worktree's release build and skips cleanly when
+`BOBBY_CHROME_EXECUTABLE` is unset.

bobby_browser-0.17.0/bobby_browser/__init__.py

@@ -0,0 +1,20 @@
+"""``bobby-browser`` -- typed HTTP client for a Bobby Browser runtime
+(``bobby serve``) speaking the authenticated ``/v1`` interface.
+
+Pair with ``@cavi-ai/bobby-browser`` (TypeScript) or ``bobby-browser-client``
+(Rust) for the same surface from other callers. Auth headers on every
+request: ``Authorization: Bearer ...``, ``x-interface-version``,
+``x-correlation-id``, and ``x-deadline``.
+"""
+
+from .client import INTERFACE_VERSION, BrowserRuntimeClient, RequestOptions
+from .errors import RuntimeClientError
+
+__all__ = [
+    "BrowserRuntimeClient",
+    "RequestOptions",
+    "RuntimeClientError",
+    "INTERFACE_VERSION",
+]
+
+__version__ = "0.17.0"

bobby_browser-0.17.0/bobby_browser/client.py

@@ -0,0 +1,470 @@
+"""HTTP client for the Bobby Browser ``/v1`` runtime interface.
+
+Mirrors ``packages/typescript-sdk/src/client.ts``: every request sends
+``Authorization``, ``x-interface-version``, ``x-correlation-id``, and
+``x-deadline``; mutating calls accept an idempotency key; failures raise
+:class:`~bobby_browser.errors.RuntimeClientError`. Stdlib only
+(``urllib``, ``json``, ``dataclasses``, ``typing``) -- no third-party HTTP
+client.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, List, Mapping, Optional, Sequence
+
+from .errors import RuntimeClientError
+
+# Interface version negotiated via the `x-interface-version` request header.
+# Keep aligned with packages/typescript-sdk/src/contracts.ts INTERFACE_VERSION.
+INTERFACE_VERSION = "2026-08-19"
+
+_DEFAULT_TIMEOUT_MS = 30_000
+_JSON_CONTENT_TYPE = re.compile(r"^application/json(?:\s*;|$)", re.IGNORECASE)
+
+# CommandOutcome.status -> expected HTTP status, mirroring client.ts's
+# commandStatus().
+_COMMAND_STATUS_HTTP: Dict[str, int] = {
+    "completed": 200,
+    "restarted": 200,
+    "retryableFailure": 503,
+    "needsReconciliation": 409,
+    "policyDenied": 403,
+    "resourceExhausted": 429,
+}
+
+# RecoveryDecision.status -> expected HTTP status, mirroring client.ts's
+# `recover()` mapping.
+_RECOVERY_NEEDS_RECONCILIATION_STATUS = "needsReconciliation"
+
+
+@dataclass
+class RequestOptions:
+    """Per-call overrides. All fields are optional.
+
+    Attributes:
+        timeout_ms: Relative timeout in milliseconds (default 30_000).
+        deadline: Absolute RFC3339 deadline string; combined with
+            ``timeout_ms`` as the earlier of the two, same as the TS client.
+        correlation_id: Value for ``x-correlation-id`` (a UUID4 is
+            generated when omitted).
+        idempotency_key: Value for ``idempotency-key`` on mutating POSTs.
+    """
+
+    timeout_ms: Optional[int] = None
+    deadline: Optional[str] = None
+    correlation_id: Optional[str] = None
+    idempotency_key: Optional[str] = None
+
+
+def _uuid4() -> str:
+    return str(uuid.uuid4())
+
+
+def _deadline_header(options: Optional[RequestOptions], default_timeout_ms: int) -> str:
+    if options is not None and options.deadline:
+        return options.deadline
+    timeout_ms = default_timeout_ms
+    if options is not None and options.timeout_ms is not None:
+        timeout_ms = options.timeout_ms
+    deadline = datetime.now(timezone.utc) + timedelta(milliseconds=timeout_ms)
+    return deadline.strftime("%Y-%m-%dT%H:%M:%S.") + f"{deadline.microsecond // 1000:03d}Z"
+
+
+def _header_get(headers: Mapping[str, str], name: str) -> Optional[str]:
+    lowered = name.lower()
+    for key, value in headers.items():
+        if key.lower() == lowered:
+            return value
+    return None
+
+
+def _content_type(headers: Mapping[str, str]) -> str:
+    raw = _header_get(headers, "content-type") or ""
+    return raw.split(";", 1)[0].strip().lower()
+
+
+def _media_type_essence(value: str) -> Optional[str]:
+    essence = value.split(";", 1)[0].strip().lower()
+    if essence and re.match(r"^[!#$%&'*+.^_`|~0-9a-z-]+/[!#$%&'*+.^_`|~0-9a-z-]+$", essence):
+        return essence
+    return None
+
+
+class BrowserRuntimeClient:
+    """Authenticated HTTP client for a Bobby Browser runtime (``bobby serve``).
+
+    Args:
+        base_url: Runtime origin. A trailing slash and a trailing ``/v1``
+            are stripped, so either ``http://127.0.0.1:7777`` or
+            ``http://127.0.0.1:7777/v1`` works.
+        bearer_token: Bearer credential for ``Authorization``. Never sent
+            anywhere but that header, never logged, never put in a URL.
+        timeout_ms: Default relative timeout for calls that do not pass
+            ``options`` (default 30_000).
+        opener: Override ``urllib.request`` opener (tests only).
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        bearer_token: str,
+        *,
+        timeout_ms: int = _DEFAULT_TIMEOUT_MS,
+        opener: Optional[urllib.request.OpenerDirector] = None,
+    ) -> None:
+        if not base_url or not bearer_token:
+            raise ValueError("base_url and bearer_token are required")
+        stripped = base_url.rstrip("/")
+        if stripped.endswith("/v1"):
+            stripped = stripped[: -len("/v1")]
+        self._base_url = stripped
+        self._bearer_token = bearer_token
+        self._timeout_ms = timeout_ms
+        self._opener = opener or urllib.request.build_opener()
+
+    def __repr__(self) -> str:  # never print the bearer token
+        return "BrowserRuntimeClient(bearer_token=[redacted])"
+
+    # ---- sessions ---------------------------------------------------
+
+    def runtime_info(self, options: Optional[RequestOptions] = None) -> Dict[str, Any]:
+        """``GET /v1/runtime`` -- version, capabilities, and load counters."""
+        return self._json("GET", "/v1/runtime", None, options, expected_status=200)
+
+    def create_session(
+        self, input: Mapping[str, Any], options: Optional[RequestOptions] = None
+    ) -> Dict[str, Any]:
+        """``POST /v1/sessions`` -- create a browser session."""
+        return self._json("POST", "/v1/sessions", input, options, expected_status=200)
+
+    def read_session(
+        self, session_id: Optional[str] = None, options: Optional[RequestOptions] = None
+    ) -> Any:
+        """Read session state.
+
+        There is no ``GET /v1/sessions/{id}`` on the wire, only
+        ``GET /v1/sessions`` (full array, no pagination). With
+        ``session_id`` omitted this returns that full list; with it set,
+        this filters client-side and returns the one matching
+        :class:`SessionState`, raising :class:`RuntimeClientError` with
+        ``kind="protocol"`` if no session with that id is active.
+        """
+        sessions = self._json("GET", "/v1/sessions", None, options, expected_status=200)
+        if not isinstance(sessions, list):
+            raise self._protocol("sessions response has an unexpected shape")
+        if session_id is None:
+            return sessions
+        for session in sessions:
+            if isinstance(session, dict) and session.get("id") == session_id:
+                return session
+        raise self._protocol(f"no active session with id {session_id!r}", 200)
+
+    def delete_session(self, session_id: str, options: Optional[RequestOptions] = None) -> None:
+        """``DELETE /v1/sessions/{id}`` -- tear down a session (204 on success)."""
+        self._empty("DELETE", f"/v1/sessions/{urllib.parse.quote(session_id)}", options)
+
+    # ---- pages --------------------------------------------------------
+
+    def open_page(
+        self, input: Mapping[str, Any], options: Optional[RequestOptions] = None
+    ) -> Dict[str, Any]:
+        """``POST /v1/pages`` -- open a page in a session."""
+        return self._json("POST", "/v1/pages", input, options, expected_status=200)
+
+    def read_page(
+        self,
+        session_id: str,
+        page_id: str,
+        *,
+        max_controls: Optional[int] = None,
+        options: Optional[RequestOptions] = None,
+    ) -> Dict[str, Any]:
+        """``GET /v1/sessions/{session}/pages/{page}/forms`` -- read-only
+        ``FormSnapshot`` (the PageRead HTTP surface; same contract as MCP
+        ``form_snapshot``). Page-derived controls carry ``pageDerived: true``.
+        ``max_controls`` is optional, 1 through 512.
+        """
+        if max_controls is not None and not (1 <= max_controls <= 512):
+            raise self._protocol("max_controls must be between 1 and 512")
+        query = f"?maxControls={max_controls}" if max_controls is not None else ""
+        path = (
+            f"/v1/sessions/{urllib.parse.quote(session_id)}"
+            f"/pages/{urllib.parse.quote(page_id)}/forms{query}"
+        )
+        return self._json("GET", path, None, options, expected_status=200)
+
+    # ---- commands -------------------------------------------------------
+
+    def submit_command(
+        self, envelope: Mapping[str, Any], options: Optional[RequestOptions] = None
+    ) -> Dict[str, Any]:
+        """``POST /v1/commands`` -- submit a raw ``CommandEnvelope``.
+
+        Returns the ``CommandOutcome`` body unmodified (its ``status``
+        discriminator field is preserved exactly as the server sent it --
+        ``completed``, ``retryableFailure``, ``needsReconciliation``,
+        ``policyDenied``, ``resourceExhausted``, ``restarted``, or
+        ``failed``) after checking the HTTP status matches the documented
+        mapping for that status.
+        Page-derived inspection, accessibility, form, and extraction evidence
+        retains its ``pageDerived: true`` marker in the returned dictionary.
+        """
+        status, payload = self._request("POST", "/v1/commands", envelope, options)
+        if not isinstance(payload, dict) or "status" not in payload:
+            raise self._response_error(status, payload)
+        outcome_status = payload["status"]
+        expected = _command_outcome_http_status(payload)
+        if expected is None:
+            raise self._protocol(f"unknown command outcome status: {outcome_status!r}", status)
+        if expected != status:
+            raise self._protocol(
+                "command outcome status does not match HTTP mapping", status
+            )
+        return payload
+
+    # ---- checkpoints / recovery ------------------------------------------
+
+    def create_checkpoint(
+        self, input: Mapping[str, Any], options: Optional[RequestOptions] = None
+    ) -> Dict[str, Any]:
+        """``POST /v1/checkpoints`` -- persist a workflow checkpoint."""
+        return self._json("POST", "/v1/checkpoints", input, options, expected_status=200)
+
+    def recovery_status(
+        self, workflow_id: str, options: Optional[RequestOptions] = None
+    ) -> Dict[str, Any]:
+        """``GET /v1/recovery/{workflowId}`` -- current recovery status."""
+        path = f"/v1/recovery/{urllib.parse.quote(workflow_id)}"
+        return self._json("GET", path, None, options, expected_status=200)
+
+    def recover_workflow(
+        self, workflow_id: str, options: Optional[RequestOptions] = None
+    ) -> Dict[str, Any]:
+        """``POST /v1/recovery/{workflowId}`` -- resume, reconcile, or
+        restart a workflow. ``needsReconciliation`` maps to HTTP 409;
+        every other decision maps to 200.
+        """
+        path = f"/v1/recovery/{urllib.parse.quote(workflow_id)}"
+        status, payload = self._request("POST", path, None, options)
+        if not isinstance(payload, dict) or "status" not in payload:
+            raise self._response_error(status, payload)
+        expected = 409 if payload["status"] == _RECOVERY_NEEDS_RECONCILIATION_STATUS else 200
+        if expected != status:
+            raise self._protocol(
+                "recovery decision status does not match HTTP mapping", status
+            )
+        return payload
+
+    # ---- context --------------------------------------------------------
+
+    def context_ask(
+        self,
+        session_id: str,
+        page_id: str,
+        description: str,
+        options: Optional[RequestOptions] = None,
+    ) -> Dict[str, Any]:
+        """``GET /v1/context/ask`` -- remembered target for a description.
+
+        The result carries ``pageDerived: true`` on either a hit or miss.
+        """
+        encoded = len(description.encode("utf-8"))
+        if not (1 <= encoded <= 256):
+            raise self._protocol("description must contain between 1 and 256 bytes")
+        query = urllib.parse.urlencode(
+            {"sessionId": session_id, "pageId": page_id, "description": description}
+        )
+        return self._json("GET", f"/v1/context/ask?{query}", None, options, expected_status=200)
+
+    def context_site(
+        self, site_key: str, options: Optional[RequestOptions] = None
+    ) -> Dict[str, Any]:
+        """``GET /v1/context/site/{key}`` -- durable per-site context view."""
+        if not site_key:
+            raise self._protocol("site key must not be empty")
+        path = f"/v1/context/site/{urllib.parse.quote(site_key)}"
+        return self._json("GET", path, None, options, expected_status=200)
+
+    # ---- artifacts --------------------------------------------------------
+
+    def read_artifact(
+        self, reference: Mapping[str, Any], options: Optional[RequestOptions] = None
+    ) -> bytes:
+        """``GET /v1/artifacts/{artifactId}`` -- verified artifact bytes.
+
+        ``reference`` is an ``ArtifactReference``: ``artifactId``,
+        ``sha256``, ``bytes``, and ``mediaType``. Checks ``Content-Type``
+        and ``Content-Length`` against the reference, then verifies
+        SHA-256 before returning anything -- no bytes are handed back on a
+        mismatch.
+        """
+        artifact_id = reference.get("artifactId")
+        if not artifact_id or not isinstance(artifact_id, str):
+            raise self._protocol("artifact reference is missing artifactId")
+        path = f"/v1/artifacts/{urllib.parse.quote(artifact_id)}"
+        status, content_type, headers, raw = self._request_raw("GET", path, None, options)
+        if status != 200:
+            raise self._response_error(status, self._decode_json_or_none(raw, content_type))
+        expected_media_type = _media_type_essence(str(reference.get("mediaType", "")))
+        if expected_media_type is None or content_type != expected_media_type:
+            raise self._protocol("artifact media type does not match its reference", status)
+        expected_bytes = reference.get("bytes")
+        content_length = _header_get(headers, "content-length")
+        if (
+            content_length is None
+            or not content_length.isdigit()
+            or int(content_length) != expected_bytes
+            or len(raw) != expected_bytes
+        ):
+            raise self._protocol("artifact content length does not match its reference", status)
+        digest = hashlib.sha256(raw).hexdigest()
+        expected_sha256 = str(reference.get("sha256", "")).lower()
+        if digest != expected_sha256:
+            raise self._protocol("artifact digest does not match its reference", status)
+        return raw
+
+    # ---- jobs --------------------------------------------------------
+
+    def submit_job(
+        self, input: Mapping[str, Any], options: Optional[RequestOptions] = None
+    ) -> Dict[str, Any]:
+        """``POST /v1/jobs`` -- submit a bounded runtime job."""
+        return self._json("POST", "/v1/jobs", input, options, expected_status=201)
+
+    def job_status(self, job_id: str, options: Optional[RequestOptions] = None) -> Dict[str, Any]:
+        """``GET /v1/jobs/{jobId}`` -- read the authenticated principal's job."""
+        path = f"/v1/jobs/{urllib.parse.quote(job_id)}"
+        return self._json("GET", path, None, options, expected_status=200)
+
+    def cancel_job(self, job_id: str, options: Optional[RequestOptions] = None) -> None:
+        """``DELETE /v1/jobs/{jobId}`` -- cancel the authenticated principal's job."""
+        self._empty("DELETE", f"/v1/jobs/{urllib.parse.quote(job_id)}", options)
+
+    # ---- transport --------------------------------------------------------
+
+    def _headers(self, options: Optional[RequestOptions], has_body: bool) -> Dict[str, str]:
+        correlation_id = (options.correlation_id if options else None) or _uuid4()
+        headers = {
+            "Authorization": f"Bearer {self._bearer_token}",
+            "x-interface-version": INTERFACE_VERSION,
+            "x-correlation-id": correlation_id,
+            "x-deadline": _deadline_header(options, self._timeout_ms),
+        }
+        if options is not None and options.idempotency_key:
+            headers["idempotency-key"] = options.idempotency_key
+        if has_body:
+            headers["content-type"] = "application/json"
+        return headers
+
+    def _request_raw(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Mapping[str, Any]],
+        options: Optional[RequestOptions],
+    ) -> tuple:
+        """Returns (status, content_type, headers, raw_bytes)."""
+        url = f"{self._base_url}{path}"
+        headers = self._headers(options, body is not None)
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        request = urllib.request.Request(url, data=data, headers=headers, method=method)
+        timeout_ms = self._timeout_ms
+        if options is not None and options.timeout_ms is not None:
+            timeout_ms = options.timeout_ms
+        try:
+            response = self._opener.open(request, timeout=timeout_ms / 1000)
+            try:
+                status = response.status
+                response_headers = dict(response.headers.items())
+                raw = response.read()
+            finally:
+                response.close()
+        except urllib.error.HTTPError as error:
+            status = error.code
+            response_headers = dict(error.headers.items()) if error.headers else {}
+            raw = error.read()
+            error.close()
+        except TimeoutError as error:
+            raise RuntimeClientError("deadline", message="Request deadline exceeded") from error
+        except urllib.error.URLError as error:
+            raise RuntimeClientError(
+                "transport", message=f"Runtime transport request failed: {error.reason}"
+            ) from error
+        content_type = _content_type(response_headers)
+        return status, content_type, response_headers, raw
+
+    def _decode_json_or_none(self, raw: bytes, content_type: str) -> Any:
+        if not _JSON_CONTENT_TYPE.match(content_type):
+            return None
+        try:
+            return json.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            return None
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Mapping[str, Any]],
+        options: Optional[RequestOptions],
+    ) -> tuple:
+        """Returns (status, parsed_json_payload)."""
+        status, content_type, _headers, raw = self._request_raw(method, path, body, options)
+        if not _JSON_CONTENT_TYPE.match(content_type):
+            raise self._protocol("response content type must be application/json", status)
+        try:
+            payload = json.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise self._protocol("response body is not valid JSON", status) from error
+        return status, payload
+
+    def _json(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Mapping[str, Any]],
+        options: Optional[RequestOptions],
+        *,
+        expected_status: int,
+    ) -> Any:
+        status, payload = self._request(method, path, body, options)
+        if status != expected_status:
+            raise self._response_error(status, payload)
+        return payload
+
+    def _empty(self, method: str, path: str, options: Optional[RequestOptions]) -> None:
+        status, content_type, _headers, raw = self._request_raw(method, path, None, options)
+        if status == 204:
+            return
+        payload = self._decode_json_or_none(raw, content_type)
+        raise self._response_error(status, payload)
+
+    def _response_error(self, status: int, payload: Any) -> RuntimeClientError:
+        if isinstance(payload, dict) and set(payload.keys()) == {"error"} and isinstance(
+            payload["error"], dict
+        ):
+            return RuntimeClientError.from_interface_error("http", status, payload["error"])
+        return self._protocol("response has an unexpected status or shape", status)
+
+    def _protocol(self, message: str, status: Optional[int] = None) -> RuntimeClientError:
+        return RuntimeClientError("protocol", status=status, message=message)
+
+
+def _command_outcome_http_status(outcome: Mapping[str, Any]) -> Optional[int]:
+    """Mirrors client.ts's commandStatus(): CommandOutcome.status -> HTTP status."""
+    status = outcome.get("status")
+    if status in _COMMAND_STATUS_HTTP:
+        return _COMMAND_STATUS_HTTP[status]
+    if status == "failed":
+        error = outcome.get("error") or {}
+        return 422 if error.get("code") == "invalidRequest" else 500
+    return None

bobby_browser-0.17.0/bobby_browser/errors.py

@@ -0,0 +1,101 @@
+"""Client-side error type for the Bobby Browser Python SDK.
+
+Mirrors ``RuntimeClientError`` from the TypeScript SDK
+(``packages/typescript-sdk/src/errors.ts``): a single exception class
+classified by ``kind``, carrying the fields a caller needs to decide whether
+to retry, without ever retaining the bearer token.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+# Classification of RuntimeClientError, matching the TypeScript
+# RuntimeClientErrorKind union exactly.
+RUNTIME_CLIENT_ERROR_KINDS = ("transport", "protocol", "http", "aborted", "deadline")
+
+
+class RuntimeClientError(Exception):
+    """Raised for every failure the client cannot recover from itself.
+
+    Attributes:
+        kind: One of ``"transport"``, ``"protocol"``, ``"http"``,
+            ``"aborted"``, ``"deadline"``.
+        status: HTTP status code, when the failure followed a response.
+        code: Wire ``InterfaceErrorCode``, when the server returned one.
+        correlation_id: The request's ``x-correlation-id``, when known.
+        command_id: The command id an interface error referenced, if any.
+        retryable: Whether the server marked the failure retryable.
+        retry_after_ms: Minimum backoff before retrying, when the server
+            supplied one (notably on HTTP 429).
+        reconciliation_required: Whether the caller must reconcile a
+            workflow's checkpoint before retrying.
+        required_capability: The capability the caller was missing, if any.
+        event_gap: The ``EventGap`` payload, for a 409 on ``events()``.
+    """
+
+    def __init__(
+        self,
+        kind: str,
+        *,
+        status: Optional[int] = None,
+        code: Optional[str] = None,
+        message: Optional[str] = None,
+        correlation_id: Optional[str] = None,
+        command_id: Optional[Any] = None,
+        retryable: Optional[bool] = None,
+        retry_after_ms: Optional[int] = None,
+        reconciliation_required: Optional[bool] = None,
+        required_capability: Optional[Any] = None,
+        event_gap: Optional[Mapping[str, Any]] = None,
+    ) -> None:
+        if kind not in RUNTIME_CLIENT_ERROR_KINDS:
+            raise ValueError(f"unknown RuntimeClientError kind: {kind!r}")
+        resolved_message = message or f"Runtime client {kind} failure"
+        super().__init__(resolved_message)
+        self.kind = kind
+        self.status = status
+        self.code = code
+        self.correlation_id = correlation_id
+        self.command_id = command_id
+        self.retryable = retryable
+        self.retry_after_ms = retry_after_ms
+        self.reconciliation_required = reconciliation_required
+        self.required_capability = required_capability
+        self.event_gap = dict(event_gap) if event_gap is not None else None
+
+    @classmethod
+    def from_interface_error(
+        cls, kind: str, status: int, error: Mapping[str, Any]
+    ) -> "RuntimeClientError":
+        """Build from a wire ``InterfaceError`` (``{"error": {...}}`` body)."""
+        return cls(
+            kind,
+            status=status,
+            code=error.get("code"),
+            message=f"Runtime request failed: {status} {error.get('code')}",
+            correlation_id=error.get("correlationId"),
+            command_id=error.get("commandId"),
+            retryable=error.get("retryable"),
+            retry_after_ms=error.get("retryAfterMs"),
+            reconciliation_required=error.get("reconciliationRequired"),
+            required_capability=error.get("requiredCapability"),
+        )
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return f"RuntimeClientError(kind={self.kind!r}, status={self.status!r}, code={self.code!r})"
+
+    def to_dict(self) -> dict:
+        """JSON-safe projection for logging."""
+        return {
+            "kind": self.kind,
+            "status": self.status,
+            "code": self.code,
+            "correlationId": self.correlation_id,
+            "commandId": self.command_id,
+            "retryable": self.retryable,
+            "retryAfterMs": self.retry_after_ms,
+            "reconciliationRequired": self.reconciliation_required,
+            "requiredCapability": self.required_capability,
+            "eventGap": self.event_gap,
+        }

bobby_browser-0.17.0/bobby_browser.egg-info/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: bobby-browser
+Version: 0.17.0
+Summary: Typed client for the authenticated Bobby Browser runtime interface
+Author: Sasan Sotoodehfar
+License: MIT
+Project-URL: Homepage, https://cavi-ai.xyz/docs/bobby-browser
+Project-URL: Repository, https://github.com/cavi-ai/bobby-browser
+Project-URL: Issues, https://github.com/cavi-ai/bobby-browser/issues
+Keywords: browser-automation,cdp,mcp,playwright,puppeteer,bobby-browser
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# bobby-browser (Python SDK)
+
+Typed HTTP client for the authenticated Bobby Browser `/v1` runtime
+interface. Stdlib only (`urllib`, `json`, `dataclasses`, `typing`) -- no
+third-party HTTP client dependency. Python >= 3.10.
+
+Mirrors `@cavi-ai/bobby-browser` (TypeScript,
+`packages/typescript-sdk`) and `bobby-browser-client` (Rust,
+`crates/bobby-browser-client`): same auth header contract, idempotency-key
+passthrough, and `CommandOutcome` status discriminator.
+
+## Install
+
+```bash
+pip install bobby-browser
+```
+
+From a bobby-browser checkout: `pip install -e packages/python-sdk`.
+
+`bobby install --skill-hermes` copies `skill/hermes/SKILL.md` into
+`$HERMES_HOME/skills/bobby-browser/` (else `~/.hermes/skills/`).
+
+## Use
+
+```python
+import os
+from bobby_browser import BrowserRuntimeClient
+
+client = BrowserRuntimeClient("http://127.0.0.1:7777", os.environ["AUTOMATION_RUNTIME_TOKEN"])
+```
+
+Full method catalog, headers, and error shape:
+[docs/bobby-browser/source/pages/surfaces/python-sdk.md](../../docs/bobby-browser/source/pages/surfaces/python-sdk.md).
+
+## Test
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+`tests/test_live_runtime.py` additionally starts the real `bobby` runtime
+from this worktree's release build and skips cleanly when
+`BOBBY_CHROME_EXECUTABLE` is unset.

bobby_browser-0.17.0/bobby_browser.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+bobby_browser/__init__.py
+bobby_browser/client.py
+bobby_browser/errors.py
+bobby_browser/py.typed
+bobby_browser.egg-info/PKG-INFO
+bobby_browser.egg-info/SOURCES.txt
+bobby_browser.egg-info/dependency_links.txt
+bobby_browser.egg-info/top_level.txt
+tests/test_client.py
+tests/test_live_runtime.py

bobby_browser-0.17.0/bobby_browser.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bobby_browser-0.17.0/bobby_browser.egg-info/top_level.txt

@@ -0,0 +1 @@
+bobby_browser

bobby_browser-0.17.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bobby-browser"
+version = "0.17.0"
+description = "Typed client for the authenticated Bobby Browser runtime interface"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Sasan Sotoodehfar" }]
+requires-python = ">=3.10"
+dependencies = []
+keywords = ["browser-automation", "cdp", "mcp", "playwright", "puppeteer", "bobby-browser"]
+
+[project.urls]
+Homepage = "https://cavi-ai.xyz/docs/bobby-browser"
+Repository = "https://github.com/cavi-ai/bobby-browser"
+Issues = "https://github.com/cavi-ai/bobby-browser/issues"
+
+[tool.setuptools.packages.find]
+include = ["bobby_browser*"]
+
+[tool.setuptools.package-data]
+bobby_browser = ["py.typed"]

bobby_browser-0.17.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bobby_browser-0.17.0/tests/test_client.py

@@ -0,0 +1,342 @@
+"""Unit tests for bobby_browser.client against a local fake HTTP server.
+
+No real bobby-browser runtime involved -- see test_live_runtime.py for the
+one test that starts the real thing. These cover: the auth header contract,
+idempotency-key passthrough, the 429 retryAfterMs surface, the 409
+needsReconciliation surface on submit_command, and that the CommandOutcome
+status discriminator survives the round trip unmodified.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sys
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from typing import Callable
+
+# `python3 -m unittest discover -s packages/python-sdk/tests` (the CI /
+# check-version-agreement.py-adjacent gate) runs straight from a checkout
+# with no `pip install` step first. `packages/python-sdk` (this file's
+# grandparent) is the source package root; put it on sys.path so
+# `bobby_browser` resolves to the checkout's own source.
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from bobby_browser import BrowserRuntimeClient, RequestOptions, RuntimeClientError  # noqa: E402
+
+
+class _Handler(BaseHTTPRequestHandler):
+    def log_message(self, format, *args):  # noqa: A002 - stdlib signature
+        pass  # keep test output quiet
+
+    def _dispatch(self) -> None:
+        self.server.route_handler(self)  # type: ignore[attr-defined]
+
+    def do_GET(self) -> None:  # noqa: N802 - stdlib naming
+        self._dispatch()
+
+    def do_POST(self) -> None:  # noqa: N802
+        self._dispatch()
+
+    def do_DELETE(self) -> None:  # noqa: N802
+        self._dispatch()
+
+    def read_body(self) -> bytes:
+        length = int(self.headers.get("Content-Length", "0") or "0")
+        return self.rfile.read(length) if length else b""
+
+    def reply_json(self, status: int, payload) -> None:
+        body = json.dumps(payload).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+
+class _FakeServer:
+    def __init__(self, handler: Callable[[_Handler], None]) -> None:
+        self.httpd = HTTPServer(("127.0.0.1", 0), _Handler)
+        self.httpd.route_handler = handler  # type: ignore[attr-defined]
+        self.thread = threading.Thread(target=self.httpd.serve_forever, daemon=True)
+        self.thread.start()
+
+    @property
+    def base_url(self) -> str:
+        return f"http://127.0.0.1:{self.httpd.server_port}"
+
+    def close(self) -> None:
+        self.httpd.shutdown()
+        self.httpd.server_close()
+        self.thread.join(timeout=5)
+
+
+class ClientUnitTests(unittest.TestCase):
+    def _serve(self, handler: Callable[[_Handler], None]) -> _FakeServer:
+        server = _FakeServer(handler)
+        self.addCleanup(server.close)
+        return server
+
+    # ---- auth header contract ------------------------------------------
+
+    def test_every_request_carries_the_documented_headers(self) -> None:
+        seen = {}
+
+        def handler(req: _Handler) -> None:
+            req.read_body()
+            seen["authorization"] = req.headers.get("Authorization")
+            seen["interface_version"] = req.headers.get("x-interface-version")
+            seen["correlation_id"] = req.headers.get("x-correlation-id")
+            seen["deadline"] = req.headers.get("x-deadline")
+            req.reply_json(200, {"version": "1.2.3", "capabilities": [], "active_sessions": 0, "queued_jobs": 0, "uptime_ms": 1})
+
+        server = self._serve(handler)
+        client = BrowserRuntimeClient(server.base_url, "top-secret-bearer")
+        info = client.runtime_info()
+
+        self.assertEqual(info["version"], "1.2.3")
+        self.assertEqual(seen["authorization"], "Bearer top-secret-bearer")
+        self.assertEqual(seen["interface_version"], "2026-08-19")
+        self.assertTrue(seen["correlation_id"])
+        self.assertTrue(seen["deadline"] and seen["deadline"].endswith("Z"))
+        # Never a credential in the URL.
+        self.assertNotIn("top-secret-bearer", server.base_url)
+
+    def test_bearer_token_never_appears_in_repr(self) -> None:
+        client = BrowserRuntimeClient("http://127.0.0.1:1", "super-secret")
+        self.assertNotIn("super-secret", repr(client))
+
+    # ---- idempotency-key passthrough -------------------------------------
+
+    def test_idempotency_key_passthrough_on_mutating_post(self) -> None:
+        seen = {}
+
+        def handler(req: _Handler) -> None:
+            body = json.loads(req.read_body() or b"{}")
+            seen["idempotency_key"] = req.headers.get("idempotency-key")
+            seen["profile"] = body.get("profile")
+            req.reply_json(
+                200,
+                {
+                    "id": "session-1",
+                    "profile": body.get("profile"),
+                    "proxy": None,
+                    "page_ids": [],
+                    "created_at": "2026-09-23T00:00:00.000Z",
+                    "last_used_at": "2026-09-23T00:00:00.000Z",
+                    "execution_policy": {
+                        "javascriptEvaluation": False,
+                        "visionAssist": False,
+                        "fingerprint": False,
+                        "humanize": False,
+                    },
+                },
+            )
+
+        server = self._serve(handler)
+        client = BrowserRuntimeClient(server.base_url, "token")
+        session = client.create_session(
+            {"profile": "default", "proxy": None},
+            RequestOptions(idempotency_key="create-session-1"),
+        )
+
+        self.assertEqual(session["id"], "session-1")
+        self.assertEqual(seen["idempotency_key"], "create-session-1")
+        self.assertEqual(seen["profile"], "default")
+
+    def test_idempotency_key_absent_when_not_supplied(self) -> None:
+        seen = {}
+
+        def handler(req: _Handler) -> None:
+            req.read_body()
+            seen["idempotency_key"] = req.headers.get("idempotency-key")
+            req.send_response(204)
+            req.end_headers()
+
+        server = self._serve(handler)
+        client = BrowserRuntimeClient(server.base_url, "token")
+        client.delete_session("11111111-1111-4111-8111-111111111111")
+
+        self.assertIsNone(seen["idempotency_key"])
+
+    # ---- 429 retryAfterMs ------------------------------------------------
+
+    def test_429_surfaces_retry_after_ms_from_interface_error(self) -> None:
+        def handler(req: _Handler) -> None:
+            req.read_body()
+            req.reply_json(
+                429,
+                {
+                    "error": {
+                        "code": "resourceExhausted",
+                        "layer": "interface",
+                        "message": "too many requests",
+                        "correlationId": "corr-1",
+                        "commandId": None,
+                        "retryable": True,
+                        "retryAfterMs": 1500,
+                        "reconciliationRequired": False,
+                        "requiredCapability": None,
+                    }
+                },
+            )
+
+        server = self._serve(handler)
+        client = BrowserRuntimeClient(server.base_url, "token")
+
+        with self.assertRaises(RuntimeClientError) as caught:
+            client.runtime_info()
+
+        error = caught.exception
+        self.assertEqual(error.kind, "http")
+        self.assertEqual(error.status, 429)
+        self.assertEqual(error.code, "resourceExhausted")
+        self.assertEqual(error.retry_after_ms, 1500)
+        self.assertTrue(error.retryable)
+
+    # ---- 409 needsReconciliation on submit_command ------------------------
+
+    def test_submit_command_409_needs_reconciliation_is_returned_not_raised(self) -> None:
+        def handler(req: _Handler) -> None:
+            req.read_body()
+            req.reply_json(
+                409,
+                {
+                    "status": "needsReconciliation",
+                    "commandId": "cmd-1",
+                    "error": {
+                        "code": "verificationFailed",
+                        "message": "page state diverged",
+                        "layer": "page",
+                        "retryable": False,
+                    },
+                    "evidence": [],
+                },
+            )
+
+        server = self._serve(handler)
+        client = BrowserRuntimeClient(server.base_url, "token")
+        outcome = client.submit_command({"schemaVersion": 1, "commandId": "cmd-1"})
+
+        self.assertEqual(outcome["status"], "needsReconciliation")
+        self.assertEqual(outcome["commandId"], "cmd-1")
+
+    def test_submit_command_mismatched_http_mapping_raises_protocol_error(self) -> None:
+        def handler(req: _Handler) -> None:
+            req.read_body()
+            # needsReconciliation must map to 409; sending 200 is a protocol violation.
+            req.reply_json(200, {"status": "needsReconciliation", "commandId": "cmd-2", "error": {}, "evidence": []})
+
+        server = self._serve(handler)
+        client = BrowserRuntimeClient(server.base_url, "token")
+
+        with self.assertRaises(RuntimeClientError) as caught:
+            client.submit_command({"schemaVersion": 1, "commandId": "cmd-2"})
+
+        self.assertEqual(caught.exception.kind, "protocol")
+
+    # ---- status discriminator preserved -----------------------------------
+
+    def test_submit_command_status_discriminator_preserved(self) -> None:
+        for status, http_status, extra in (
+            ("completed", 200, {"evidence": []}),
+            ("policyDenied", 403, {"error": {"code": "policyDenied", "message": "x", "layer": "interface", "retryable": False}}),
+            (
+                "resourceExhausted",
+                429,
+                {
+                    "error": {"code": "resourceExhausted", "message": "x", "layer": "interface", "retryable": True},
+                    "retryAfterMs": 250,
+                },
+            ),
+        ):
+            with self.subTest(status=status):
+                payload = {"status": status, "commandId": "cmd-x", **extra}
+
+                def handler(req: _Handler, payload=payload, http_status=http_status) -> None:
+                    req.read_body()
+                    req.reply_json(http_status, payload)
+
+                server = self._serve(handler)
+                client = BrowserRuntimeClient(server.base_url, "token")
+                outcome = client.submit_command({"schemaVersion": 1, "commandId": "cmd-x"})
+                self.assertEqual(outcome["status"], status)
+
+    # ---- read_session (no single-id GET on the wire) -----------------------
+
+    def test_read_session_filters_the_list_endpoint_client_side(self) -> None:
+        def handler(req: _Handler) -> None:
+            req.read_body()
+            req.reply_json(
+                200,
+                [
+                    {"id": "s1", "profile": "default"},
+                    {"id": "s2", "profile": "default"},
+                ],
+            )
+
+        server = self._serve(handler)
+        client = BrowserRuntimeClient(server.base_url, "token")
+
+        self.assertEqual(client.read_session("s2")["id"], "s2")
+        self.assertEqual(len(client.read_session()), 2)
+        with self.assertRaises(RuntimeClientError):
+            client.read_session("does-not-exist")
+
+    # ---- artifact verification ---------------------------------------------
+
+    def test_read_artifact_verifies_sha256_before_returning_bytes(self) -> None:
+        data = b"artifact-bytes-for-testing"
+        digest = hashlib.sha256(data).hexdigest()
+
+        def handler(req: _Handler) -> None:
+            req.read_body()
+            req.send_response(200)
+            req.send_header("Content-Type", "application/octet-stream")
+            req.send_header("Content-Length", str(len(data)))
+            req.end_headers()
+            req.wfile.write(data)
+
+        server = self._serve(handler)
+        client = BrowserRuntimeClient(server.base_url, "token")
+        reference = {
+            "referenceId": "ref-1",
+            "artifactId": "artifact-1",
+            "sha256": digest,
+            "bytes": len(data),
+            "mediaType": "application/octet-stream",
+        }
+
+        self.assertEqual(client.read_artifact(reference), data)
+
+    def test_read_artifact_rejects_a_digest_mismatch(self) -> None:
+        data = b"tampered-or-wrong-bytes"
+
+        def handler(req: _Handler) -> None:
+            req.read_body()
+            req.send_response(200)
+            req.send_header("Content-Type", "application/octet-stream")
+            req.send_header("Content-Length", str(len(data)))
+            req.end_headers()
+            req.wfile.write(data)
+
+        server = self._serve(handler)
+        client = BrowserRuntimeClient(server.base_url, "token")
+        reference = {
+            "referenceId": "ref-2",
+            "artifactId": "artifact-2",
+            "sha256": "0" * 64,
+            "bytes": len(data),
+            "mediaType": "application/octet-stream",
+        }
+
+        with self.assertRaises(RuntimeClientError) as caught:
+            client.read_artifact(reference)
+        self.assertEqual(caught.exception.kind, "protocol")
+
+
+if __name__ == "__main__":
+    unittest.main()

bobby_browser-0.17.0/tests/test_live_runtime.py

@@ -0,0 +1,135 @@
+"""One live test: start the real ``bobby`` runtime from this worktree's
+release build, mint a bootstrap credential with ``bobby init``, and drive
+``runtime_info`` / ``create_session`` through the Python SDK over real HTTP.
+
+Skipped cleanly (not failed) when ``BOBBY_CHROME_EXECUTABLE`` is unset, same
+convention the Rust workspace tests use (crates/worker-pool/tests/chromium_worker.rs).
+Never prints the bootstrap bearer: it is read from ``bobby init``'s stdout
+and handed straight to the client.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import socket
+import subprocess
+import sys
+import tempfile
+import time
+import unittest
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+# See test_client.py: makes `bobby_browser` importable for
+# `python3 -m unittest discover -s packages/python-sdk/tests` run straight
+# from a checkout, with no `pip install` step first.
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from bobby_browser import BrowserRuntimeClient  # noqa: E402
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+BOBBY_BIN = REPO_ROOT / "target" / "release" / "bobby"
+
+_SKIP_REASON = "BOBBY_CHROME_EXECUTABLE is unset; skipping the live runtime test"
+
+
+def _free_tcp_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
+        probe.bind(("127.0.0.1", 0))
+        return probe.getsockname()[1]
+
+
+def _wait_for_healthz(base_url: str, deadline: float) -> None:
+    last_error: Exception | None = None
+    while time.monotonic() < deadline:
+        try:
+            with urllib.request.urlopen(f"{base_url}/healthz", timeout=2) as response:
+                if response.status == 200:
+                    return
+        except (urllib.error.URLError, OSError) as error:
+            last_error = error
+        time.sleep(0.25)
+    raise AssertionError(f"bobby serve never became healthy: {last_error}")
+
+
+@unittest.skipUnless(os.environ.get("BOBBY_CHROME_EXECUTABLE"), _SKIP_REASON)
+class LiveRuntimeTests(unittest.TestCase):
+    def test_runtime_info_and_create_session_over_real_http(self) -> None:
+        if not BOBBY_BIN.is_file():
+            self.skipTest(f"{BOBBY_BIN} not built; run: cargo build -p bobby-browser --release")
+
+        with tempfile.TemporaryDirectory(prefix="bobby-python-sdk-live-") as tmp:
+            tmp_path = Path(tmp)
+            # `bobby serve` does not auto-create every storage/browser
+            # directory (deploy/docker/entrypoint.sh pre-creates them for
+            # the same reason) -- the defaults are relative to the process
+            # cwd, which we pin to tmp_path below.
+            for relative in (
+                "data/profiles",
+                "data/uploads",
+                "data/downloads",
+                "data/artifacts",
+                "data/storage/checkpoints",
+            ):
+                (tmp_path / relative).mkdir(parents=True, exist_ok=True)
+
+            bootstrap_path = tmp_path / "bootstrap.env"
+            init = subprocess.run(
+                [str(BOBBY_BIN), "init", "--path", str(bootstrap_path), "--force"],
+                cwd=tmp_path,
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+            self.assertEqual(init.returncode, 0, msg="bobby init failed (see stderr on the CI runner)")
+            bearer = init.stdout.strip()
+            self.assertTrue(bearer, "bobby init printed no bearer on stdout")
+
+            port = _free_tcp_port()
+            config_path = tmp_path / "config.toml"
+            config_path.write_text(
+                f'[server]\nhost = "127.0.0.1"\nport = {port}\n', encoding="utf-8"
+            )
+
+            env = dict(os.environ)
+            env.setdefault("AUTOMATION_RUNTIME_BROWSER_SELECTION", json.dumps({"preference": {"mode": "managedChromium"}}))
+
+            serve_stdout = open(tmp_path / "serve.stdout.log", "wb")
+            serve_stderr = open(tmp_path / "serve.stderr.log", "wb")
+            process = subprocess.Popen(
+                [str(BOBBY_BIN), "serve", "--config", str(config_path), "--bootstrap-env", str(bootstrap_path)],
+                cwd=tmp_path,
+                env=env,
+                stdout=serve_stdout,
+                stderr=serve_stderr,
+            )
+            try:
+                base_url = f"http://127.0.0.1:{port}"
+                _wait_for_healthz(base_url, deadline=time.monotonic() + 30)
+
+                client = BrowserRuntimeClient(base_url, bearer)
+                info = client.runtime_info()
+                self.assertIn("version", info)
+                self.assertIsInstance(info["capabilities"], list)
+
+                session = client.create_session({"profile": "default", "proxy": None})
+                self.assertTrue(session.get("id"))
+                self.assertEqual(session.get("profile"), "default")
+            finally:
+                process.terminate()
+                try:
+                    process.wait(timeout=10)
+                except subprocess.TimeoutExpired:
+                    process.kill()
+                    process.wait(timeout=10)
+                with contextlib.suppress(Exception):
+                    serve_stdout.close()
+                with contextlib.suppress(Exception):
+                    serve_stderr.close()
+
+
+if __name__ == "__main__":
+    unittest.main()