scalebrowser 0.2.0__py3-none-any.whl

scalebrowser/client.py

@@ -0,0 +1,825 @@
+"""The async Scalebrowser client — typed REST surface + a direct-CDP entry point.
+
+Every endpoint path is defined here exactly once, so endpoint drift is a
+one-file change (the transport in ``_http.py`` is the only other HTTP-aware
+module). The driver plane is direct-CDP (``connect_cdp`` / ``launch``).
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import Any, AsyncIterator, Mapping, Optional, Sequence, Union
+from urllib.parse import quote
+
+import httpx
+from pydantic import BaseModel
+
+from ._http import AsyncTransport
+from .cdp import CdpSession, connect_cdp
+from .errors import ApiError, ErrorCode
+from .events import iter_events
+from .models import (
+    RunStep,
+    AuditStatus,
+    BulkAssignProxyBody,
+    BulkCreateBody,
+    BulkIdsBody,
+    CheckProxyConfigBody,
+    CredentialBundle,
+    CredentialImportResult,
+    CredentialMeta,
+    CreateGroupBody,
+    CreatePresetBody,
+    CreateProfileBody,
+    CreateProxyBody,
+    Event,
+    Extension,
+    ExtensionsResult,
+    Group,
+    Metrics,
+    MetricsAvailability,
+    PersonaConstraintOptions,
+    Preset,
+    Profile,
+    Proxy,
+    ProxyCheckResult,
+    RevealedCredential,
+    SessionExportBody,
+    SessionExportResult,
+    SessionImportBody,
+    StartProfileResult,
+    StopProfileResult,
+    UpdatePresetBody,
+    UpdateProfileBody,
+    UpdateProxyBody,
+)
+
+from .models_control import (
+    Account,
+    ArtifactBytes,
+    ArtifactPutResult,
+    HealthStatus,
+    InterruptionLockView,
+    InterruptionRuleRow,
+    ReadyStatus,
+    SetInterruptionLockBody,
+    SetInterruptionRuleBody,
+)
+from .models_identity import (
+    BindInboxBody,
+    Inbox,
+    InboxBindings,
+    PasskeyRow,
+    PutInboxBody,
+    RevealCookiesBody,
+    RevealCookiesResult,
+)
+from .models_runs import ActivitySnapshot, AgentRun
+
+DEFAULT_BASE_URL = "http://127.0.0.1:8787"
+
+#: Mirrors ``CapacityConfig::default()`` — used by the metrics fallback.
+DEFAULT_CAPACITY_MAX_CONCURRENT = 64
+DEFAULT_CAPACITY_RAM_BUDGET_MB = 24_576
+
+BodyLike = Union[BaseModel, Mapping[str, Any], None]
+
+
+def _payload(body: BodyLike) -> Optional[dict[str, Any]]:
+    """Normalize a pydantic model / mapping request body to a JSON dict."""
+    if body is None:
+        return None
+    if isinstance(body, BaseModel):
+        return body.model_dump(by_alias=True, exclude_none=True, mode="json")
+    return dict(body)
+
+
+def _q(value: str) -> str:
+    return quote(value, safe="")
+
+
+class AsyncScalebrowserClient:
+    """Async client for the Scalebrowser daemon REST + direct-CDP surfaces.
+
+    >>> async with AsyncScalebrowserClient(token="…") as sb:
+    ...     started = await sb.start_profile(profile_id, headless=True)
+    ...     async with await sb.connect_cdp(started, profile_id) as cdp:
+    ...         await cdp.navigate("https://example.com")
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        token: Optional[str] = None,
+        *,
+        timeout: float = 30.0,
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._t = AsyncTransport(
+            base_url, token, timeout=timeout, transport=transport, http_client=http_client
+        )
+
+    @property
+    def transport(self) -> AsyncTransport:
+        return self._t
+
+    def __repr__(self) -> str:
+        masked = "***" if self._t.token else None
+        return f"AsyncScalebrowserClient(base_url={self._t.base_url!r}, token={masked!r})"
+
+    # ── profiles ──────────────────────────────────────────────────────────────
+
+    async def list_profiles(
+        self,
+        *,
+        group: Optional[str] = None,
+        state: Optional[str] = None,
+        q: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        sort: Optional[str] = None,
+        order: Optional[str] = None,
+    ) -> list[Profile]:
+        """List profiles.
+
+        ``sort`` (``created_at`` | ``name`` | ``runtime_state`` | ``last_open_at``)
+        and ``order`` (``asc`` | ``desc``) are applied by the DAEMON over the whole
+        filtered set — sorting a fetched page would order a minority of a paged
+        fleet while looking authoritative.
+        """
+        data = await self._t.get(
+            "/v1/profiles",
+            params={
+                "group": group,
+                "state": state,
+                "q": q,
+                "limit": limit,
+                "offset": offset,
+                "sort": sort,
+                "order": order,
+            },
+        )
+        return [Profile.model_validate(item) for item in data]
+
+    async def get_profile(self, profile_id: str) -> Profile:
+        data = await self._t.get(f"/v1/profiles/{_q(profile_id)}")
+        return Profile.model_validate(data)
+
+    async def create_profile(self, body: Union[CreateProfileBody, Mapping[str, Any]]) -> Profile:
+        data = await self._t.post("/v1/profiles", _payload(body))
+        return Profile.model_validate(data)
+
+    async def update_profile(
+        self, profile_id: str, body: Union[UpdateProfileBody, Mapping[str, Any]]
+    ) -> Profile:
+        data = await self._t.patch(f"/v1/profiles/{_q(profile_id)}", _payload(body))
+        return Profile.model_validate(data)
+
+    async def delete_profile(self, profile_id: str) -> None:
+        await self._t.delete(f"/v1/profiles/{_q(profile_id)}")
+
+    async def start_profile(self, profile_id: str, *, headless: Optional[bool] = None) -> StartProfileResult:
+        body: dict[str, Any] = {} if headless is None else {"headless": headless}
+        data = await self._t.post(f"/v1/profiles/{_q(profile_id)}/start", body)
+        return StartProfileResult.model_validate(data)
+
+    async def stop_profile(self, profile_id: str) -> StopProfileResult:
+        data = await self._t.post(f"/v1/profiles/{_q(profile_id)}/stop", {})
+        return StopProfileResult.model_validate(data)
+
+    # ── bulk (PRD §D2) ───────────────────────────────────────────────────────
+
+    async def bulk_create_profiles(
+        self,
+        preset_id: str,
+        count: int,
+        *,
+        name_prefix: Optional[str] = None,
+        group_id: Optional[str] = None,
+    ) -> list[Profile]:
+        body = BulkCreateBody(
+            preset_id=preset_id, count=count, name_prefix=name_prefix, group_id=group_id
+        )
+        data = await self._t.post("/v1/bulk/profiles", _payload(body))
+        return [Profile.model_validate(item) for item in data]
+
+    async def list_profile_ids(
+        self,
+        *,
+        group: Optional[str] = None,
+        state: Optional[str] = None,
+        q: Optional[str] = None,
+        sort: Optional[str] = None,
+        order: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Every id matching the filters, unpaged — what "act on all matches" needs.
+
+        ``list_profiles`` is paged, so acting on "everything" from it only ever
+        covers the page that was fetched. This costs one request and carries no
+        persona payloads.
+        """
+        return await self._t.get(
+            "/v1/profiles/ids",
+            params={"group": group, "state": state, "q": q, "sort": sort, "order": order},
+        )
+
+    async def bulk_start(self, ids: Sequence[str], *, headless: Optional[bool] = None) -> Any:
+        """Start a batch.
+
+        ``headless`` is the ONE visibility decision for the run; omitted means
+        headless, the right default for an unattended client. The daemon stops at
+        the machine's capacity limit and reports ``started`` / ``remaining`` /
+        ``stopped_reason`` instead of failing every remaining id.
+        """
+        return await self._t.post("/v1/bulk/start", {"ids": list(ids), "headless": headless})
+
+    async def bulk_stop(self, ids: Sequence[str]) -> Any:
+        return await self._t.post("/v1/bulk/stop", _payload(BulkIdsBody(ids=list(ids))))
+
+    async def bulk_delete(self, ids: Sequence[str]) -> Any:
+        return await self._t.post("/v1/bulk/delete", _payload(BulkIdsBody(ids=list(ids))))
+
+    async def bulk_assign_proxy(self, ids: Sequence[str], proxy_id: str) -> Any:
+        body = BulkAssignProxyBody(ids=list(ids), proxy_id=proxy_id)
+        return await self._t.post("/v1/bulk/assign-proxy", _payload(body))
+
+    async def bulk_assign_extensions(
+        self, ids: Sequence[str], ext_refs: Sequence[str]
+    ) -> Any:
+        """Give every id exactly this set of extensions.
+
+        REPLACES rather than adds, the same shape as assigning a proxy. An empty
+        list is a legitimate "none"; an id the library does not hold refuses the
+        whole call.
+        """
+        return await self._t.post(
+            "/v1/bulk/assign-extensions",
+            {"ids": list(ids), "ext_refs": list(ext_refs)},
+        )
+
+    # ── groups ────────────────────────────────────────────────────────────────
+
+    async def list_groups(self) -> list[Group]:
+        data = await self._t.get("/v1/groups")
+        return [Group.model_validate(item) for item in data]
+
+    async def create_group(self, body: Union[CreateGroupBody, Mapping[str, Any]]) -> Group:
+        data = await self._t.post("/v1/groups", _payload(body))
+        return Group.model_validate(data)
+
+    async def get_group(self, group_id: str) -> Group:
+        data = await self._t.get(f"/v1/groups/{_q(group_id)}")
+        return Group.model_validate(data)
+
+    async def update_group(self, group_id: str, body: Mapping[str, Any]) -> Group:
+        data = await self._t.patch(f"/v1/groups/{_q(group_id)}", _payload(body))
+        return Group.model_validate(data)
+
+    async def delete_group(self, group_id: str) -> None:
+        await self._t.delete(f"/v1/groups/{_q(group_id)}")
+
+    # ── presets ───────────────────────────────────────────────────────────────
+
+    async def list_presets(self) -> list[Preset]:
+        data = await self._t.get("/v1/presets")
+        return [Preset.model_validate(item) for item in data]
+
+    async def create_preset(self, body: Union[CreatePresetBody, Mapping[str, Any]]) -> Preset:
+        data = await self._t.post("/v1/presets", _payload(body))
+        return Preset.model_validate(data)
+
+    async def get_preset(self, preset_id: str) -> Preset:
+        data = await self._t.get(f"/v1/presets/{_q(preset_id)}")
+        return Preset.model_validate(data)
+
+    async def update_preset(
+        self, preset_id: str, body: Union[UpdatePresetBody, Mapping[str, Any]]
+    ) -> Preset:
+        data = await self._t.patch(f"/v1/presets/{_q(preset_id)}", _payload(body))
+        return Preset.model_validate(data)
+
+    async def delete_preset(self, preset_id: str) -> None:
+        await self._t.delete(f"/v1/presets/{_q(preset_id)}")
+
+    async def get_persona_constraints(self) -> PersonaConstraintOptions:
+        """The values a preset's ``constraints`` may take.
+
+        Ask rather than hardcode: the region list comes from the daemon's
+        embedded persona model, so a pinned copy drifts the moment that model
+        changes and every create returns a 400.
+        """
+        data = await self._t.get("/v1/persona/constraints")
+        return PersonaConstraintOptions.model_validate(data)
+
+    # ── proxies ───────────────────────────────────────────────────────────────
+
+    async def list_proxies(self) -> list[Proxy]:
+        data = await self._t.get("/v1/proxies")
+        return [Proxy.model_validate(item) for item in data]
+
+    async def create_proxy(self, body: Union[CreateProxyBody, Mapping[str, Any]]) -> Proxy:
+        data = await self._t.post("/v1/proxies", _payload(body))
+        return Proxy.model_validate(data)
+
+    async def get_proxy(self, proxy_id: str) -> Proxy:
+        data = await self._t.get(f"/v1/proxies/{_q(proxy_id)}")
+        return Proxy.model_validate(data)
+
+    async def update_proxy(
+        self, proxy_id: str, body: Union[UpdateProxyBody, Mapping[str, Any]]
+    ) -> Proxy:
+        data = await self._t.patch(f"/v1/proxies/{_q(proxy_id)}", _payload(body))
+        return Proxy.model_validate(data)
+
+    async def delete_proxy(self, proxy_id: str) -> None:
+        await self._t.delete(f"/v1/proxies/{_q(proxy_id)}")
+
+    async def check_proxy(self, proxy_id: str) -> ProxyCheckResult:
+        data = await self._t.post(f"/v1/proxies/{_q(proxy_id)}/check", {})
+        return ProxyCheckResult.model_validate(data)
+
+    async def check_proxy_config(
+        self, body: Union[CheckProxyConfigBody, Mapping[str, Any]]
+    ) -> ProxyCheckResult:
+        """Probe a proxy config WITHOUT persisting it — validate before committing."""
+        data = await self._t.post("/v1/proxies/check", _payload(body))
+        return ProxyCheckResult.model_validate(data)
+
+    # ── live detector audit ──────────────────────────────────────────────────
+    #
+    # Drives the profile's OWN running browser through ~15 third-party fingerprint
+    # sites and keeps what each one saw. The profile must be RUNNING; the run takes
+    # minutes, so ``start_audit`` returns immediately and you poll ``get_audit``.
+
+    async def start_audit(self, profile_id: str) -> AuditStatus:
+        """Queue a run. ``409`` if the profile is not running, or one is in flight."""
+        data = await self._t.post(f"/v1/profiles/{_q(profile_id)}/audit", {})
+        return AuditStatus.model_validate(data)
+
+    async def get_audit(self, profile_id: str) -> AuditStatus:
+        """State plus the last stored report."""
+        data = await self._t.get(f"/v1/profiles/{_q(profile_id)}/audit")
+        return AuditStatus.model_validate(data)
+
+    # ── platform credentials ─────────────────────────────────────────────────
+    #
+    # Stored logins, so an agent can sign a profile into a platform WITHOUT ever
+    # holding the password: the daemon decrypts and types it. Only
+    # :meth:`reveal_credential` and the bundle calls return plaintext, and all of
+    # them need the vault password — the bearer token alone is not enough, because
+    # the MCP agent layer authenticates with exactly the same one.
+    #
+    # ``platform`` is whatever you have: the service's domain ("discord.com"),
+    # its name ("Discord") or a host under it ("www.discord.com"). The daemon
+    # resolves all of them to ONE key — the registrable domain — and every
+    # response echoes that key, so a later :meth:`delete_credential` addresses
+    # the same row. Pass a whole sign-in URL only to the MCP tools: here the
+    # platform is a path segment, and a "/" in it is refused rather than read
+    # as a path.
+
+    async def list_credentials(self, profile_id: str) -> list[CredentialMeta]:
+        """Which platforms this profile can log into. Never a secret."""
+        data = await self._t.get(f"/v1/profiles/{_q(profile_id)}/credentials")
+        return [CredentialMeta.model_validate(c) for c in (data or [])]
+
+    async def put_credential(
+        self,
+        profile_id: str,
+        platform: str,
+        *,
+        username: str | None = None,
+        password: str | None = None,
+        totp_secret: str | None = None,
+        login_url: str | None = None,
+    ) -> CredentialMeta:
+        """Store or update one login.
+
+        An omitted secret keeps its stored value rather than clearing it — an edit
+        form never saw the password in the clear, so it cannot resend one. Delete
+        the row to remove a credential. ``totp_secret`` may be pasted exactly as a
+        site presents it (grouped, lower case); it is normalised and test-decoded
+        by the daemon, so a broken key is refused here rather than mid-login.
+        """
+        body = {
+            "username": username,
+            "password": password,
+            "totp_secret": totp_secret,
+            "login_url": login_url,
+        }
+        data = await self._t.request(
+            "PUT",
+            f"/v1/profiles/{_q(profile_id)}/credentials/{_q(platform)}",
+            json={k: v for k, v in body.items() if v is not None},
+        )
+        return CredentialMeta.model_validate(data)
+
+    async def delete_credential(self, profile_id: str, platform: str) -> None:
+        """Forget one login. The account itself is untouched."""
+        await self._t.delete(f"/v1/profiles/{_q(profile_id)}/credentials/{_q(platform)}")
+
+    async def reveal_credential(
+        self, profile_id: str, platform: str, vault_password: str
+    ) -> RevealedCredential:
+        """Read one login back in the clear. Needs the vault password."""
+        data = await self._t.post(
+            f"/v1/profiles/{_q(profile_id)}/credentials/{_q(platform)}/reveal",
+            {"vault_password": vault_password},
+        )
+        return RevealedCredential.model_validate(data)
+
+    async def export_credentials(
+        self, profile_id: str, vault_password: str, password: str
+    ) -> CredentialBundle:
+        """Pack this profile's logins into a bundle sealed with ``password``.
+
+        ``password`` is deliberately separate from the vault password: a backup
+        gets handed to another machine, and that must not also hand over access to
+        this daemon. It is the answer to a lost master key — a daemon-generated
+        password exists nowhere else.
+        """
+        data = await self._t.post(
+            f"/v1/profiles/{_q(profile_id)}/credential-bundle/export",
+            {"vault_password": vault_password, "password": password},
+        )
+        return CredentialBundle.model_validate(data)
+
+    async def import_credentials(
+        self, profile_id: str, vault_password: str, password: str, bundle: str
+    ) -> CredentialImportResult:
+        """Restore a bundle into ``profile_id``."""
+        data = await self._t.post(
+            f"/v1/profiles/{_q(profile_id)}/credential-bundle/import",
+            {"vault_password": vault_password, "password": password, "bundle": bundle},
+        )
+        return CredentialImportResult.model_validate(data)
+
+    async def vault_status(self) -> VaultStatus:
+        """Has a vault password been set on this daemon?"""
+        data = await self._t.get("/v1/vault")
+        return VaultStatus.model_validate(data)
+
+    async def set_vault_password(
+        self, new_password: str, current_password: str | None = None
+    ) -> None:
+        """Set the vault password, or change it (then ``current_password`` is required)."""
+        body: dict[str, str] = {"new_password": new_password}
+        if current_password is not None:
+            body["current_password"] = current_password
+        await self._t.request("PUT", "/v1/vault", json=body)
+
+    # ── extension library (daemon-wide) ──────────────────────────────────────
+    #
+    # Upload a ``.crx``; the daemon lifts its public key out of the CRX header and
+    # writes it into the unpacked ``manifest.json``, so every profile loads the
+    # package under its CANONICAL Web-Store id. A key-less package is refused — it
+    # would take a path-derived id, identical across the fleet.
+
+    async def list_library_extensions(self) -> list[Extension]:
+        """The library, newest first."""
+        data = await self._t.get("/v1/extensions")
+        return [Extension.model_validate(e) for e in (data or [])]
+
+    async def upload_extension(self, crx: bytes) -> Extension:
+        """Add a package from raw ``.crx`` bytes.
+
+        A new VERSION is stocked alongside the existing ones (profiles draw their
+        own); re-uploading the same version replaces it.
+        """
+        data = await self._t.request("POST", "/v1/extensions", content=crx)
+        return Extension.model_validate(data)
+
+    async def get_library_extension(self, ext_id: str) -> Extension:
+        """One library entry."""
+        data = await self._t.get(f"/v1/extensions/{_q(ext_id)}")
+        return Extension.model_validate(data)
+
+    async def delete_library_extension(self, ext_id: str) -> None:
+        """Remove EVERY version of a package, its files and every assignment of it."""
+        await self._t.delete(f"/v1/extensions/{_q(ext_id)}")
+
+    async def delete_library_extension_version(self, ext_id: str, version: str) -> None:
+        """Remove ONE stocked version.
+
+        Assignments survive — they name the extension, not the version — unless
+        this was the last version, in which case they go with it.
+        """
+        await self._t.delete(f"/v1/extensions/{_q(ext_id)}/{_q(version)}")
+
+    # ── extensions per profile ───────────────────────────────────────────────
+    #
+    # ``ext_ref`` is a LIBRARY ID, not a path. The launch copies each assigned
+    # package into the profile's own tree and loads that, so files and state stay
+    # per-profile while the id stays shared (the camouflage, not the leak).
+
+    async def list_extensions(self, profile_id: str) -> ExtensionsResult:
+        """The profile's assigned set, resolved, + the launch policy."""
+        data = await self._t.get(f"/v1/profiles/{_q(profile_id)}/extensions")
+        return ExtensionsResult.model_validate(data)
+
+    async def attach_extension(self, profile_id: str, ext_ref: str) -> ExtensionsResult:
+        """Assign a library id (idempotent) → the updated set + policy. 404 if unknown."""
+        data = await self._t.post(
+            f"/v1/profiles/{_q(profile_id)}/extensions", {"ext_ref": ext_ref}
+        )
+        return ExtensionsResult.model_validate(data)
+
+    async def detach_extension(self, profile_id: str, ext_ref: str) -> ExtensionsResult:
+        """Unassign a library id (idempotent) → the updated set + policy."""
+        data = await self._t.delete(
+            f"/v1/profiles/{_q(profile_id)}/extensions", {"ext_ref": ext_ref}
+        )
+        return ExtensionsResult.model_validate(data)
+
+    # ── session bundles (AC-ST-002/003) ──────────────────────────────────────
+
+    async def export_session(
+        self, profile_id: str, password: str, *, kinds: Optional[Sequence[str]] = None
+    ) -> SessionExportResult:
+        body = SessionExportBody(password=password, kinds=list(kinds) if kinds else None)
+        data = await self._t.post(f"/v1/profiles/{_q(profile_id)}/session/export", _payload(body))
+        return SessionExportResult.model_validate(data)
+
+    async def import_session(self, profile_id: str, password: str, bundle: str) -> Any:
+        body = SessionImportBody(password=password, bundle=bundle)
+        return await self._t.post(f"/v1/profiles/{_q(profile_id)}/session/import", _payload(body))
+
+    # ── trusted input (G8) ───────────────────────────────────────────────────
+
+    async def send_input(self, profile_id: str, body: Mapping[str, Any]) -> Any:
+        return await self._t.post(f"/v1/profiles/{_q(profile_id)}/input", dict(body))
+
+    # ── metrics (with fallback) ──────────────────────────────────────────────
+
+    async def get_metrics(self) -> Metrics:
+        try:
+            data = await self._t.get("/v1/metrics")
+        except ApiError as err:
+            if err.status == 404 or err.code == ErrorCode.NOT_FOUND:
+                return self._derive_metrics(await self.list_profiles(limit=10_000))
+            raise
+        return Metrics.model_validate(data)
+
+    @staticmethod
+    def _derive_metrics(profiles: Sequence[Profile]) -> Metrics:
+        running = sum(1 for p in profiles if p.runtime_state == "running")
+        unavailable = MetricsAvailability(
+            ram="unavailable",
+            cpu="unavailable",
+            gpu="unavailable",
+            vram="unavailable",
+            per_profile="unavailable",
+        )
+        return Metrics(
+            running=running,
+            capacity_max_concurrent=DEFAULT_CAPACITY_MAX_CONCURRENT,
+            ram_used_mb=None,
+            ram_budget_mb=DEFAULT_CAPACITY_RAM_BUDGET_MB,
+            vram_used_mb=None,
+            vram_budget_mb=None,
+            cpu_pct=None,
+            gpu_pct=None,
+            source="derived",
+            sampled_at=None,
+            availability=unavailable,
+            profiles=[],
+        )
+
+    # ── agent runs ───────────────────────────────────────────────────────────
+
+    async def list_runs(
+        self,
+        *,
+        profile_id: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> list[AgentRun]:
+        """Runs, newest first. Read-only, all of it."""
+        data = await self._t.get(
+            "/v1/runs", params={"profile_id": profile_id, "limit": limit, "offset": offset}
+        )
+        return [AgentRun.model_validate(row) for row in data or []]
+
+    async def get_run(self, run_id: str) -> AgentRun:
+        data = await self._t.get(f"/v1/runs/{_q(run_id)}")
+        return AgentRun.model_validate(data)
+
+    async def list_run_steps(
+        self, run_id: str, *, limit: Optional[int] = None, offset: Optional[int] = None
+    ) -> list[RunStep]:
+        """A run's steps, oldest first — the order they happened in."""
+        data = await self._t.get(
+            f"/v1/runs/{_q(run_id)}/steps", params={"limit": limit, "offset": offset}
+        )
+        return [RunStep.model_validate(row) for row in data or []]
+
+    async def get_run_shot(self, run_id: str, seq: int) -> ArtifactBytes:
+        """The still taken at one step, as JPEG bytes.
+
+        The picture shows a customer's account, so it is decrypted only on the
+        way out and never cached anywhere shared.
+        """
+        content, content_type, filename = await self._t.get_bytes(
+            f"/v1/runs/{_q(run_id)}/shots/{seq}"
+        )
+        return ArtifactBytes(data=content, content_type=content_type, filename=filename)
+
+    async def get_activity(self) -> ActivitySnapshot:
+        """What every running profile currently shows."""
+        return ActivitySnapshot.model_validate(await self._t.get("/v1/activity"))
+
+    # ── mailboxes ────────────────────────────────────────────────────────────
+
+    async def list_inboxes(self) -> list[Inbox]:
+        """Mailboxes; passwords are never returned."""
+        data = await self._t.get("/v1/inboxes")
+        return [Inbox.model_validate(row) for row in data or []]
+
+    async def create_inbox(self, body: Union[PutInboxBody, Mapping[str, Any]]) -> Inbox:
+        return Inbox.model_validate(await self._t.post("/v1/inboxes", _payload(body)))
+
+    async def update_inbox(
+        self, inbox_id: str, body: Union[PutInboxBody, Mapping[str, Any]]
+    ) -> Inbox:
+        """An omitted ``password`` leaves the stored one unchanged."""
+        return Inbox.model_validate(await self._t.put(f"/v1/inboxes/{_q(inbox_id)}", _payload(body)))
+
+    async def delete_inbox(self, inbox_id: str) -> None:
+        await self._t.delete(f"/v1/inboxes/{_q(inbox_id)}")
+
+    async def get_inbox_bindings(self, profile_id: str) -> InboxBindings:
+        """Which mailbox this profile's confirmation codes arrive in, per channel."""
+        data = await self._t.get(f"/v1/profiles/{_q(profile_id)}/inbox")
+        return InboxBindings.model_validate(data)
+
+    async def bind_inbox(
+        self, profile_id: str, body: Union[BindInboxBody, Mapping[str, Any]]
+    ) -> InboxBindings:
+        data = await self._t.put(f"/v1/profiles/{_q(profile_id)}/inbox", _payload(body))
+        return InboxBindings.model_validate(data)
+
+    async def unbind_inbox(self, profile_id: str, channel: str) -> None:
+        await self._t.delete(f"/v1/profiles/{_q(profile_id)}/inbox/{_q(channel)}")
+
+    # ── passkeys ─────────────────────────────────────────────────────────────
+
+    async def list_passkeys(self, profile_id: str) -> list[PasskeyRow]:
+        """What this profile can sign in to without a password. Metadata only."""
+        data = await self._t.get(f"/v1/profiles/{_q(profile_id)}/passkeys")
+        return [PasskeyRow.model_validate(row) for row in data or []]
+
+    async def delete_passkey(self, profile_id: str, credential_id: str) -> None:
+        """Retire a passkey.
+
+        Calling it twice is meaningful: the first call retires a live key and
+        leaves a headstone, the second clears the headstone for good.
+        """
+        await self._t.delete(f"/v1/profiles/{_q(profile_id)}/passkeys/{_q(credential_id)}")
+
+    # ── interruptions ────────────────────────────────────────────────────────
+
+    async def list_interruption_locks(self) -> InterruptionLockView:
+        """Which browser surfaces are locked shut, and what actually applies."""
+        return InterruptionLockView.model_validate(await self._t.get("/v1/interruptions/locks"))
+
+    async def set_interruption_lock(
+        self, body: Union[SetInterruptionLockBody, Mapping[str, Any]]
+    ) -> None:
+        """Omit ``profile_id`` to set the account-wide default."""
+        await self._t.put("/v1/interruptions/locks", _payload(body))
+
+    async def list_interruption_rules(self) -> list[InterruptionRuleRow]:
+        """Standing answers per origin and kind."""
+        data = await self._t.get("/v1/interruptions/rules")
+        return [InterruptionRuleRow.model_validate(row) for row in data or []]
+
+    async def set_interruption_rule(
+        self, body: Union[SetInterruptionRuleBody, Mapping[str, Any]]
+    ) -> None:
+        await self._t.put("/v1/interruptions/rules", _payload(body))
+
+    async def delete_interruption_rule(
+        self, origin: str, kind: str, profile_id: Optional[str] = None
+    ) -> None:
+        await self._t.request(
+            "DELETE",
+            "/v1/interruptions/rules",
+            params={"origin": origin, "kind": kind, "profile_id": profile_id},
+        )
+
+    # ── artifacts ────────────────────────────────────────────────────────────
+
+    async def put_artifact(
+        self, profile_id: str, data: bytes, name: Optional[str] = None
+    ) -> ArtifactPutResult:
+        """Hand the daemon a file so ``interact action=upload`` has something to attach.
+
+        The bytes are bound to the PROFILE, not to a reservation: set a file up
+        before leasing, and a lease released mid-task does not destroy it.
+        """
+        result = await self._t.request(
+            "POST",
+            f"/v1/profiles/{_q(profile_id)}/artifacts",
+            content=data,
+            params={"name": name},
+        )
+        return ArtifactPutResult.model_validate(result)
+
+    async def get_artifact(self, artifact_id: str) -> ArtifactBytes:
+        """Fetch one artifact's bytes — a screenshot, a download, a saved PDF.
+
+        A miss is a plain 404 whether the id never existed, expired, or belonged
+        to a released lease: the caller's next move is the same in all three.
+        """
+        content, content_type, filename = await self._t.get_bytes(
+            f"/v1/artifacts/{_q(artifact_id)}"
+        )
+        return ArtifactBytes(data=content, content_type=content_type, filename=filename)
+
+    # ── cookies ──────────────────────────────────────────────────────────────
+
+    async def reveal_cookies(
+        self, profile_id: str, body: Union[RevealCookiesBody, Mapping[str, Any]]
+    ) -> RevealCookiesResult:
+        """The one door a cookie VALUE leaves through, and it needs the vault password.
+
+        A session cookie skips both the password and the second factor, which is
+        why every other cookie surface answers with metadata only.
+        """
+        data = await self._t.post(f"/v1/profiles/{_q(profile_id)}/cookies/reveal", _payload(body))
+        return RevealCookiesResult.model_validate(data)
+
+    # ── account + health ─────────────────────────────────────────────────────
+
+    async def get_account(self) -> Account:
+        """Licence state for display. The launch gate stays the authority on starts.
+
+        A daemon predating the route answers 404, and that is not an error worth
+        raising: it means "self-hosted, no control plane", which is exactly what
+        ``licensed=False`` says. Same tolerance as :meth:`get_metrics`.
+        """
+        try:
+            data = await self._t.get("/v1/account")
+        except ApiError as err:
+            if err.status == 404:
+                return Account()
+            raise
+        return Account.model_validate(data)
+
+    async def health(self) -> HealthStatus:
+        """"Is the daemon alive?" Public, needs no token."""
+        return HealthStatus.model_validate(await self._t.get("/health"))
+
+    async def ready(self) -> ReadyStatus:
+        """"Can it serve?" Local facts only — the control plane is not consulted."""
+        return ReadyStatus.model_validate(await self._t.get("/health/ready"))
+
+    # ── events (SSE) ─────────────────────────────────────────────────────────
+
+    async def events(self) -> AsyncIterator[Event]:
+        """Async-iterate the daemon lifecycle event stream (``GET /v1/events``)."""
+        async for event in iter_events(self._t):
+            yield event
+
+    # ── direct-CDP driver plane ──────────────────────────────────────────────
+
+    async def connect_cdp(
+        self,
+        target: Union[StartProfileResult, str],
+        profile_id: Optional[str] = None,
+        *,
+        attach: bool = True,
+    ) -> CdpSession:
+        """Open a direct-CDP session for a started profile.
+
+        ``target`` is the :class:`StartProfileResult` from :meth:`start_profile`
+        (or a raw ``cdp_ws`` URL). Pass ``profile_id`` to enable ``humanize_*``.
+        """
+        cdp_ws = target.cdp_ws if isinstance(target, StartProfileResult) else target
+        return await connect_cdp(
+            cdp_ws, token=self._t.token, transport=self._t, profile_id=profile_id, attach=attach
+        )
+
+    @asynccontextmanager
+    async def launch(self, profile_id: str, *, headless: bool = True) -> AsyncIterator[CdpSession]:
+        """Start a profile, yield a connected CDP session, and stop it on exit."""
+        result = await self.start_profile(profile_id, headless=headless)
+        cdp = await self.connect_cdp(result, profile_id=profile_id)
+        try:
+            yield cdp
+        finally:
+            try:
+                await cdp.close()
+            finally:
+                await self.stop_profile(profile_id)
+
+    # ── lifecycle ─────────────────────────────────────────────────────────────
+
+    async def aclose(self) -> None:
+        await self._t.aclose()
+
+    async def __aenter__(self) -> "AsyncScalebrowserClient":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()