aetherius 0.2.0__py3-none-any.whl

aetherius/acts/continuum/browser.py

@@ -0,0 +1,164 @@
+"""Playwright browser lifecycle: launch, contexts, headed and headless modes, debug options.
+
+Wraps the synchronous Playwright API. The engine (and therefore this driver) is synchronous, so the
+sync API is the natural fit: no event loop to juggle inside the driver. Playwright is imported
+lazily so ``import aetherius`` never pulls it in; a missing extra surfaces as a typed DependencyError.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any
+
+from ...core.errors import DependencyError
+from ...stealth.fingerprint.patch import FINGERPRINT_PATCH_JS
+from ...stealth.fingerprint.profile import get_profile
+from ...stealth.humanizer.input import HumanInput
+from ...stealth.policy import OFF, StealthPolicy
+from .debug_overlay import DEBUG_OVERLAY_JS
+from .human_actions import humanized_actions
+
+# Slow-motion delay (ms) inserted before every action when debug is on, so a human can follow along.
+_DEBUG_SLOW_MO_MS = 500
+# How long the window lingers after the last step (or a failure) in debug, so it does not just
+# flash and vanish before the final state can be read.
+_DEBUG_LINGER_MS = 2500
+
+
+def _import_playwright() -> Any:
+    """Import the sync Playwright entry point, or raise a typed, actionable error."""
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError as exc:  # extra [browser] not installed
+        raise DependencyError(
+            "Act II (Continuum) requires Playwright. Install it with:\n"
+            '    pip install "aetherius[browser]" && playwright install chromium',
+            extra="browser",
+        ) from exc
+    return sync_playwright
+
+
+class BrowserSession:
+    """Owns a Playwright instance, context and page for the duration of a run.
+
+    An ephemeral context by default; a *persistent* context (reused cookies/cache/history) when a
+    profile directory is supplied. ``debug`` opens a headed window with slow-motion so a step can be
+    watched. ``stealth`` is the assembled :class:`StealthPolicy`: an active one wears a fingerprint
+    profile (context options + init patches) and exposes a :class:`HumanInput` for the driver to
+    route interactive actions through.
+    """
+
+    def __init__(
+        self,
+        *,
+        debug: bool = False,
+        timeout_ms: int = 30_000,
+        profile_dir: Path | None = None,
+        stealth: StealthPolicy = OFF,
+    ) -> None:
+        self._debug = debug
+        self._timeout_ms = timeout_ms
+        self._profile_dir = profile_dir
+        self._stealth = stealth
+        self._pw: Any = None
+        self._browser: Any = None
+        self._context: Any = None
+        self._page: Any = None
+        self._human: HumanInput | None = None
+
+    def start(self) -> None:
+        """Launch the browser and open the working page. Idempotent per session."""
+        sync_playwright = _import_playwright()
+        self._pw = sync_playwright().start()
+
+        headless = not self._debug
+        slow_mo = self._slow_mo_ms()
+        context_options = self._context_options()
+
+        if self._profile_dir is not None:
+            self._context = self._pw.chromium.launch_persistent_context(
+                str(self._profile_dir),
+                headless=headless,
+                slow_mo=slow_mo,
+                **context_options,
+            )
+            pages = self._context.pages
+            self._page = pages[0] if pages else self._context.new_page()
+        else:
+            self._browser = self._pw.chromium.launch(headless=headless, slow_mo=slow_mo)
+            self._context = self._browser.new_context(**context_options)
+            self._page = self._context.new_page()
+
+        self._context.set_default_timeout(self._timeout_ms)
+        self._apply_stealth()
+
+        if self._debug:
+            # Visible cursor + red click ripple, re-installed on every navigation.
+            self._context.add_init_script(DEBUG_OVERLAY_JS)
+
+    def _slow_mo_ms(self) -> int:
+        """Debug slow-motion delay, but 0 whenever inputs are humanized.
+
+        slow_mo delays *every* Playwright op. That is fine for plain actions, but the humanizer
+        issues dozens of mouse.move/wheel calls per gesture and supplies its own realistic timing;
+        stacking slow_mo on top would shred each gesture into a slow, ugly stutter. So when discretion
+        humanizes inputs, the humanizer owns the pacing and slow_mo stays off, even in debug.
+        """
+        if self._debug and not humanized_actions(self._stealth):
+            return _DEBUG_SLOW_MO_MS
+        return 0
+
+    def _context_options(self) -> dict[str, Any]:
+        """Playwright context options for the active fingerprint profile (empty when none)."""
+        if self._stealth.fingerprint is None:
+            return {}
+        return get_profile(self._stealth.fingerprint).context_options()
+
+    def _apply_stealth(self) -> None:
+        """Inject the fingerprint patches and, if inputs are humanized, build the HumanInput facade."""
+        if not self._stealth.is_active:
+            return
+        self._context.add_init_script(FINGERPRINT_PATCH_JS)
+        if self._stealth.fingerprint is not None:
+            self._context.add_init_script(get_profile(self._stealth.fingerprint).init_script())
+        if humanized_actions(self._stealth):
+            self._human = HumanInput(self._page, self._stealth)
+
+    @property
+    def human(self) -> HumanInput | None:
+        """The humanized input facade when discretion humanizes inputs, else ``None``."""
+        return self._human
+
+    @property
+    def page(self) -> Any:
+        """The active Playwright page. Valid only between ``start`` and ``close``."""
+        if self._page is None:
+            raise RuntimeError("BrowserSession.page accessed before start() or after close().")
+        return self._page
+
+    def close(self) -> None:
+        """Tear down page, context, browser and Playwright, tolerating partial startup.
+
+        In debug mode, linger briefly first so the final page (or the point of failure) stays on
+        screen instead of vanishing the instant the run ends.
+        """
+        if self._debug and self._page is not None:
+            time.sleep(_DEBUG_LINGER_MS / 1000)
+
+        for closer in (
+            self._context,
+            self._browser,
+        ):
+            if closer is not None:
+                try:
+                    closer.close()
+                except Exception:  # teardown must never mask the original run error
+                    pass
+        if self._pw is not None:
+            try:
+                self._pw.stop()
+            except Exception:
+                pass
+        self._page = self._context = self._browser = self._pw = None
+        self._human = None

aetherius/acts/continuum/debug_overlay.py

@@ -0,0 +1,65 @@
+"""Client-side debug overlay: a visible cursor and a red click ripple.
+
+Injected via Playwright's ``add_init_script`` when ``options.debug`` is on, so it re-installs on
+every navigation. It listens to the real mouse events Playwright dispatches, so the cursor tracks
+where the bot moves and a red ripple marks every click. Purely a debug aid — never loaded otherwise,
+and unrelated to the discretion layer (which does the opposite: hide automation).
+"""
+
+from __future__ import annotations
+
+# A self-invoking script (add_init_script evaluates verbatim, it does not call a returned function).
+# Guarded by a window flag so repeated injection on the same document is a no-op.
+DEBUG_OVERLAY_JS = """
+(() => {
+  if (window.__aetheriusDebugOverlay) return;
+  window.__aetheriusDebugOverlay = true;
+  const install = () => {
+    const root = document.documentElement;
+    if (!root) return;
+    const style = document.createElement('style');
+    style.textContent = `
+      .__ae-cursor {
+        position: fixed; z-index: 2147483647; pointer-events: none;
+        width: 20px; height: 20px; margin: -10px 0 0 -10px; opacity: 0;
+        border: 2px solid rgba(224,48,48,0.95); border-radius: 50%;
+        background: rgba(224,48,48,0.20);
+        box-shadow: 0 0 8px 2px rgba(224,48,48,0.55);
+        transition: opacity 0.25s linear;
+      }
+      .__ae-ripple {
+        position: fixed; z-index: 2147483647; pointer-events: none;
+        width: 12px; height: 12px; margin: -6px 0 0 -6px; border-radius: 50%;
+        background: rgba(224,48,48,0.6);
+        animation: __ae-ripple-anim 0.65s ease-out forwards;
+      }
+      @keyframes __ae-ripple-anim {
+        0%   { transform: scale(1);  opacity: 0.9; }
+        100% { transform: scale(6);  opacity: 0;   }
+      }
+    `;
+    root.appendChild(style);
+    const cursor = document.createElement('div');
+    cursor.className = '__ae-cursor';
+    root.appendChild(cursor);
+    document.addEventListener('mousemove', (e) => {
+      cursor.style.opacity = '1';
+      cursor.style.left = e.clientX + 'px';
+      cursor.style.top = e.clientY + 'px';
+    }, true);
+    document.addEventListener('mousedown', (e) => {
+      const ripple = document.createElement('div');
+      ripple.className = '__ae-ripple';
+      ripple.style.left = e.clientX + 'px';
+      ripple.style.top = e.clientY + 'px';
+      root.appendChild(ripple);
+      setTimeout(() => ripple.remove(), 700);
+    }, true);
+  };
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', install);
+  } else {
+    install();
+  }
+})();
+"""

aetherius/acts/continuum/driver.py

@@ -0,0 +1,127 @@
+"""Continuum driver: follows the Blueprint literally against a real browser page.
+
+Act II. Dispatches each step to a Playwright page operation (actions.py), a DOM read
+(bridge.py), an artifact producer (screenshot), or an Act-agnostic handler (SharedActionsMixin).
+Synchronous throughout, matching the engine; Playwright is imported lazily by BrowserSession.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .._shared import SharedActionsMixin
+from ...core.blueprint.models import StepModel
+from ...core.errors import ActionError
+from ...core.events.bus import EventBus
+from ...core.events.models import EventType, RunEvent
+from ...core.runtime.context import RunContext
+from ...stealth.policy import StealthPolicy, build_policy
+from ...stealth.session.store import resolve_profile_dir, run_dir
+from .actions import PAGE_ACTIONS, _locator
+from .bridge import evaluate, extract, wait_for
+from .browser import BrowserSession
+from .human_actions import HUMAN_ACTIONS, humanized_actions
+
+
+class ContinuumDriver(SharedActionsMixin):
+    act = "continuum"
+
+    def __init__(self) -> None:
+        self._session: BrowserSession | None = None
+        self._policy: StealthPolicy | None = None
+        self._humanized: frozenset[str] = frozenset()
+
+    def setup(self, ctx: RunContext) -> None:
+        opts = ctx.blueprint.options
+        session_opts = opts.session
+        profile_dir = None
+        if session_opts is not None and session_opts.persist:
+            profile_dir = resolve_profile_dir(session_opts.profile)
+        self._policy = build_policy(opts.stealth)
+        self._humanized = humanized_actions(self._policy)
+        self._session = BrowserSession(
+            debug=opts.debug,
+            timeout_ms=opts.timeout_ms or 30_000,
+            profile_dir=profile_dir,
+            stealth=self._policy,
+        )
+        self._session.start()
+
+    def teardown(self, ctx: RunContext) -> None:
+        if self._session is not None:
+            self._session.close()
+            self._session = None
+
+    def run_step(
+        self,
+        step: StepModel,
+        ctx: RunContext,
+        bus: EventBus,
+        renderer: Callable[[Any], Any],
+    ) -> dict[str, Any]:
+        if self._session is None:
+            raise ActionError("ContinuumDriver.run_step called before setup().")
+        page = self._session.page
+        params = step.extra_fields
+
+        human = self._session.human
+        if human is not None and step.action in self._humanized:
+            return HUMAN_ACTIONS[step.action](human, params, renderer)
+
+        page_action = PAGE_ACTIONS.get(step.action)
+        if page_action is not None:
+            return page_action(page, params, renderer)
+
+        match step.action:
+            case "extract":
+                return extract(page, params, renderer)
+            case "wait_for":
+                return wait_for(page, params, renderer)
+            case "evaluate":
+                return evaluate(page, params, renderer)
+            case "screenshot":
+                return self._screenshot(step, ctx, bus, renderer)
+            case "emit":
+                return self._emit(step, ctx, bus, renderer)
+            case "wait":
+                if human is not None:
+                    human.park()  # drift the cursor off the controls while idling, like a person
+                return self._wait(step, renderer)
+            case "set":
+                return self._set(step, renderer)
+            case "assert":
+                return self._assert(step, renderer)
+            case _:
+                raise ActionError(f"ContinuumDriver: unsupported action {step.action!r}")
+
+    def _screenshot(
+        self,
+        step: StepModel,
+        ctx: RunContext,
+        bus: EventBus,
+        renderer: Callable[[Any], Any],
+    ) -> dict[str, Any]:
+        assert self._session is not None
+        page = self._session.page
+        params = step.extra_fields
+        name = renderer(params.get("name")) or f"{step.id or 'screenshot'}.png"
+        path = run_dir(ctx.run_id) / str(name)
+
+        if params.get("selector"):
+            _locator(page, params, renderer).screenshot(path=str(path))
+        else:
+            page.screenshot(
+                path=str(path), full_page=bool(renderer(params.get("full_page", False)))
+            )
+
+        bus.emit(
+            RunEvent(
+                run_id=ctx.run_id,
+                type=EventType.ARTIFACT,
+                step_id=step.id,
+                message=f"screenshot: {path}",
+                level="info",
+                data={"kind": "screenshot", "path": str(path)},
+            )
+        )
+        return {"path": str(path)}

aetherius/acts/continuum/human_actions.py

@@ -0,0 +1,74 @@
+"""Humanized variants of the interactive page actions, used when a StealthPolicy enables them.
+
+The plain actions in ``actions.py`` stay the fast, deterministic default. When discretion is on, the
+driver routes the interactive subset (click/hover/fill/type/scroll) here instead: same
+``(params, render) -> dict`` contract, but the operation runs through :class:`HumanInput` so it is
+paced and moved like a person. Locator resolution is reused from ``actions.py`` — this module owns
+none of Playwright's selector logic, only the choice to humanize.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Mapping
+
+from ...stealth.humanizer.input import HumanInput
+from ...stealth.policy import StealthPolicy
+from .actions import Renderer, _locator
+
+
+def _target(human: HumanInput, params: Mapping[str, Any], render: Renderer) -> Any:
+    return _locator(human.page, params, render)
+
+
+def click(human: HumanInput, params: Mapping[str, Any], render: Renderer) -> dict[str, Any]:
+    human.click(_target(human, params, render))
+    return {}
+
+
+def hover(human: HumanInput, params: Mapping[str, Any], render: Renderer) -> dict[str, Any]:
+    human.hover(_target(human, params, render))
+    return {}
+
+
+def fill(human: HumanInput, params: Mapping[str, Any], render: Renderer) -> dict[str, Any]:
+    human.fill(_target(human, params, render), render(params.get("value", "")))
+    return {}
+
+
+def type_text(human: HumanInput, params: Mapping[str, Any], render: Renderer) -> dict[str, Any]:
+    text = render(params.get("text", params.get("value", "")))
+    human.type(_target(human, params, render), text)
+    return {}
+
+
+def scroll(human: HumanInput, params: Mapping[str, Any], render: Renderer) -> dict[str, Any]:
+    # A targeted scroll is about reaching an element (kept programmatic); a bare delta is a real
+    # wheel gesture and gets the eased humanized motion.
+    if params.get("selector"):
+        _locator(human.page, params, render).scroll_into_view_if_needed()
+    else:
+        human.scroll_by(float(render(params.get("dy", 0)) or 0))
+    return {}
+
+
+HumanAction = Callable[[HumanInput, Mapping[str, Any], Renderer], dict[str, Any]]
+
+HUMAN_ACTIONS: dict[str, HumanAction] = {
+    "click": click,
+    "hover": hover,
+    "fill": fill,
+    "type": type_text,
+    "scroll": scroll,
+}
+
+
+def humanized_actions(policy: StealthPolicy) -> frozenset[str]:
+    """Which action names *policy* should route to the humanized layer (empty when none apply)."""
+    actions: set[str] = set()
+    if policy.mouse == "gestures":
+        actions |= {"click", "hover", "fill", "type"}
+    if policy.keyboard == "human":
+        actions |= {"fill", "type"}
+    if policy.scroll == "eased":
+        actions |= {"scroll"}
+    return frozenset(actions)

aetherius/acts/oracle/__init__.py

@@ -0,0 +1 @@
+"""Act III - Oracle: vision-guided browser automation with stealth as a first-class concern."""

aetherius/acts/oracle/driver.py

@@ -0,0 +1 @@
+"""Oracle driver: locates targets by vision when selectors are brittle, acts through the stealth humanizer."""

aetherius/acts/oracle/locator.py

@@ -0,0 +1 @@
+"""Turns a vision target description into concrete on-screen coordinates."""

aetherius/acts/oracle/model.py

@@ -0,0 +1 @@
+"""Loading and inference wrapper for the Oracle vision models."""

aetherius/acts/oracle/perception.py

@@ -0,0 +1 @@
+"""Screenshot perception: runs the task-specific ONNX detector to find UI elements."""

aetherius/acts/phantom/__init__.py

@@ -0,0 +1 @@
+"""Act IV - Phantom: autonomous decisional agent. The heaviest Act."""

aetherius/acts/phantom/driver.py

@@ -0,0 +1 @@
+"""Phantom driver: goal-driven execution, stealth by default, maximal resilience."""

aetherius/acts/phantom/loop.py

@@ -0,0 +1 @@
+"""The perceive-reason-act loop that advances the agent toward its goal."""

aetherius/acts/phantom/memory.py

@@ -0,0 +1 @@
+"""Working and task memory for the agent across steps."""

aetherius/acts/phantom/perception.py

@@ -0,0 +1 @@
+"""Perception fusion: DOM, accessibility tree and vision merged into the planner state."""

aetherius/acts/phantom/planner.py

@@ -0,0 +1 @@
+"""Decision policy: a vision-language planner (Claude by default, pluggable) that chooses the next action."""

aetherius/acts/vector/__init__.py

@@ -0,0 +1 @@
+"""Act I - Vector: HTTP/API engine. The lightest Act."""

aetherius/acts/vector/auth.py

@@ -0,0 +1,108 @@
+"""Authentication strategies for Vector (Act I): NoAuth, Bearer, Basic, Cookie, CAS form-login."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+import httpx
+from parsel import Selector
+
+
+@runtime_checkable
+class AuthStrategy(Protocol):
+    def prepare(self, client: httpx.Client) -> None:
+        """Called once before the first request (e.g., perform a login flow)."""
+        ...
+
+    def apply(self, request: httpx.Request) -> httpx.Request:
+        """Mutate or replace a request to inject auth headers/cookies. Called per-request."""
+        ...
+
+
+class NoAuth:
+    def prepare(self, client: httpx.Client) -> None:
+        pass
+
+    def apply(self, request: httpx.Request) -> httpx.Request:
+        return request
+
+
+class BearerAuth:
+    def __init__(self, token: str) -> None:
+        self._token = token
+
+    def prepare(self, client: httpx.Client) -> None:
+        pass
+
+    def apply(self, request: httpx.Request) -> httpx.Request:
+        # httpx requests are immutable; re-build with updated headers.
+        return httpx.Request(
+            method=request.method,
+            url=request.url,
+            headers={**dict(request.headers), "Authorization": f"Bearer {self._token}"},
+            content=request.content,
+        )
+
+
+class BasicAuth:
+    def __init__(self, username: str, password: str) -> None:
+        self._auth = httpx.BasicAuth(username, password)
+
+    def prepare(self, client: httpx.Client) -> None:
+        client.auth = self._auth
+
+    def apply(self, request: httpx.Request) -> httpx.Request:
+        return request
+
+
+class CookieAuth:
+    def __init__(self, cookies: dict[str, str]) -> None:
+        self._cookies = cookies
+
+    def prepare(self, client: httpx.Client) -> None:
+        client.cookies.update(self._cookies)
+
+    def apply(self, request: httpx.Request) -> httpx.Request:
+        return request
+
+
+class CasFormLogin:
+    """CAS-style form-login: GET login page → extract hidden fields → POST credentials → capture cookies."""
+
+    def __init__(
+        self,
+        login_url: str,
+        username: str,
+        password: str,
+        username_field: str = "username",
+        password_field: str = "password",
+    ) -> None:
+        self._login_url = login_url
+        self._username = username
+        self._password = password
+        self._username_field = username_field
+        self._password_field = password_field
+
+    def prepare(self, client: httpx.Client) -> None:
+        resp = client.get(self._login_url)
+        resp.raise_for_status()
+        form_data = _extract_form_fields(resp.content)
+        form_data[self._username_field] = self._username
+        form_data[self._password_field] = self._password
+        login_resp = client.post(self._login_url, data=form_data, follow_redirects=True)
+        login_resp.raise_for_status()
+
+    def apply(self, request: httpx.Request) -> httpx.Request:
+        return request
+
+
+def _extract_form_fields(html: bytes) -> dict[str, str]:
+    """Extract all hidden input fields from the first <form> in *html*."""
+    sel = Selector(text=html.decode("utf-8", errors="replace"))
+    fields: dict[str, str] = {}
+    for inp in sel.css("form input[type=hidden]"):
+        name = inp.attrib.get("name", "")
+        value = inp.attrib.get("value", "")
+        if name:
+            fields[name] = value
+    return fields