scalebrowser 0.2.0__py3-none-any.whl

scalebrowser/models.py

@@ -0,0 +1,861 @@
+"""Wire models — a 1:1 mirror of the daemon's serialized domain model and the
+endpoint contract in ``docs/features/api.md`` (kept in lockstep with
+``web-ui/src/api/types.ts``).
+
+All Rust enums serialize ``snake_case``. Timestamps are unix seconds (``int``).
+Read models tolerate unknown fields (forward-compat); request models are plain
+optional-field carriers. This module is the single source of contract truth for
+the SDK: backend drift is a change here + ``client.py``.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter
+
+# ── Enums (string literals; Rust serializes snake_case) ───────────────────────
+
+RuntimeState = Literal["stopped", "starting", "running", "crashed"]
+RUNTIME_STATES: tuple[RuntimeState, ...] = ("stopped", "starting", "running", "crashed")
+
+HostMode = Literal["linux_engine_spoof", "local_native_windows"]
+HOST_MODES: tuple[HostMode, ...] = ("linux_engine_spoof", "local_native_windows")
+
+
+GeoMode = Literal["strict_expected", "follow_exit", "off"]
+GEO_MODES: tuple[GeoMode, ...] = ("strict_expected", "follow_exit", "off")
+
+ProxyKind = Literal["http", "socks5", "gateway"]
+PROXY_KINDS: tuple[ProxyKind, ...] = ("http", "socks5", "gateway")
+
+Rotation = Literal["sticky", "rotating"]
+ROTATIONS: tuple[Rotation, ...] = ("sticky", "rotating")
+
+SessionKind = Literal["cookies", "local_storage", "indexed_db", "service_worker"]
+
+OsFamily = Literal["windows", "macos", "linux"]
+
+#: Who is driving: an agent holding a reservation, or a person at a window.
+RunActor = Literal["agent", "human"]
+
+#: How a run ended. ``reached``/``partial`` appear only when a source claimed it —
+#: the daemon can tell that a run ended, never that it worked.
+RunOutcome = Literal[
+    "running", "reached", "partial", "blocked", "interrupted", "unknown"
+]
+
+#: What kind of thing a trail entry is.
+StepKind = Literal["page", "action", "interruption"]
+
+
+class _ReadModel(BaseModel):
+    """Base for models read from the daemon — tolerant of unknown fields."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
+class _WriteModel(BaseModel):
+    """Base for request payloads the SDK sends to the daemon."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+
+# ── Persona (read-only; derived deterministically from `seed`) ────────────────
+
+
+class Screen(_ReadModel):
+    width: int
+    height: int
+    avail_width: int
+    avail_height: int
+    color_depth: int
+    pixel_depth: int
+    device_pixel_ratio: float
+    orientation: str
+
+
+class Locale(_ReadModel):
+    language: str
+    languages: list[str]
+    accept_language: str
+
+
+class WebGl(_ReadModel):
+    vendor: str
+    renderer: str
+    unmasked_vendor: str
+    unmasked_renderer: str
+    version: str
+    shading_language_version: str
+
+
+class WebGpu(_ReadModel):
+    present: bool
+    adapter: str
+    vendor: str
+    architecture: str
+    device: str
+    description: str
+
+
+class AudioProps(_ReadModel):
+    sample_rate: int
+    base_latency: float
+    max_channel_count: int
+    output_channel_count: int
+
+
+class SpeechVoice(_ReadModel):
+    name: str
+    lang: str
+    local_service: bool
+    default: bool
+
+
+class GpuPersona(_ReadModel):
+    backend: str
+    vendor: str
+    model: str
+
+
+class Brand(_ReadModel):
+    brand: str
+    version: str
+
+
+class ClientHints(_ReadModel):
+    brands: list[Brand]
+    full_version_list: list[Brand]
+    platform: str
+    platform_version: str
+    architecture: str
+    bitness: str
+    model: str
+    mobile: bool
+    ua_full_version: str
+    wow64: bool
+
+
+class PermissionDefaults(_ReadModel):
+    notifications: str
+    geolocation: str
+    camera: str
+    microphone: str
+
+
+class MediaDevice(_ReadModel):
+    kind: str
+    label: str
+    device_id: str
+    group_id: str
+
+
+class PersonaMisc(_ReadModel):
+    webdriver: bool
+    get_installed_related_apps: bool
+    max_touch_points: int
+    pdf_viewer_enabled: bool
+    headless_guards: bool
+
+
+class Persona(_ReadModel):
+    os: OsFamily
+    user_agent: str
+    platform: str
+    browser_version: str
+    screen: Screen
+    hardware_concurrency: int
+    device_memory: int
+    timezone: str
+    locale: Locale
+    webgl: WebGl
+    webgpu: WebGpu
+    fonts: list[str]
+    noise_seed: int
+    audio: AudioProps
+    speech_voices: list[SpeechVoice]
+    gpu_persona: GpuPersona
+    client_hints: ClientHints
+    permissions: PermissionDefaults
+    media_devices: list[MediaDevice]
+    misc: PersonaMisc
+
+
+# ── Resources ─────────────────────────────────────────────────────────────────
+
+
+#: How protected a profile is right now, decided by the daemon WITHOUT starting
+#: a browser — it runs the same gates the launch runs. ``blocked`` means the
+#: launch will refuse this profile.
+ProtectionLevel = Literal["ok", "warn", "blocked"]
+
+
+class ProtectionStatus(_ReadModel):
+    level: ProtectionLevel
+    #: Plain-language findings, worst first. Empty exactly when ``level`` is ``ok``.
+    reasons: list[str] = []
+
+
+class Profile(_ReadModel):
+    """A browser identity profile (``profiles`` table)."""
+
+    id: str
+    name: str
+    runtime_state: RuntimeState
+    enabled: bool
+    crash_reason: Optional[str] = None
+    pid: Optional[int] = None
+    run_lock: Optional[str] = None
+    seed: str
+    engine_version: str
+    persona: Persona
+    host_mode: HostMode
+    gpu_persona: Optional[str] = None
+    group_id: Optional[str] = None
+    proxy_id: Optional[str] = None
+    geo_mode: GeoMode
+    expected_country: Optional[str] = None
+    data_dir: str
+    created_at: int
+    last_open_at: Optional[int] = None
+    #: Additive: present on list/get (``ProfileView``), absent on create/delete/
+    #: bulk, which answer the bare profile.
+    protection: Optional[ProtectionStatus] = None
+    #: Platform slugs with a stored login, sorted by the daemon. Additive — a
+    #: daemon predating the credential vault simply omits it.
+    platforms: list[str] = []
+
+
+class Group(_ReadModel):
+    id: str
+    name: str
+    created_at: int
+
+
+class PresetConfig(_ReadModel):
+    """Operating config: what the created profiles DO.
+
+    Every field mirrors a ``POST /v1/profiles`` body field. The daemon refuses an
+    unknown key with a 400 instead of dropping it — a preset makes up to 1000
+    profiles, so a swallowed key is a thousand wrong ones.
+    """
+
+    # Pin the batch to one engine build. Omit for per-profile version diversity.
+    engine_version: Optional[str] = None
+    host_mode: Optional[HostMode] = None
+    geo_mode: Optional[GeoMode] = None
+    # The geo GATE's expectation — not the persona's drawn region.
+    expected_country: Optional[str] = None
+    group_id: Optional[str] = None
+    proxy_id: Optional[str] = None
+    #: Library ids every profile of the batch is created with. ``None`` leaves the
+    #: key out of the request entirely, which the daemon reads as "none" — the same
+    #: shape every other key of this half has.
+    extensions: Optional[list[str]] = None
+
+
+class PresetConstraints(_ReadModel):
+    """Generator constraints: what the created profiles ARE.
+
+    Exactly one axis, because an axis is only honest here if the daemon does not
+    overwrite it at launch — the GPU, screen, DPR and Chrome version all are.
+    """
+
+    # ISO-3166 alpha-2 from ``GET /v1/persona/constraints``. Pins language,
+    # timezone and speech voices together.
+    country: Optional[str] = None
+
+
+class Preset(_ReadModel):
+    id: str
+    name: str
+    constraints: PresetConstraints = PresetConstraints()
+    config: PresetConfig = PresetConfig()
+    created_at: int
+
+
+class PersonaConstraintOptions(_ReadModel):
+    """``GET /v1/persona/constraints`` — the values a preset may constrain to."""
+
+    countries: list[str] = []
+
+
+class Proxy(_ReadModel):
+    """Proxy — credentials are write-only on the daemon; never returned."""
+
+    id: str
+    kind: ProxyKind
+    host: str
+    port: int
+    rotation: Rotation
+    last_exit_ip: Optional[str] = None
+    last_country: Optional[str] = None
+    last_check_at: Optional[int] = None
+    healthy: Optional[bool] = None
+    created_at: int
+
+
+# ── Request payloads ──────────────────────────────────────────────────────────
+
+
+class CreateProfileBody(_WriteModel):
+    name: str
+    seed: Optional[str] = None
+    host_mode: Optional[HostMode] = None
+    geo_mode: Optional[GeoMode] = None
+    expected_country: Optional[str] = None
+    group_id: Optional[str] = None
+    proxy_id: Optional[str] = None
+
+
+class UpdateProfileBody(_WriteModel):
+    # host_mode and seed are fixed at create time (C4/C5): a DIFFERING host_mode is
+    # refused with 400, an unchanged echo is accepted. A tier change needs recreate.
+    name: Optional[str] = None
+    geo_mode: Optional[GeoMode] = None
+    expected_country: Optional[str] = None
+    group_id: Optional[str] = None
+    proxy_id: Optional[str] = None
+
+
+class StartProfileBody(_WriteModel):
+    headless: Optional[bool] = None
+
+
+class StartProfileResult(_ReadModel):
+    """`POST /v1/profiles/:id/start` response (server `StartResp`)."""
+
+    profile_id: str
+    cdp_ws: str
+    # Parsed by the daemon out of `cdp_ws`; null when the URL carries no port.
+    debug_port: Optional[int] = None
+    headless: bool
+    pid: Optional[int] = None
+    started_at: int
+
+
+class StopProfileResult(_ReadModel):
+    stopped: bool
+
+
+class BulkCreateBody(_WriteModel):
+    preset_id: str
+    count: int
+    #: Base name for the batch; the daemon appends an index per profile.
+    name_prefix: Optional[str] = None
+    #: Drop the whole batch into this group at create time.
+    group_id: Optional[str] = None
+
+
+class BulkIdsBody(_WriteModel):
+    ids: list[str]
+
+
+class BulkAssignProxyBody(_WriteModel):
+    ids: list[str]
+    proxy_id: str
+
+
+class CreateProxyBody(_WriteModel):
+    kind: ProxyKind
+    host: str
+    port: int
+    username: Optional[str] = None
+    password: Optional[str] = None
+    rotation: Optional[Rotation] = None
+
+
+class UpdateProxyBody(_WriteModel):
+    kind: Optional[ProxyKind] = None
+    host: Optional[str] = None
+    port: Optional[int] = None
+    username: Optional[str] = None
+    password: Optional[str] = None
+    rotation: Optional[Rotation] = None
+
+
+class ProxyCheckResult(_ReadModel):
+    """Result of ``POST /v1/proxies/:id/check`` (health + geo + JA4↔JA4T verdict)."""
+
+    healthy: bool
+    exit_ip: Optional[str] = None
+    country: Optional[str] = None
+    #: Carrier/mobile-exit hint (a mobile exit is the best case for anti-detect).
+    is_mobile: Optional[bool] = None
+    ja4: Optional[str] = None
+    ja4t: Optional[str] = None
+    ja4t_mismatch: Optional[bool] = None
+    warnings: Optional[list[str]] = None
+    checked_at: Optional[int] = None
+    #: Round-trip RTT — ``None`` on an unreachable exit (a timeout is not a latency).
+    latency_ms: Optional[int] = None
+
+
+class CheckProxyConfigBody(_WriteModel):
+    """Body of ``POST /v1/proxies/check`` — probe a config that is NOT persisted.
+
+    Edit-mode: pass ``id`` of an existing proxy and omit ``username``/``password``
+    to probe with its stored (write-only) credentials. A proxy whose credentials
+    cannot be decrypted fails closed instead of probing unauthenticated.
+    """
+
+    kind: ProxyKind
+    host: str
+    port: int
+    username: Optional[str] = None
+    password: Optional[str] = None
+    rotation: Optional[Rotation] = None
+    #: Existing proxy id — enables the stored-credential fallback.
+    id: Optional[str] = None
+
+
+class Extension(_ReadModel):
+    """One package in the library, keyed by id AND version.
+
+    The library stocks several versions of the same extension; each profile draws
+    one from its own seed, because a fleet in lockstep on one version is itself
+    unusual (real auto-update rolls out gradually).
+    """
+
+    #: Canonical Web-Store id, derived from the package's own key. Repeats across versions.
+    id: str
+    name: str
+    version: str
+    #: Base64 DER public key lifted from the CRX header.
+    public_key: str
+    #: Unpacked library directory (a profile launches from its own copy). Derived
+    #: by the daemon from its data dir rather than stored, so a moved data dir does
+    #: not leave every row pointing at nothing.
+    dir: str
+    #: SHA-256 of the unpacked tree — names the CONTENT of this version.
+    content_hash: str = ""
+    added_at: int
+
+
+class ExtensionPolicy(_ReadModel):
+    """How a profile's extension set reaches the browser.
+
+    ``engine_switches`` is what the launch actually emits. ``id_model`` is
+    ``"canonical"``: the id comes from the package's key and is the same for every
+    profile — deliberately, since that is the id millions of real users report.
+    Only the FILES are per-profile (``delivery = "per_profile_copy"``).
+    """
+
+    id_model: str
+    delivery: str
+    engine_switches: list[str]
+
+
+class ExtensionAdvice(_ReadModel):
+    """One finding about a profile's extension set."""
+
+    #: ``warn`` — a launch is never blocked by an extension.
+    level: str
+    message: str
+
+
+class ExtensionsResult(_ReadModel):
+    """Response of every ``/v1/profiles/:id/extensions`` call: the set + the policy."""
+
+    profile_id: str
+    #: Assigned library ids, as an idempotent set.
+    extensions: list[str]
+    #: The set this profile actually loads — ONE version per extension, drawn from the
+    #: profile's seed. Shorter than ``extensions`` when an id no longer resolves.
+    packages: list[Extension]
+    policy: ExtensionPolicy
+    #: What is worth knowing about THIS set, judged by the daemon with the same
+    #: function the launch gate uses. Empty for an unremarkable set — including an
+    #: empty one. Never recompute it: a second opinion could contradict the gate.
+    advice: list[ExtensionAdvice] = []
+
+
+class CredentialMeta(_ReadModel):
+    """One stored platform login — everything about it EXCEPT the secrets.
+
+    The username is returned because it is the account's display identity, not a
+    secret on any platform; without it two stored accounts are indistinguishable.
+    The password and the two-factor key never travel here — only through
+    :meth:`Client.reveal_credential`, which needs the vault password.
+    """
+
+    platform: str
+    username: str | None = None
+    login_url: str | None = None
+    has_password: bool
+    has_totp: bool
+    #: Typed into a sign-up form but never confirmed — the account may not exist.
+    pending: bool = False
+    created_at: int
+    updated_at: int
+    last_used_at: int | None = None
+    #: The stored blobs no longer open with the current master key. The row stays
+    #: listable and deletable; every USE of it fails closed.
+    secrets_unreadable: bool = False
+
+
+class RevealedCredential(_ReadModel):
+    """The plaintext of one login. The only shape in this SDK that carries one."""
+
+    platform: str
+    username: str | None = None
+    password: str | None = None
+    totp_secret: str | None = None
+
+
+class CredentialBundle(_ReadModel):
+    """A passphrase-sealed backup of one profile's logins."""
+
+    bundle: str
+    count: int
+
+
+class CredentialImportResult(_ReadModel):
+    """What a restore put back."""
+
+    #: Boolean, like the session import — the number is in ``count``.
+    imported: bool
+    count: int
+    platforms: list[str]
+
+
+class VaultStatus(_ReadModel):
+    """Whether a vault password has been set on this daemon."""
+
+    configured: bool
+
+
+class AuditDetectorReport(_ReadModel):
+    """One detector's outcome. ``skip`` means the page could not be evaluated —
+    NOT that it passed."""
+
+    id: str
+    verdict: str
+    detail: str
+
+
+class AuditReport(_ReadModel):
+    """What the detector sites saw on one launch."""
+
+    schema_version: int
+    timestamp: str
+    overall: str
+    detectors: list[AuditDetectorReport]
+
+
+class AuditStatus(_ReadModel):
+    """State of a profile's detector audit, plus the last stored report."""
+
+    profile_id: str
+    #: ``idle`` (never run since the daemon started), ``running`` or ``finished``.
+    state: str
+    started_at: Optional[int] = None
+    finished_at: Optional[int] = None
+    #: Why the RUN failed — distinct from a detector's own ``skip``.
+    error: Optional[str] = None
+    report: Optional[AuditReport] = None
+
+
+class CreateGroupBody(_WriteModel):
+    name: str
+
+
+class UpdateGroupBody(_WriteModel):
+    name: Optional[str] = None
+
+
+class CreatePresetBody(_WriteModel):
+    name: str
+    constraints: Optional[PresetConstraints] = None
+    config: Optional[PresetConfig] = None
+
+
+class UpdatePresetBody(_WriteModel):
+    """Partial update; an omitted half is left as stored."""
+
+    name: Optional[str] = None
+    constraints: Optional[PresetConstraints] = None
+    config: Optional[PresetConfig] = None
+
+
+class SessionExportBody(_WriteModel):
+    password: str
+    kinds: Optional[list[SessionKind]] = None
+
+
+class SessionExportResult(_ReadModel):
+    bundle: str
+    harvested: Optional[bool] = None
+    """Whether the cookies came out of the RUNNING browser for this export.
+
+    ``False`` means the bundle carries only what was stored earlier, which for a
+    stopped profile is all there can be: a browser holds its jar in its own
+    process. Export while the profile runs for a current session.
+    """
+    note: Optional[str] = None
+    """Why the bundle is thinner than it could be, when it is."""
+
+
+class SessionImportBody(_WriteModel):
+    password: str
+    bundle: str
+
+
+ProbeState = Literal["measured", "unsupported", "unavailable"]
+"""Availability of one probed figure: really measured, not supported on this
+host/HW, or temporarily unavailable (probe error / not yet sampled)."""
+
+MetricsSource = Literal["live", "derived"]
+"""`live` = served by the daemon's sampler; `derived` = client fallback (an old
+daemon without the endpoint)."""
+
+
+class MetricsAvailability(_ReadModel):
+    ram: ProbeState
+    cpu: ProbeState
+    gpu: ProbeState
+    vram: ProbeState
+    per_profile: ProbeState
+
+
+class ProfileResource(_ReadModel):
+    profile_id: str
+    name: str
+    pid: Optional[int] = None
+    ram_mb: Optional[int] = None
+    cpu_pct: Optional[float] = None
+    vram_mb: Optional[int] = None
+
+
+class Metrics(_ReadModel):
+    running: int
+    capacity_max_concurrent: int
+    ram_used_mb: Optional[int] = None
+    # Never null on the wire: Rust serializes a bare `u64` (`metrics/mod.rs`).
+    # The Optional both mirrors used to carry was recalled, not read.
+    ram_budget_mb: int
+    vram_used_mb: Optional[int] = None
+    vram_budget_mb: Optional[int] = None
+    cpu_pct: Optional[float] = None
+    gpu_pct: Optional[float] = None
+    # Additive: distinguish a real value from "not on this host" vs "measuring".
+    source: Optional[MetricsSource] = None
+    sampled_at: Optional[int] = None
+    availability: Optional[MetricsAvailability] = None
+    profiles: list[ProfileResource] = Field(default_factory=list)
+    #: Launchable host memory (MiB) — the capacity gate's own reading. "How many
+    #: more browsers fit" derives from THIS; ``ram_budget_mb − ram_used_mb`` does
+    #: not subtract (used is host-wide, the budget is the daemon's own ceiling).
+    ram_available_mb: Optional[int] = None
+
+
+# ── Trusted input (G8, AC-API-003) ───────────────────────────────────────────
+
+InputAction = Literal["move", "click", "type", "scroll"]
+
+
+# ── Events (SSE `/v1/events`, WS `/v1/ws`) — tagged union on `type` ───────────
+
+
+class ProfileStateChanged(_ReadModel):
+    type: Literal["profile_state_changed"]
+    profile_id: str
+    from_: RuntimeState = Field(alias="from")
+    to: RuntimeState
+    at: int
+
+
+class ProfileStarted(_ReadModel):
+    type: Literal["profile_started"]
+    profile_id: str
+    cdp_ws: str
+    headless: bool
+    at: int
+
+
+class ProfileStopped(_ReadModel):
+    type: Literal["profile_stopped"]
+    profile_id: str
+    at: int
+
+
+class ProfileCrashed(_ReadModel):
+    type: Literal["profile_crashed"]
+    profile_id: str
+    reason: str
+    at: int
+
+
+class PreflightFailed(_ReadModel):
+    type: Literal["preflight_failed"]
+    profile_id: str
+    detail: str
+    at: int
+
+
+class ProxyChecked(_ReadModel):
+    type: Literal["proxy_checked"]
+    proxy_id: str
+    healthy: bool
+    country: Optional[str] = None
+    at: int
+
+
+class CapacityRejected(_ReadModel):
+    type: Literal["capacity_rejected"]
+    profile_id: str
+    at: int
+
+
+# ── Agent runs + activity (payloads the live events carry) ───────────────────
+
+
+class StepTarget(_ReadModel):
+    """The element a step acted on, as it can still be recognised later."""
+
+    role: str
+    name: str
+
+
+class RunStep(_ReadModel):
+    """One tool call, as the operator gets to read it back.
+
+    Carries every field the daemon stored. The image is the one exception:
+    :attr:`shot_path` is a reference and the picture is fetched separately.
+    """
+
+    seq: int
+    at: int
+    duration_ms: Optional[int] = None
+    kind: StepKind
+    tool: Optional[str] = None
+    target: Optional[StepTarget] = None
+    summary: Optional[str] = None
+    redacted: bool = False
+    url: Optional[str] = None
+    shot_path: Optional[str] = None
+    #: What the call produced, in one line — "3 blocks, 122 characters",
+    #: "no visible change · 14 elements". ``summary`` says what the agent asked
+    #: for, this says what came back. ``None`` on a step recorded before this
+    #: field existed.
+    result: Optional[str] = None
+    error: Optional[str] = None
+
+
+class ProfileActivity(_ReadModel):
+    """What one running profile is showing."""
+
+    profile_id: str
+    profile_name: str
+    url: str
+    title: str
+    actor: RunActor
+    since: int
+    #: The browser did not answer the last sweep; this is the last known value.
+    stale: bool = False
+
+
+class RunStarted(_ReadModel):
+    type: Literal["run_started"]
+    run_id: str
+    profile_id: str
+    actor: RunActor
+    goal: str
+    at: int
+
+
+class RunStepEvent(_ReadModel):
+    """One tool call was appended to a run's trail — the whole stored step."""
+
+    type: Literal["run_step"]
+    run_id: str
+    profile_id: str
+    step: RunStep
+    at: int
+
+
+class RunFinished(_ReadModel):
+    type: Literal["run_finished"]
+    run_id: str
+    profile_id: str
+    outcome: RunOutcome
+    at: int
+
+
+class ProfileActivityChanged(_ReadModel):
+    """A running profile's row appeared, or something about it is different."""
+
+    type: Literal["profile_activity_changed"]
+    activity: ProfileActivity
+    at: int
+
+
+class ProfileActivityGone(_ReadModel):
+    type: Literal["profile_activity_gone"]
+    profile_id: str
+    at: int
+
+
+class Resync(_ReadModel):
+    """Frames were lost; re-read rather than carry on.
+
+    Raised when the daemon notices this connection fell behind the bus;
+    ``dropped`` counts what it skipped.
+    """
+
+    type: Literal["resync"]
+    dropped: int
+    at: int
+
+
+Event = Annotated[
+    Union[
+        ProfileStateChanged,
+        ProfileStarted,
+        ProfileStopped,
+        ProfileCrashed,
+        PreflightFailed,
+        ProxyChecked,
+        CapacityRejected,
+        RunStarted,
+        RunStepEvent,
+        RunFinished,
+        ProfileActivityChanged,
+        ProfileActivityGone,
+        Resync,
+    ],
+    Field(discriminator="type"),
+]
+
+EVENT_ADAPTER: TypeAdapter[Event] = TypeAdapter(Event)
+"""Validates a wire payload into the typed :data:`Event` union."""
+
+
+__all__ = [
+    # enums
+    "RuntimeState", "RUNTIME_STATES", "HostMode", "HOST_MODES",
+    "GeoMode", "GEO_MODES", "ProxyKind", "PROXY_KINDS",
+    "Rotation", "ROTATIONS", "SessionKind", "OsFamily", "InputAction",
+    "RunActor", "RunOutcome", "StepKind",
+    # persona
+    "Screen", "Locale", "WebGl", "WebGpu", "AudioProps", "SpeechVoice",
+    "GpuPersona", "Brand", "ClientHints", "PermissionDefaults", "MediaDevice",
+    "PersonaMisc", "Persona",
+    # resources
+    "Profile", "Group", "Preset", "Proxy",
+    # payloads
+    "CreateProfileBody", "UpdateProfileBody", "StartProfileBody",
+    "StartProfileResult", "StopProfileResult", "BulkCreateBody", "BulkIdsBody",
+    "BulkAssignProxyBody", "CreateProxyBody", "UpdateProxyBody",
+    "ProxyCheckResult", "CreateGroupBody", "UpdateGroupBody", "SessionExportBody",
+    "SessionExportResult", "SessionImportBody", "Metrics",
+    # runs + activity
+    "StepTarget", "RunStep", "ProfileActivity",
+    # events
+    "ProfileStateChanged", "ProfileStarted", "ProfileStopped", "ProfileCrashed",
+    "PreflightFailed", "ProxyChecked", "CapacityRejected",
+    "RunStarted", "RunStepEvent", "RunFinished",
+    "ProfileActivityChanged", "ProfileActivityGone", "Resync", "Event",
+    "EVENT_ADAPTER",
+]