vdisplay 0.1.5__py3-none-any.whl

vdisplay/__init__.py

@@ -0,0 +1,12 @@
+from .api import MirrorSession, VirtualDisplaySession, WindowRelaySession, platform_summary
+from .exceptions import BackendNotAvailableError, CapabilityError, VDisplayError
+
+__all__ = [
+    "VirtualDisplaySession",
+    "MirrorSession",
+    "WindowRelaySession",
+    "platform_summary",
+    "VDisplayError",
+    "BackendNotAvailableError",
+    "CapabilityError",
+]

vdisplay/agent_config.py

@@ -0,0 +1,71 @@
+"""Resolve vdisplay-agent connection (install-once broker for all client apps)."""
+
+from __future__ import annotations
+
+import os
+import urllib.error
+import urllib.request
+
+_PROBE_SENTINEL = object()
+_probe_cache: str | None | object = _PROBE_SENTINEL
+
+
+def agent_auto_enabled() -> bool:
+    return os.environ.get("VDISPLAY_AGENT_AUTO", "1").strip().lower() not in {
+        "0",
+        "false",
+        "no",
+        "off",
+    }
+
+
+def reset_agent_probe_cache() -> None:
+    global _probe_cache
+    _probe_cache = _PROBE_SENTINEL
+
+
+def _default_agent_base() -> str:
+    host = os.environ.get("VDISPLAY_AGENT_HOST", "127.0.0.1").strip() or "127.0.0.1"
+    port = os.environ.get("VDISPLAY_AGENT_PORT", "8765").strip() or "8765"
+    return f"http://{host}:{port}"
+
+
+def _probe_agent_url(base_url: str, *, timeout: float = 0.2) -> str | None:
+    try:
+        with urllib.request.urlopen(f"{base_url.rstrip('/')}/health", timeout=timeout) as response:
+            if response.status == 200:
+                return base_url.rstrip("/")
+    except (urllib.error.URLError, TimeoutError, OSError, ValueError):
+        return None
+    return None
+
+
+def _probe_default_agent() -> str | None:
+    global _probe_cache
+    if isinstance(_probe_cache, str):
+        return _probe_cache
+    url = _probe_agent_url(_default_agent_base())
+    if url:
+        _probe_cache = url
+    return url
+
+
+def resolve_agent_url(explicit: str | None = None, *, allow_auto: bool = False) -> str | None:
+    """Return agent base URL when clients should use IPC instead of in-process capture."""
+    url = (explicit or os.environ.get("VDISPLAY_AGENT_URL") or "").strip()
+    if url:
+        return url.rstrip("/")
+    if not allow_auto or not agent_auto_enabled():
+        return None
+    return _probe_default_agent()
+
+
+def resolve_agent_token() -> str | None:
+    token = (os.environ.get("VDISPLAY_AGENT_TOKEN") or "").strip()
+    return token or None
+
+
+def use_agent(explicit: str | None = None) -> bool:
+    if os.environ.get("VDISPLAY_AGENT_BROKER", "").strip().lower() in {"1", "true", "yes"}:
+        return False
+    return resolve_agent_url(explicit, allow_auto=True) is not None

vdisplay/agent_dispatch.py

@@ -0,0 +1,30 @@
+"""Deprecated — route DSL verbs through application.executor."""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+from .agent_config import resolve_agent_url
+from .application.commands import CommandRequest
+from .application.executor import execute
+from .client import AgentClient
+from .exceptions import VDisplayError
+
+
+def agent_client(url: str | None = None) -> AgentClient:
+    resolved = resolve_agent_url(url)
+    if not resolved:
+        raise VDisplayError("VDISPLAY_AGENT_URL is not set")
+    return AgentClient(resolved)
+
+
+def dispatch_via_agent(cmd: dict[str, Any], *, line: str) -> Any:
+    """Execute parsed DSL command through vdisplay-agent (via executor)."""
+    warnings.warn(
+        "agent_dispatch.dispatch_via_agent is deprecated; use application.executor.execute",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    request = CommandRequest.from_dsl(cmd, line=line)
+    return execute(request, force_route="agent").to_dsl_result()

vdisplay/agent_envelope.py

@@ -0,0 +1,17 @@
+"""Flatten vdisplay-agent JSON envelopes for SDK clients."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def flatten_agent_envelope(payload: dict[str, Any]) -> dict[str, Any]:
+    """Merge envelope.data to top level for backward-compatible clients."""
+    if "data" in payload and "action" in payload:
+        flat = dict(payload.get("data") or {})
+        if "ok" in payload:
+            flat["ok"] = payload["ok"]
+        if payload.get("error"):
+            flat["error"] = payload["error"]
+        return flat
+    return payload

vdisplay/api.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+import platform
+import sys
+from dataclasses import asdict
+
+from .backends.linux_x11_mirror import LinuxX11MirrorBackend
+from .backends.linux_x11_relay import LinuxX11RelayBackend
+from .backends.linux_xvfb import LinuxXvfbBackend
+from .exceptions import BackendNotAvailableError
+
+
+def _default_virtual_backend() -> str:
+    if sys.platform.startswith("linux"):
+        return "xvfb"
+    return "xvfb"
+
+
+def _default_mirror_backend() -> str:
+    if sys.platform.startswith("linux"):
+        return "x11"
+    return "stub"
+
+
+def _default_relay_backend() -> str:
+    if sys.platform.startswith("linux"):
+        return "x11"
+    return "x11"
+
+
+class VirtualDisplaySession:
+    def __init__(self, backend) -> None:
+        self.backend = backend
+
+    @classmethod
+    def create(
+        cls,
+        width: int = 1920,
+        height: int = 1080,
+        backend: str | None = None,
+        display: str = ":99",
+    ):
+        backend = backend or _default_virtual_backend()
+        if backend == "xvfb":
+            if not sys.platform.startswith("linux"):
+                raise BackendNotAvailableError("xvfb backend is only available on Linux")
+            return cls(LinuxXvfbBackend(width=width, height=height, display=display))
+        raise BackendNotAvailableError(f"Unknown virtual backend: {backend}")
+
+    def start(self) -> None:
+        self.backend.start()
+
+    def stop(self) -> None:
+        self.backend.stop()
+
+    def launch(self, command):
+        return self.backend.launch(command)
+
+    def screenshot_bytes(self) -> bytes:
+        return self.backend.screenshot_bytes()
+
+    def save_screenshot(self, path: str) -> str:
+        return self.backend.save_screenshot(path)
+
+    def adopt_window(self, *, match_title: str | None = None, window_id: str | None = None) -> str:
+        return self.backend.adopt_window(match_title=match_title, window_id=window_id)
+
+    def release_window(self, *, match_title: str | None = None, window_id: str | None = None) -> str:
+        return self.backend.release_window(match_title=match_title, window_id=window_id)
+
+    def info(self) -> dict:
+        return asdict(self.backend.info())
+
+    def capabilities(self) -> dict:
+        return asdict(self.backend.capabilities())
+
+
+class MirrorSession:
+    def __init__(self, backend) -> None:
+        self.backend = backend
+        self.pointer = getattr(backend, "pointer", None)
+
+    @classmethod
+    def create(
+        cls,
+        source: str = "primary",
+        target: str | None = None,
+        backend: str | None = None,
+        display: str | None = None,
+    ):
+        backend = backend or _default_mirror_backend()
+        if backend in {"x11", "linux-x11", "linux-x11-mirror"}:
+            if not sys.platform.startswith("linux"):
+                raise BackendNotAvailableError("linux-x11 mirror backend is only available on Linux")
+            return cls(LinuxX11MirrorBackend(source=source, target=target, display=display))
+        if backend == "stub":
+            from .backends.mirror_stub import MirrorStubBackend
+
+            return cls(MirrorStubBackend(source=source, target=target or "virtual:1"))
+        raise BackendNotAvailableError(f"Unknown mirror backend: {backend}")
+
+    def start(self) -> None:
+        self.backend.start()
+
+    def stop(self) -> None:
+        self.backend.stop()
+
+    def screenshot_bytes(self) -> bytes:
+        return self.backend.screenshot_bytes()
+
+    def save_screenshot(self, path: str) -> str:
+        return self.backend.save_screenshot(path)
+
+    def info(self) -> dict:
+        return asdict(self.backend.info())
+
+    def capabilities(self) -> dict:
+        return asdict(self.backend.capabilities())
+
+
+class WindowRelaySession:
+    def __init__(self, backend) -> None:
+        self.backend = backend
+
+    @classmethod
+    def create(cls, backend: str | None = None, display: str | None = None):
+        backend = backend or _default_relay_backend()
+        if backend in {"x11", "linux-x11", "linux-x11-relay"}:
+            if not sys.platform.startswith("linux"):
+                raise BackendNotAvailableError("linux-x11 relay backend is only available on Linux")
+            return cls(LinuxX11RelayBackend(display=display))
+        raise BackendNotAvailableError(f"Unknown relay backend: {backend}")
+
+    def start(self) -> None:
+        self.backend.start()
+
+    def stop(self) -> None:
+        self.backend.stop()
+
+    def adopt_window(
+        self,
+        *,
+        match_title: str | None = None,
+        window_id: str | None = None,
+        match_class: str | None = None,
+        match_pid: int | None = None,
+        match_app: str | None = None,
+        target: str = "offscreen",
+    ) -> str:
+        return self.backend.adopt_window(
+            match_title=match_title,
+            window_id=window_id,
+            match_class=match_class,
+            match_pid=match_pid,
+            match_app=match_app,
+            target=target,
+        )
+
+    def release_window(
+        self,
+        *,
+        match_title: str | None = None,
+        window_id: str | None = None,
+        match_class: str | None = None,
+        match_pid: int | None = None,
+        match_app: str | None = None,
+    ) -> str:
+        return self.backend.release_window(
+            match_title=match_title,
+            window_id=window_id,
+            match_class=match_class,
+            match_pid=match_pid,
+            match_app=match_app,
+        )
+
+    def list_adopted(self) -> list[dict]:
+        return self.backend.list_adopted()
+
+    def info(self) -> dict:
+        return asdict(self.backend.info())
+
+    def capabilities(self) -> dict:
+        return asdict(self.backend.capabilities())
+
+
+def platform_summary() -> dict:
+    return {
+        "platform": platform.system(),
+        "python": platform.python_version(),
+        "virtual_backend": _default_virtual_backend(),
+        "mirror_backend": _default_mirror_backend(),
+        "relay_backend": _default_relay_backend(),
+    }

vdisplay/application/__init__.py

@@ -0,0 +1,14 @@
+"""Application use-cases — single execution layer for all interfaces."""
+
+from . import commands, errors
+from .services import capture, discovery, info, session
+
+__all__ = ["capture", "commands", "discovery", "errors", "executor", "info", "session"]
+
+
+def __getattr__(name: str):
+    if name == "executor":
+        from . import executor as executor_mod
+
+        return executor_mod
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

vdisplay/application/commands.py

@@ -0,0 +1,183 @@
+"""Shared command model for CLI, DSL, REST, and agent client."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+from .errors import ApplicationError
+
+
+class CommandVerb(StrEnum):
+    HEALTH = "HEALTH"
+    INFO = "INFO"
+    OUTPUTS = "OUTPUTS"
+    MONITORS = "MONITORS"
+    WINDOWS = "WINDOWS"
+    ALL = "ALL"
+    CAPABILITIES = "CAPABILITIES"
+    VALIDATE = "VALIDATE"
+    SCREENSHOT = "SCREENSHOT"
+    VIRTUAL_START = "VIRTUAL_START"
+    VIRTUAL_STOP = "VIRTUAL_STOP"
+    LAUNCH = "LAUNCH"
+    MIRROR = "MIRROR"
+    ADOPT = "ADOPT"
+    RELEASE = "RELEASE"
+
+
+QUERY_VERBS = frozenset(
+    {
+        CommandVerb.HEALTH,
+        CommandVerb.INFO,
+        CommandVerb.OUTPUTS,
+        CommandVerb.MONITORS,
+        CommandVerb.WINDOWS,
+        CommandVerb.ALL,
+        CommandVerb.CAPABILITIES,
+        CommandVerb.VALIDATE,
+    }
+)
+
+COMMAND_VERBS = frozenset(
+    {
+        CommandVerb.SCREENSHOT,
+        CommandVerb.VIRTUAL_START,
+        CommandVerb.VIRTUAL_STOP,
+        CommandVerb.LAUNCH,
+        CommandVerb.MIRROR,
+        CommandVerb.ADOPT,
+        CommandVerb.RELEASE,
+    }
+)
+
+
+@dataclass
+class CommandRequest:
+    verb: CommandVerb
+    line: str = ""
+    display: str | None = None
+    apps_only: bool = False
+    include_all: bool = True
+    match_class: str | None = None
+    match_pid: int | None = None
+    match_app: str | None = None
+    match_title: str | None = None
+    window_id: str | None = None
+    min_width: int = 0
+    min_height: int = 0
+    output: str | None = None
+    width: int = 1920
+    height: int = 1080
+    source: str | None = None
+    target: str | None = None
+    mode: str = "host"
+    all_monitors: bool = False
+    out_dir: str | None = None
+    vd_display: str = ":99"
+    backend: str = "xvfb"
+    monitor: int | None = None
+    local_only: bool = False
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def action(self) -> str:
+        if self.verb == CommandVerb.OUTPUTS:
+            return "outputs"
+        return self.verb.value.lower()
+
+    @classmethod
+    def from_dsl(cls, cmd: dict[str, Any], *, line: str = "") -> CommandRequest:
+        verb_raw = str(cmd.get("verb", "HEALTH")).upper()
+        try:
+            verb = CommandVerb(verb_raw)
+        except ValueError:
+            verb = CommandVerb.HEALTH
+        apps_only = bool(cmd.get("apps_only", False))
+        return cls(
+            verb=verb,
+            line=line,
+            display=cmd.get("display"),
+            apps_only=apps_only,
+            include_all=not apps_only,
+            match_class=cmd.get("class"),
+            match_pid=cmd.get("pid"),
+            match_app=cmd.get("app"),
+            match_title=cmd.get("title"),
+            window_id=cmd.get("window_id"),
+            output=cmd.get("out"),
+            width=int(cmd.get("width", 1920)),
+            height=int(cmd.get("height", 1080)),
+            source=cmd.get("source"),
+            target=cmd.get("target"),
+            vd_display=str(cmd.get("display", ":99")),
+            backend=str(cmd.get("backend", "xvfb")),
+            extra={k: v for k, v in cmd.items() if k not in {"verb"}},
+        )
+
+
+@dataclass
+class CommandResult:
+    ok: bool
+    action: str
+    data: dict[str, Any] = field(default_factory=dict)
+    error: ApplicationError | None = None
+    meta: dict[str, Any] = field(default_factory=dict)
+    command: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "ok": self.ok,
+            "action": self.action,
+            "data": self.data,
+            "meta": self.meta,
+        }
+        if self.command:
+            payload["command"] = self.command
+        if self.error is not None:
+            payload["error"] = self.error.to_dict()
+        return payload
+
+    def to_dsl_result(self) -> Any:
+        from dsl2vdisplay.result import DslResult
+
+        return DslResult(
+            ok=self.ok,
+            command=self.command,
+            action=self.action,
+            output=json.dumps(self.data, indent=2, ensure_ascii=False) if self.ok else "",
+            data=self.data,
+            error=None if self.ok else (self.error.message if self.error else "unknown error"),
+        )
+
+    @classmethod
+    def success(
+        cls,
+        *,
+        action: str,
+        data: dict[str, Any],
+        command: str = "",
+        meta: dict[str, Any] | None = None,
+    ) -> CommandResult:
+        return cls(ok=True, action=action, data=data, command=command, meta=meta or {})
+
+    @classmethod
+    def failure(
+        cls,
+        *,
+        action: str,
+        error: ApplicationError,
+        data: dict[str, Any] | None = None,
+        command: str = "",
+        meta: dict[str, Any] | None = None,
+    ) -> CommandResult:
+        return cls(
+            ok=False,
+            action=action,
+            data=data or {},
+            error=error,
+            command=command,
+            meta=meta or {},
+        )

vdisplay/application/errors.py

@@ -0,0 +1,39 @@
+"""Stable error codes for command execution and agent HTTP envelope."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+
+class ErrorCode(StrEnum):
+    NOT_SUPPORTED = "not_supported"
+    DEPENDENCY_MISSING = "dependency_missing"
+    PERMISSION_REQUIRED = "permission_required"
+    SESSION_NOT_FOUND = "session_not_found"
+    INVALID_REQUEST = "invalid_request"
+    BACKEND_UNAVAILABLE = "backend_unavailable"
+    INTERNAL = "internal"
+
+
+@dataclass
+class ApplicationError:
+    code: ErrorCode
+    message: str
+    details: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"code": self.code.value, "message": self.message, "details": self.details}
+
+
+def error_from_exception(exc: Exception) -> ApplicationError:
+    from ..exceptions import BackendNotAvailableError, CapabilityError, VDisplayError
+
+    if isinstance(exc, CapabilityError):
+        return ApplicationError(ErrorCode.NOT_SUPPORTED, str(exc))
+    if isinstance(exc, BackendNotAvailableError):
+        return ApplicationError(ErrorCode.BACKEND_UNAVAILABLE, str(exc))
+    if isinstance(exc, VDisplayError):
+        return ApplicationError(ErrorCode.INVALID_REQUEST, str(exc))
+    return ApplicationError(ErrorCode.INTERNAL, str(exc))

vdisplay/application/executor.py

@@ -0,0 +1,51 @@
+"""Execute CommandRequest via agent or local application services."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .commands import CommandRequest, CommandResult, CommandVerb
+from .errors import error_from_exception
+from .handlers import execute_agent, execute_local
+from .runtime import ExecutionPolicy, Route, get_execution_policy
+from ..exceptions import VDisplayError
+
+
+def _maybe_enrich_screenshot(cmd: CommandRequest, data: dict[str, Any]) -> dict[str, Any]:
+    if cmd.verb != CommandVerb.SCREENSHOT:
+        return data
+    if cmd.extra.get("skip_img2nl"):
+        return data
+    from .services import img2nl_enrich
+
+    return img2nl_enrich.enrich_screenshot_payload(data)
+
+
+def execute(
+    cmd: CommandRequest,
+    *,
+    policy: ExecutionPolicy | None = None,
+    force_route: Route | None = None,
+) -> CommandResult:
+    """Single entry for command execution across CLI, DSL, REST, and agent dispatch."""
+    pol = policy or get_execution_policy()
+    route = force_route or pol.route(cmd)
+    meta = pol.meta_for(route)
+    try:
+        data = execute_agent(cmd) if route == "agent" else execute_local(cmd)
+        data = _maybe_enrich_screenshot(cmd, data)
+        return CommandResult.success(action=cmd.action, data=data, command=cmd.line, meta=meta)
+    except VDisplayError as exc:
+        return CommandResult.failure(
+            action=cmd.action,
+            error=error_from_exception(exc),
+            command=cmd.line,
+            meta=meta,
+        )
+    except Exception as exc:
+        return CommandResult.failure(
+            action=cmd.action,
+            error=error_from_exception(exc),
+            command=cmd.line,
+            meta=meta,
+        )

vdisplay/application/handlers/__init__.py

@@ -0,0 +1,6 @@
+"""Per-verb command handlers for local and agent execution."""
+
+from .agent import execute_agent
+from .local import execute_local
+
+__all__ = ["execute_agent", "execute_local"]