aetherius 0.2.0__py3-none-any.whl

aetherius/recorder/gesture_recorder.py

@@ -0,0 +1,193 @@
+"""Gesture recorder: capture real human mouse traces to extend the stealth gesture library.
+
+The stealth mouse humanizer replays gestures from a source-agnostic library (:mod:`aetherius.stealth
+.gestures.library`); the package ships a synthetic seed so it works from day one. This recorder adds
+*real* traces in the exact same neutral format: a gesture is a list of ``[dx, dy, t]`` offsets from
+its start. The browser wiring captures raw pointer samples; the pure functions here segment them into
+aimed gestures (the move leading up to each click) and merge them into the library file.
+
+Segmentation is pure and unit-tested without a browser; only :func:`record_gestures` needs Playwright.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import threading
+import urllib.parse
+from pathlib import Path
+from typing import Any, Callable
+
+from ..stealth.gestures import library as _library
+from ..stealth.gestures.library import Point
+from ._gesture_js import GESTURE_RECORDER_JS
+from ._playwright import import_playwright, pump
+
+# Reuse the library's own path as the single source of truth for where traces live.
+_DEFAULT_LIBRARY_FILE = _library._DATA_FILE
+
+# A new gesture starts after a pause this long (s); a gesture must have at least this many points and
+# span at least this many pixels, to drop idle jitter and accidental micro-moves.
+_PAUSE_S = 0.35
+_MIN_POINTS = 5
+_MIN_DISTANCE_PX = 12.0
+
+_INSTRUCTION_HTML = """<!doctype html><html><head><meta charset="utf-8">
+<style>
+  html,body{height:100%;margin:0;background:#0f0b1e;color:#e7e2f3;
+    font:16px/1.6 system-ui,sans-serif;display:flex;align-items:center;justify-content:center}
+  .card{max-width:32rem;text-align:center;padding:2rem}
+  h1{font-weight:600;letter-spacing:.02em}
+  b{color:#e0b64d}
+</style></head><body><div class="card">
+  <h1>Gesture recorder</h1>
+  <p>Move the mouse naturally across this page and <b>click</b> in different spots, as if using a
+  real site. Each move up to a click is captured as one gesture.</p>
+  <p>When you have made a few dozen moves, <b>close this window</b> to save.</p>
+</div></body></html>"""
+
+
+def _instruction_url() -> str:
+    return "data:text/html," + urllib.parse.quote(_INSTRUCTION_HTML)
+
+
+def _to_relative(segment: list[Point]) -> list[Point]:
+    """Rebase an absolute ``[x, y, t]`` segment onto offsets from its first point."""
+    x0, y0, t0 = segment[0]
+    return [(round(x - x0, 2), round(y - y0, 2), round(t - t0, 4)) for x, y, t in segment]
+
+
+def _span(relative: list[Point]) -> float:
+    """Total displacement of a rebased gesture (distance of its last offset)."""
+    end_x, end_y, _ = relative[-1]
+    return math.hypot(end_x, end_y)
+
+
+def segment_gestures(
+    samples: list[Point],
+    clicks: list[float],
+    *,
+    pause_s: float = _PAUSE_S,
+    min_points: int = _MIN_POINTS,
+    min_distance_px: float = _MIN_DISTANCE_PX,
+) -> list[list[Point]]:
+    """Split raw absolute pointer samples into aimed gestures in the neutral library format.
+
+    A gesture is the run of samples leading up to a click (the aimed move), also broken on any pause
+    longer than *pause_s*. Degenerate runs (too few points or too short a path) are discarded.
+    """
+    points = sorted(samples, key=lambda s: s[2])
+    click_times = sorted(clicks)
+    segments: list[list[Point]] = []
+    current: list[Point] = []
+    click_index = 0
+
+    for x, y, t in points:
+        if current and (t - current[-1][2]) > pause_s:
+            segments.append(current)
+            current = []
+        current.append((x, y, t))
+        while click_index < len(click_times) and click_times[click_index] <= t + 1e-6:
+            # Close only if the click belongs to this run; a click stranded in a pause gap before
+            # the current segment started belonged to an already-closed gesture, so just skip it.
+            if current and click_times[click_index] >= current[0][2] - 1e-6:
+                segments.append(current)
+                current = []
+            click_index += 1
+    if current:
+        segments.append(current)
+
+    gestures: list[list[Point]] = []
+    for segment in segments:
+        if len(segment) < min_points:
+            continue
+        relative = _to_relative(segment)
+        if _span(relative) >= min_distance_px:
+            gestures.append(relative)
+    return gestures
+
+
+def merge_into_library(path: Path, gestures: list[list[Point]]) -> int:
+    """Append *gestures* to the library file at *path* without dropping what is already there.
+
+    Existing traces (synthetic seed or earlier recordings) are preserved; ``meta`` is updated to mark
+    that the library now contains recorded human traces. Returns the number of gestures added.
+    """
+    existing: list[Any] = []
+    if path.exists():
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            existing = list(data.get("gestures", []))
+        except (ValueError, OSError):
+            existing = []
+
+    combined = existing + [[list(point) for point in gesture] for gesture in gestures]
+    payload = {
+        "meta": {
+            "source": "recorded-human",
+            "generator": "aetherius.recorder.gesture_recorder",
+            "count": len(combined),
+            "note": "Real captured traces; may include prior seed/recorded gestures (same format).",
+        },
+        "gestures": combined,
+    }
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=1), encoding="utf-8")
+    return len(gestures)
+
+
+def record_gestures(
+    *,
+    out_path: Path | str | None = None,
+    on_event: Callable[[int], None] | None = None,
+    stop_event: threading.Event | None = None,
+) -> tuple[Path, int]:
+    """Capture mouse traces in a live browser, segment them, and merge them into the library.
+
+    Returns the library path written and the number of gestures added. Stops when the window closes
+    or *stop_event* is set.
+    """
+    samples: list[Point] = []
+    clicks: list[float] = []
+
+    def on_binding(_source: dict[str, Any], payload: str) -> None:
+        try:
+            data = json.loads(payload)
+        except (TypeError, ValueError):
+            return
+        for move in data.get("moves", []):
+            samples.append((float(move[0]), float(move[1]), float(move[2])))
+        if data.get("click") is not None:
+            clicks.append(float(data["click"]))
+        if on_event is not None:
+            on_event(len(samples))
+
+    sync_playwright = import_playwright()
+    pw = sync_playwright().start()
+    browser = context = None
+    disconnected = threading.Event()
+    try:
+        browser = pw.chromium.launch(headless=False)
+        browser.on("disconnected", lambda: disconnected.set())
+        context = browser.new_context()
+        context.expose_binding("__aetherius_gesture", on_binding)
+        context.add_init_script(GESTURE_RECORDER_JS)
+        page = context.new_page()
+        page.goto(_instruction_url())
+        pump(context, disconnected, stop_event)
+    finally:
+        for closer in (context, browser):
+            if closer is not None:
+                try:
+                    closer.close()
+                except Exception:
+                    pass
+        try:
+            pw.stop()
+        except Exception:
+            pass
+
+    gestures = segment_gestures(samples, clicks)
+    target = Path(out_path) if out_path is not None else _DEFAULT_LIBRARY_FILE
+    added = merge_into_library(target, gestures)
+    return target, added

aetherius/recorder/selector_synth.py

@@ -0,0 +1,83 @@
+"""Robust selector synthesis: prefer data-testid, aria and text before fragile css paths.
+
+The in-page capture script (``_capture_js.py``) does the DOM work: for a target element it forms
+candidate selector strings (escaping with the browser's ``CSS.escape``) and, crucially, tests each
+for *uniqueness* on the live page (``querySelectorAll(sel).length === 1``). This module owns the
+policy that is worth testing on its own: given those candidates, which one to keep, in what order,
+and when to fall back to a positional css path. Keeping the ranking here — pure, browser-free — means
+it runs in the base test suite while the DOM facts it consumes are produced by the browser.
+
+A selector survives a page far better when it is anchored on intent (a test id, a name, a label,
+visible text) than on a brittle ``div > div:nth-child(3) > span`` chain, so intent-based strategies
+are ranked first and the positional path is only ever the last resort.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Strategy names, in the order we trust them. First unique candidate wins; css_path is the fallback.
+# data-testid/-test/-cy/-qa are added by developers precisely as stable hooks, so they rank highest;
+# a positional css path is the most fragile and ranks below everything intent-based.
+_PRIORITY: tuple[str, ...] = ("testid", "id", "href", "name", "aria", "role", "class", "text")
+
+
+@dataclass(frozen=True, slots=True)
+class Candidate:
+    """One selector the page offers for an element, tagged with its strategy and uniqueness.
+
+    ``unique`` is measured in-page against the live DOM; a non-unique candidate is skipped because a
+    Blueprint action would hit Playwright's strict mode on an ambiguous target.
+    """
+
+    strategy: str
+    selector: str
+    selector_type: str  # "css" | "text" | "xpath"
+    unique: bool
+
+
+@dataclass(frozen=True, slots=True)
+class ElementDescriptor:
+    """Everything the capture script observed about a target element.
+
+    ``candidates`` feed selector synthesis; ``name``/``field_type``/``autocomplete`` feed the
+    credential heuristic in the blueprint recorder. One descriptor, two consumers, no duplication.
+    """
+
+    tag: str
+    css_path: str
+    candidates: tuple[Candidate, ...] = ()
+    text: str | None = None
+    name: str | None = None
+    field_type: str | None = None
+    autocomplete: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class SelectorChoice:
+    """The chosen selector and how to interpret it (``css`` is the Blueprint default)."""
+
+    selector: str
+    selector_type: str = "css"
+    strategy: str = "css_path"
+
+
+def synthesize(descriptor: ElementDescriptor) -> SelectorChoice:
+    """Pick the most robust selector for *descriptor*.
+
+    Walks the trusted strategies in order and returns the first candidate that is unique on the
+    page; if none qualifies, falls back to the positional css path (or the bare tag if even that is
+    missing, so a caller always gets something usable rather than an empty selector).
+    """
+    by_strategy: dict[str, Candidate] = {}
+    for candidate in descriptor.candidates:
+        # Keep the first candidate seen per strategy: the capture script emits them best-first.
+        by_strategy.setdefault(candidate.strategy, candidate)
+
+    for strategy in _PRIORITY:
+        chosen = by_strategy.get(strategy)
+        if chosen is not None and chosen.unique:
+            return SelectorChoice(chosen.selector, chosen.selector_type, strategy)
+
+    fallback = descriptor.css_path or descriptor.tag
+    return SelectorChoice(fallback, "css", "css_path")

aetherius/recorder/session.py

@@ -0,0 +1,101 @@
+"""Generic recording session: owns the live browser, driven by an Act-specific backend.
+
+This is the shared shell every recorder reuses — launch, context, page, the synchronous pump, and the
+seams a backend needs (expose a binding, hook new pages, stream a description, end the session). It
+holds no Act logic: what to inject and how to interpret captures is the backend's job (:mod:`.base`).
+Synchronous throughout (runs on the caller's thread); Playwright is imported lazily.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any, Callable
+
+from ._playwright import import_playwright, pump
+from .base import RecorderBackend, RecordingResult
+
+# A backend streams human-readable descriptions of what it captures; the Console/CLI render them.
+NotifyCallback = Callable[[str], None]
+PageHook = Callable[[Any], None]
+
+
+class RecordingSession:
+    """Owns a visible browser for a demonstration and returns the backend's RecordingResult.
+
+    Stops when the user closes the window, when ``stop_event`` is set (the Console's Stop button), or
+    when the backend calls :meth:`finish` (e.g. the overlay's Finish button).
+    """
+
+    def __init__(
+        self,
+        start_url: str,
+        backend: RecorderBackend,
+        *,
+        on_event: NotifyCallback | None = None,
+        stop_event: threading.Event | None = None,
+    ) -> None:
+        self._start_url = start_url
+        self._backend = backend
+        self._on_event = on_event
+        self._stop = stop_event
+        self._done = threading.Event()
+        self._context: Any = None
+        self._page_hooks: list[PageHook] = []
+
+    def record(self) -> RecordingResult:
+        """Launch the browser, let the backend capture until the session ends, return its result."""
+        sync_playwright = import_playwright()
+        pw = sync_playwright().start()
+        browser = None
+        disconnected = threading.Event()
+        try:
+            browser = pw.chromium.launch(headless=False)
+            browser.on("disconnected", lambda: disconnected.set())
+            self._context = browser.new_context()
+            for script in self._backend.init_scripts():
+                self._context.add_init_script(script)
+            self._backend.attach(
+                self
+            )  # backend registers bindings + page hooks now that ctx exists
+            self._context.on("page", self._wire_page)
+
+            page = self._context.new_page()
+            self._wire_page(page)
+            page.goto(self._start_url)
+
+            pump(self._context, disconnected, self._stop, self._done)
+        finally:
+            for closer in (self._context, browser):
+                if closer is not None:
+                    try:
+                        closer.close()
+                    except Exception:  # teardown must never mask what was already captured
+                        pass
+            try:
+                pw.stop()
+            except Exception:
+                pass
+            self._context = None
+        return self._backend.result()
+
+    # ── backend-facing seams ──────────────────────────────────────────────────
+    def expose(self, name: str, handler: Callable[..., Any]) -> None:
+        """Expose a page binding ``window[name]`` that calls *handler* (context-wide, all pages)."""
+        self._context.expose_binding(name, handler)
+
+    def on_new_page(self, hook: PageHook) -> None:
+        """Register *hook* to run on the first page and any later popup/tab."""
+        self._page_hooks.append(hook)
+
+    def notify(self, description: str) -> None:
+        """Stream one human-readable description of a captured item (never raises)."""
+        if self._on_event is not None:
+            self._on_event(description)
+
+    def finish(self) -> None:
+        """End the session from the backend (e.g. the overlay Finish control message)."""
+        self._done.set()
+
+    def _wire_page(self, page: Any) -> None:
+        for hook in self._page_hooks:
+            hook(page)

aetherius/recorder/vector_backend.py

@@ -0,0 +1,158 @@
+"""Vector recorder backend: turn captured API calls into an ``http.request`` Blueprint (Act I).
+
+The in-page script (:mod:`._vector_js`) observes network calls and lets the user pick a request and
+the JSON fields to extract; this backend transforms those picks into ``http.request`` steps with
+JSONPath extraction (the shape [`acts/vector/driver.py`] runs). Picks on the same request coalesce
+into one step. Auth-bearing headers become ``{{ secrets.x }}`` — never stored literally — the network
+analogue of the DOM recorder's credentials→secrets.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from urllib.parse import unquote_plus
+
+from ._names import ident, unique
+from ._vector_js import VECTOR_JS
+from .base import RecordingResult, register_backend
+from .session import RecordingSession
+
+# Header names (lowercased) that carry credentials: kept as secret placeholders, never in the file.
+_SENSITIVE_HEADERS = frozenset(
+    {"authorization", "cookie", "x-api-key", "api-key", "x-auth-token", "x-csrf-token"}
+)
+
+
+def _parse_body(body: str | None) -> tuple[str | None, Any]:
+    """Classify a request body: JSON object/array, url-encoded form, or unknown (omitted)."""
+    if not body:
+        return None, None
+    text = body.strip()
+    if text[:1] in "{[":
+        try:
+            return "json", json.loads(text)
+        except ValueError:
+            pass
+    if "=" in text:
+        form: dict[str, str] = {}
+        for pair in text.split("&"):
+            key, _, value = pair.partition("=")
+            form[unquote_plus(key)] = unquote_plus(value)
+        return "form", form
+    return None, None
+
+
+def _clean_headers(raw: dict[str, Any], secrets: list[str]) -> dict[str, str]:
+    """Keep Content-Type; turn auth headers into secret placeholders; drop browser noise."""
+    clean: dict[str, str] = {}
+    for name, value in raw.items():
+        lowered = str(name).lower()
+        if lowered in _SENSITIVE_HEADERS:
+            secret = unique(ident(lowered.replace("-", "_"), fallback="token"), set(secrets))
+            secrets.append(secret)
+            clean[name] = f"{{{{ secrets.{secret} }}}}"
+        elif lowered == "content-type":
+            clean[name] = str(value)
+    return clean
+
+
+def _build_request_step(
+    request_id: str, request: dict[str, Any], secrets: list[str]
+) -> dict[str, Any]:
+    """Reproduce a captured request as an http.request step (method/url/headers/body/expect)."""
+    step: dict[str, Any] = {
+        "id": request_id,
+        "action": "http.request",
+        "method": str(request.get("method", "GET")),
+        "url": str(request.get("url", "")),
+    }
+    headers = _clean_headers(request.get("headers") or {}, secrets)
+    if headers:
+        step["headers"] = headers
+    body_kind, body_value = _parse_body(request.get("body"))
+    if body_kind == "json":
+        step["json"] = body_value
+    elif body_kind == "form":
+        step["form"] = body_value
+    step["expect"] = {"status": int(request.get("status") or 200)}
+    return step
+
+
+def _extract_spec(extract: dict[str, Any]) -> dict[str, Any]:
+    """One extract entry: JSONPath, plus a fields map for records."""
+    spec: dict[str, Any] = {"from": "json", "path": str(extract.get("path", "$"))}
+    fields = extract.get("fields")
+    if fields:
+        spec["fields"] = {str(k): str(v) for k, v in fields.items()}
+    return spec
+
+
+def transform(events: list[dict[str, Any]]) -> RecordingResult:
+    """Turn captured ``http_request`` picks into http.request steps, secrets and outputs."""
+    steps: list[dict[str, Any]] = []
+    secrets: list[str] = []
+    outputs: dict[str, Any] = {}
+    by_request: dict[tuple[str, str, str], dict[str, Any]] = {}
+    output_names: set[str] = set()
+    sequence = 0
+
+    for event in events:
+        request = event.get("request") or {}
+        extract = event.get("extract") or {}
+        key = (str(request.get("method")), str(request.get("url")), str(request.get("body")))
+        step = by_request.get(key)
+        if step is None:
+            sequence += 1
+            request_id = "req" if sequence == 1 else f"req_{sequence}"
+            step = _build_request_step(request_id, request, secrets)
+            by_request[key] = step
+            steps.append(step)
+        name = unique(ident(extract.get("name"), fallback="data"), output_names)
+        output_names.add(name)
+        step.setdefault("extract", {})[name] = _extract_spec(extract)
+        outputs[name] = f"{{{{ steps.{step['id']}.{name} }}}}"
+
+    return RecordingResult(steps=steps, secrets=secrets, inputs={}, outputs=outputs)
+
+
+def _describe(event: dict[str, Any]) -> str:
+    request = event.get("request") or {}
+    return f"{request.get('method', 'GET')} {request.get('url', '')}  -> {event.get('extract', {}).get('name', '?')}"
+
+
+class VectorRecorder:
+    """Records API calls (via a browser) into a ``vector`` Blueprint."""
+
+    act = "vector"
+
+    def __init__(self) -> None:
+        self._events: list[dict[str, Any]] = []
+        self._session: RecordingSession | None = None
+
+    def init_scripts(self) -> list[str]:
+        return [VECTOR_JS]
+
+    def attach(self, session: RecordingSession) -> None:
+        self._session = session
+        session.expose("__aetherius_capture", self._on_binding)
+
+    def result(self) -> RecordingResult:
+        return transform(self._events)
+
+    def _on_binding(self, _source: dict[str, Any], payload: str) -> None:
+        try:
+            data = json.loads(payload)
+        except (TypeError, ValueError):
+            return
+        if data.get("kind") == "finish":
+            if self._session is not None:
+                self._session.finish()
+            return
+        if data.get("kind") == "http_request":
+            self._events.append(data)
+            if self._session is not None:
+                self._session.notify(_describe(data))
+
+
+register_backend("vector", lambda **_: VectorRecorder())

aetherius/server/__init__.py

@@ -0,0 +1,12 @@
+"""The local daemon exposing Aetherius to any language over HTTP and WebSocket.
+
+Import stays light (FastAPI/uvicorn are base dependencies): ``create_app`` builds the ASGI app and
+``DaemonConfig`` carries its bind address and optional token. Nothing here pulls an Act extra.
+"""
+
+from __future__ import annotations
+
+from .app import create_app
+from .config import DaemonConfig
+
+__all__ = ["create_app", "DaemonConfig"]

aetherius/server/app.py

@@ -0,0 +1,37 @@
+"""FastAPI application factory wiring routes, config and the run manager."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import FastAPI
+
+from ..version import __version__
+from .config import DaemonConfig
+from .jobs import RunManager
+from .routes import blueprints, recorder, runs, stream
+
+
+def create_app(config: DaemonConfig | None = None) -> FastAPI:
+    """Build the daemon application. One :class:`RunManager` lives for the app's lifetime."""
+    config = config or DaemonConfig()
+
+    app = FastAPI(
+        title="Aetherius Daemon",
+        version=__version__,
+        summary="Local HTTP + WebSocket gateway to the Aetherius engine.",
+    )
+    app.state.config = config
+    app.state.manager = RunManager()
+
+    app.include_router(runs.router)
+    app.include_router(blueprints.router)
+    app.include_router(recorder.router)
+    app.include_router(stream.router)
+
+    @app.get("/health", tags=["meta"])
+    async def health() -> dict[str, Any]:
+        """Unauthenticated readiness probe used by the SDK and the Console when spawning the daemon."""
+        return {"status": "ok", "version": __version__}
+
+    return app

aetherius/server/config.py

@@ -0,0 +1,25 @@
+"""Daemon configuration (bind address, auth token, limits).
+
+Resolved from the environment (prefix ``AETHERIUS_DAEMON_``) with CLI overrides. The daemon binds to
+loopback by default: it exposes the engine to local processes only, never the network. A token is
+optional; when set, every HTTP request and WebSocket upgrade must present it as a bearer credential.
+"""
+
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class DaemonConfig(BaseSettings):
+    """Runtime configuration for the local daemon."""
+
+    model_config = SettingsConfigDict(env_prefix="AETHERIUS_DAEMON_", extra="ignore")
+
+    host: str = "127.0.0.1"
+    port: int = 8787
+    token: str | None = None
+
+    @property
+    def base_url(self) -> str:
+        """The HTTP address the daemon serves on."""
+        return f"http://{self.host}:{self.port}"

aetherius/server/deps.py

@@ -0,0 +1,50 @@
+"""Shared FastAPI dependencies: run-manager access and optional bearer authentication.
+
+The manager and config live on ``app.state`` (set by the application factory) so routers stay
+decoupled from construction. Authentication is a no-op unless a token is configured, in which case
+every ``/v1`` request must present it as ``Authorization: Bearer <token>``.
+"""
+
+from __future__ import annotations
+
+from fastapi import HTTPException, status
+from starlette.requests import HTTPConnection
+
+from .config import DaemonConfig
+from .jobs import RunManager
+
+
+def get_config(conn: HTTPConnection) -> DaemonConfig:
+    """Injected for both HTTP requests and WebSocket connections (their common base)."""
+    config = conn.app.state.config
+    assert isinstance(config, DaemonConfig)
+    return config
+
+
+def get_manager(conn: HTTPConnection) -> RunManager:
+    manager = conn.app.state.manager
+    assert isinstance(manager, RunManager)
+    return manager
+
+
+def require_auth(request: HTTPConnection) -> None:
+    """Reject the request when a token is configured and the bearer credential does not match."""
+    config = get_config(request)
+    if config.token is None:
+        return
+    if request.headers.get("Authorization") != f"Bearer {config.token}":
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or missing bearer token.",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+
+def websocket_authorized(config: DaemonConfig, header: str | None, query_token: str | None) -> bool:
+    """WebSocket auth: browsers cannot set headers on the upgrade, so a ``?token=`` query is also
+    accepted. Returns True when no token is configured."""
+    if config.token is None:
+        return True
+    if header == f"Bearer {config.token}":
+        return True
+    return query_token == config.token