desk-proxy 0.1.2__py3-none-any.whl

desk_proxy/__init__.py

@@ -0,0 +1,13 @@
+"""
+desk-proxy: Non-MCP CLI proxy for Linux desktop automation.
+
+Screenshots, keyboard/mouse input, OCR, and HITL review — ADN envelope
+compatible with tick-proxy / mail-proxy / tg-proxy.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("desk-proxy")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

desk_proxy/actions/__init__.py

@@ -0,0 +1,5 @@
+"""desk-proxy actions package — domain modules + registry."""
+
+from .registry import ACTION_COUNT, REGISTRY, by_group, get
+
+__all__ = ["ACTION_COUNT", "REGISTRY", "by_group", "get"]

desk_proxy/actions/base.py

@@ -0,0 +1,116 @@
+"""
+Action framework — declarative approval policy for desk-proxy.
+
+Same ADN contract as tick/mail: an ``ActionDef`` carries the action name, its
+colocated Pydantic payload model and the handler. ``@require_approval`` derives
+HITL policy from the handler — ``cli.py`` has no separate policy table.
+
+Handler signature (local desktop — no remote client)::
+
+    handler(payload) -> dict
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from functools import wraps
+from typing import Any
+
+from pydantic import BaseModel
+
+
+@dataclass(frozen=True)
+class ActionDef:
+    """One ``do`` action: name, payload model, handler and its policies.
+
+    Attributes:
+        name (str): The flat kebab-case action name, e.g. ``shot-take``.
+        payload (type[BaseModel] | None): Pydantic model validating the payload
+            (None when the action takes no payload).
+        handler (Callable): ``handler(payload) -> dict`` — no client argument.
+        hitl (bool): Derived from the handler's ``@require_approval`` declaration.
+        group (str): Catalog group used by ``do --help``, e.g. ``"Screen"``.
+        aliases (tuple[str, ...]): Optional command aliases.
+
+    Examples:
+        >>> ActionDef("shot-take", None, lambda p: {}, group="Screen").name
+        'shot-take'
+        >>> ActionDef("shot-take", None, lambda p: {}).hitl
+        False
+    """
+
+    name: str
+    payload: type[BaseModel] | None
+    handler: Callable[..., Any]
+    hitl: bool = False
+    group: str = "Misc"
+    aliases: tuple[str, ...] = field(default_factory=tuple)
+
+
+def require_approval() -> Callable:
+    """Declare a handler's mandatory centralized HITL review policy.
+
+    Returns:
+        Callable: A decorator carrying auditable review metadata.
+
+    Examples:
+        >>> @require_approval()
+        ... def click(payload): return {}
+        >>> click.__require_approval__
+        True
+        >>> click.__review_mode__
+        'default'
+        >>> callable(click)
+        True
+    """
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            return func(*args, **kwargs)
+
+        wrapper.__require_approval__ = True  # type: ignore[attr-defined]
+        wrapper.__review_mode__ = "default"  # type: ignore[attr-defined]
+        return wrapper
+
+    return decorator
+
+
+def action_def(
+    name: str,
+    payload: type[BaseModel] | None,
+    handler: Callable[..., Any],
+    *,
+    group: str = "Misc",
+    aliases: tuple[str, ...] = (),
+) -> ActionDef:
+    """Build an action definition from visible handler decorators.
+
+    Args:
+        name (str): Flat registered action name.
+        payload (type[BaseModel] | None): Pydantic payload model.
+        handler (Callable[..., Any]): Decorated implementation
+            (``handler(payload) -> dict``).
+        group (str): Help catalog group.
+        aliases (tuple[str, ...]): Optional command aliases.
+
+    Returns:
+        ActionDef: HITL policy derived from ``__require_approval__``.
+
+    Examples:
+        >>> @require_approval()
+        ... def type_text(payload): return {}
+        >>> action_def("type-text", None, type_text).hitl
+        True
+        >>> action_def("shot-take", None, lambda p: {}).hitl
+        False
+        >>> action_def("raw", None, lambda p: {}, group="Escape hatch").group
+        'Escape hatch'
+    """
+    return ActionDef(
+        name=name,
+        payload=payload,
+        handler=handler,
+        hitl=bool(getattr(handler, "__require_approval__", False)),
+        group=group,
+        aliases=aliases,
+    )

desk_proxy/actions/clipboard.py

@@ -0,0 +1,68 @@
+"""Clipboard group — get and set system clipboard text."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from desk_proxy.api import clipboard as clip_api
+
+from .base import action_def, require_approval
+
+
+class ClipboardSetPayload(BaseModel):
+    """Text to place on the clipboard."""
+
+    text: str = Field(..., description="Clipboard contents to write")
+
+
+def clipboard_get(_payload: Any = None) -> dict[str, Any]:
+    """Read the current clipboard text (wl-paste or xclip).
+
+    Parameters:
+        - (none): Payload may be null or ``{}``.
+
+    Examples:
+        - Read clipboard:
+            `desk-proxy do clipboard-get '{}'`
+            → {"text": "hello from clipboard"}
+
+        - Empty clipboard:
+            `desk-proxy do clipboard-get`
+            → {"text": ""}
+
+        - After a set:
+            `desk-proxy do clipboard-get '{}'`
+            → {"text": "desk-proxy-probe"}
+    """
+    return {"text": clip_api.clipboard_get()}
+
+
+@require_approval()
+def clipboard_set(p: ClipboardSetPayload) -> dict[str, Any]:
+    """Write text to the clipboard. HITL required.
+
+    Parameters:
+        - text (str): Text to place on the clipboard (required).
+
+    Examples:
+        - Set a short string:
+            `desk-proxy do clipboard-set '{"text":"hello"}'`
+            → {"text": "hello"}
+
+        - Clear clipboard:
+            `desk-proxy do clipboard-set '{"text":""}'`
+            → {"text": ""}
+
+        - HITL rejection:
+            `desk-proxy do clipboard-set '{"text":"secret"}'`
+            → {"meta": {"status": "rejected", "comment": "not now"}, "data": null}
+    """
+    return {"text": clip_api.clipboard_set(p.text)}
+
+
+ACTIONS = [
+    action_def("clipboard-get", None, clipboard_get, group="Clipboard"),
+    action_def("clipboard-set", ClipboardSetPayload, clipboard_set, group="Clipboard"),
+]

desk_proxy/actions/control.py

@@ -0,0 +1,158 @@
+"""Control group — wait, action chains, and raw backend escape hatch."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from desk_proxy.api.run import run_cmd
+from desk_proxy.exceptions import DeskProxyError
+
+from .base import action_def, require_approval
+
+RawBackend = Literal["xdotool", "ydotool", "wmctrl", "shell"]
+
+
+class WaitPayload(BaseModel):
+    """Sleep for a fixed duration."""
+
+    seconds: float = Field(..., description="Seconds to sleep (>= 0)", ge=0)
+
+
+class ChainStep(BaseModel):
+    """One step inside a ``chain`` action."""
+
+    action: str = Field(..., description="Registered kebab-case action name")
+    payload: dict[str, Any] = Field(
+        default_factory=dict, description="JSON payload for that action"
+    )
+
+
+class ChainPayload(BaseModel):
+    """Sequential execution of registered desk-proxy actions."""
+
+    steps: list[ChainStep] = Field(..., description="Ordered list of {action, payload}")
+
+
+class RawPayload(BaseModel):
+    """Escape hatch — run a desktop backend with explicit argv."""
+
+    backend: RawBackend = Field(..., description="xdotool | ydotool | wmctrl | shell")
+    args: list[str] = Field(..., description="Arguments (or full argv for shell)")
+
+
+def wait(p: WaitPayload) -> dict[str, Any]:
+    """Sleep for ``seconds`` then return the duration slept.
+
+    Parameters:
+        - seconds (float): Duration in seconds (>= 0).
+
+    Examples:
+        - Short pause:
+            `desk-proxy do wait '{"seconds":0.5}'`
+            → {"slept": 0.5}
+
+        - One second:
+            `desk-proxy do wait '{"seconds":1}'`
+            → {"slept": 1.0}
+
+        - Zero (no-op):
+            `desk-proxy do wait '{"seconds":0}'`
+            → {"slept": 0.0}
+    """
+    time.sleep(float(p.seconds))
+    return {"slept": float(p.seconds)}
+
+
+@require_approval()
+def chain(p: ChainPayload) -> dict[str, Any]:
+    """Execute registered actions sequentially. HITL required for the whole chain.
+
+    Unknown action names are rejected. Nested HITL is not re-prompted — the
+    outer chain approval covers every step. Each step receives a validated
+    payload model when the action declares one.
+
+    Parameters:
+        - steps (list): Ordered ``{action, payload}`` objects.
+
+    Examples:
+        - Info then mouse:
+            `desk-proxy do chain '{"steps":[{"action":"screen-info","payload":{}},{"action":"mouse-get","payload":{}}]}'`
+            → {"results": [{"action": "screen-info", "data": {"width": 1920}}, {"action": "mouse-get", "data": {"x": 10, "y": 20}}]}
+
+        - Wait then shot:
+            `desk-proxy do chain '{"steps":[{"action":"wait","payload":{"seconds":0.1}},{"action":"screen-shot","payload":{}}]}'`
+            → {"results": [{"action": "wait", "data": {"slept": 0.1}}, {"action": "screen-shot", "data": {"path": "/tmp/desk-proxy-shots/full_1.png"}}]}
+
+        - Unknown action fails:
+            `desk-proxy do chain '{"steps":[{"action":"nope","payload":{}}]}'`
+            → {"meta": {"status": "error"}, "data": null}
+    """
+    # Lazy import avoids circular registry ↔ control dependency.
+    from desk_proxy.actions.registry import REGISTRY
+
+    if not p.steps:
+        raise DeskProxyError("chain requires at least one step")
+
+    results: list[dict[str, Any]] = []
+    for step in p.steps:
+        action = REGISTRY.get(step.action)
+        if action is None:
+            raise DeskProxyError(f"Unknown action in chain: {step.action}")
+        raw = step.payload if isinstance(step.payload, dict) else {}
+        if action.payload is not None:
+            validated: Any = action.payload(**raw)
+        else:
+            validated = raw
+        data = action.handler(validated)
+        results.append({"action": step.action, "data": data})
+    return {"results": results}
+
+
+@require_approval()
+def raw(p: RawPayload) -> dict[str, Any]:
+    """Run a desktop backend with explicit args. HITL required.
+
+    For ``xdotool`` / ``ydotool`` / ``wmctrl`` the binary is prepended.
+    For ``shell`` the ``args`` list is the full argv (no shell expansion).
+
+    Parameters:
+        - backend (str): ``xdotool`` | ``ydotool`` | ``wmctrl`` | ``shell``.
+        - args (list[str]): Arguments after the backend binary (or full argv).
+
+    Examples:
+        - Display geometry via xdotool:
+            `desk-proxy do raw '{"backend":"xdotool","args":["getdisplaygeometry"]}'`
+            → {"backend": "xdotool", "argv": ["xdotool", "getdisplaygeometry"], "returncode": 0, "stdout": "1920 1080", "stderr": ""}
+
+        - List windows via wmctrl:
+            `desk-proxy do raw '{"backend":"wmctrl","args":["-l"]}'`
+            → {"backend": "wmctrl", "argv": ["wmctrl", "-l"], "returncode": 0, "stdout": "0x01a00007  0 host Terminal", "stderr": ""}
+
+        - Shell argv (no expansion):
+            `desk-proxy do raw '{"backend":"shell","args":["true"]}'`
+            → {"backend": "shell", "argv": ["true"], "returncode": 0, "stdout": "", "stderr": ""}
+    """
+    if p.backend == "shell":
+        if not p.args:
+            raise DeskProxyError("raw shell backend requires a non-empty args list")
+        argv = list(p.args)
+    else:
+        argv = [p.backend, *p.args]
+    result = run_cmd(argv, timeout=30)
+    return {
+        "backend": p.backend,
+        "argv": argv,
+        "returncode": result.returncode,
+        "stdout": result.stdout or "",
+        "stderr": result.stderr or "",
+    }
+
+
+ACTIONS = [
+    action_def("wait", WaitPayload, wait, group="Control"),
+    action_def("chain", ChainPayload, chain, group="Control"),
+    action_def("raw", RawPayload, raw, group="Control"),
+]

desk_proxy/actions/keyboard.py

@@ -0,0 +1,75 @@
+"""Keyboard group — type text and press key chords."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from desk_proxy.api import input as input_api
+
+from .base import action_def
+
+
+class KeyboardTypePayload(BaseModel):
+    """Unicode text injection at the current focus."""
+
+    text: str = Field(..., description="Text to type")
+    delay_ms: int = Field(12, description="Inter-key delay in milliseconds", ge=0)
+
+
+class KeyboardKeyPayload(BaseModel):
+    """Single key or chord (xdotool-style)."""
+
+    combo: str = Field(..., description="Key or chord, e.g. Return, ctrl+c, alt+F4")
+
+
+def keyboard_type(p: KeyboardTypePayload) -> dict[str, Any]:
+    """Type Unicode text at the current keyboard focus.
+
+    Parameters:
+        - text (str): Text to type (required).
+        - delay_ms (int): Inter-key delay in ms (default 12).
+
+    Examples:
+        - Type a short string:
+            `desk-proxy do keyboard-type '{"text":"hello"}'`
+            → {"typed": "hello", "backend": "wtype", "delay_ms": 12}
+
+        - Slower typing:
+            `desk-proxy do keyboard-type '{"text":"slow","delay_ms":40}'`
+            → {"typed": "slow", "backend": "xdotool", "delay_ms": 40}
+
+        - Long text is preview-truncated:
+            `desk-proxy do keyboard-type '{"text":"abcdefghijklmnopqrstuvwxyz0123456789EXTRA"}'`
+            → {"typed": "abcdefghijklmnopqrstuvwxyz0123456789EXTR...", "backend": "wtype", "delay_ms": 12}
+    """
+    return input_api.type_text(p.text, delay_ms=p.delay_ms)
+
+
+def keyboard_key(p: KeyboardKeyPayload) -> dict[str, Any]:
+    """Press a key or chord (``ctrl+c``, ``Return``, ``alt+F4``, …).
+
+    Parameters:
+        - combo (str): xdotool-style combo string (required).
+
+    Examples:
+        - Escape:
+            `desk-proxy do keyboard-key '{"combo":"Escape"}'`
+            → {"combo": "Escape", "backend": "xdotool"}
+
+        - Copy chord:
+            `desk-proxy do keyboard-key '{"combo":"ctrl+c"}'`
+            → {"combo": "ctrl+c", "backend": "xdotool"}
+
+        - Enter:
+            `desk-proxy do keyboard-key '{"combo":"Return"}'`
+            → {"combo": "Return", "backend": "wtype"}
+    """
+    return input_api.press_key(p.combo)
+
+
+ACTIONS = [
+    action_def("keyboard-type", KeyboardTypePayload, keyboard_type, group="Keyboard"),
+    action_def("keyboard-key", KeyboardKeyPayload, keyboard_key, group="Keyboard"),
+]

desk_proxy/actions/mouse.py

@@ -0,0 +1,183 @@
+"""Mouse group — pointer query, move, click, drag, scroll."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from desk_proxy.api import input as input_api
+
+from .base import action_def
+
+ButtonName = Literal["left", "right", "middle"]
+ScrollDir = Literal["up", "down", "left", "right"]
+
+
+class MouseMovePayload(BaseModel):
+    """Absolute pointer destination."""
+
+    x: int = Field(..., description="Target X in pixels")
+    y: int = Field(..., description="Target Y in pixels")
+
+
+class MouseClickPayload(BaseModel):
+    """Click at absolute coordinates."""
+
+    x: int = Field(..., description="Click X")
+    y: int = Field(..., description="Click Y")
+    button: ButtonName = Field("left", description="left | right | middle")
+    clicks: int = Field(1, description="Click count (>= 1; 2 = double-click)", ge=1)
+
+
+class MouseDragPayload(BaseModel):
+    """Drag from (x1,y1) to (x2,y2)."""
+
+    x1: int = Field(..., description="Start X")
+    y1: int = Field(..., description="Start Y")
+    x2: int = Field(..., description="End X")
+    y2: int = Field(..., description="End Y")
+    button: ButtonName = Field("left", description="Button held during drag")
+    duration_ms: int = Field(300, description="Approximate drag duration in ms", ge=1)
+
+
+class MouseScrollPayload(BaseModel):
+    """Scroll at coordinates."""
+
+    x: int = Field(..., description="Pointer X before scrolling")
+    y: int = Field(..., description="Pointer Y before scrolling")
+    direction: ScrollDir = Field("down", description="up | down | left | right")
+    clicks: int = Field(3, description="Number of scroll ticks", ge=1)
+
+
+def mouse_get(_payload: Any = None) -> dict[str, Any]:
+    """Return the current pointer position.
+
+    Parameters:
+        - (none): Payload may be null or ``{}``.
+
+    Examples:
+        - Read pointer:
+            `desk-proxy do mouse-get '{}'`
+            → {"x": 960, "y": 540}
+
+        - Empty payload:
+            `desk-proxy do mouse-get`
+            → {"x": 12, "y": 34}
+
+        - After a move:
+            `desk-proxy do mouse-get '{}'`
+            → {"x": 100, "y": 200}
+    """
+    return input_api.get_mouse()
+
+
+def mouse_move(p: MouseMovePayload) -> dict[str, Any]:
+    """Move the pointer to absolute coordinates.
+
+    Parameters:
+        - x (int): Target X in pixels.
+        - y (int): Target Y in pixels.
+
+    Examples:
+        - Move to center-ish:
+            `desk-proxy do mouse-move '{"x":960,"y":540}'`
+            → {"x": 960, "y": 540}
+
+        - Origin:
+            `desk-proxy do mouse-move '{"x":0,"y":0}'`
+            → {"x": 0, "y": 0}
+
+        - Button corner:
+            `desk-proxy do mouse-move '{"x":100,"y":200}'`
+            → {"x": 100, "y": 200}
+    """
+    return input_api.move_mouse(p.x, p.y)
+
+
+def mouse_click(p: MouseClickPayload) -> dict[str, Any]:
+    """Move to ``(x, y)`` and click.
+
+    Parameters:
+        - x (int): Click X.
+        - y (int): Click Y.
+        - button (str): ``left`` | ``right`` | ``middle`` (default left).
+        - clicks (int): Repeat count (default 1; use 2 for double-click).
+
+    Examples:
+        - Left click:
+            `desk-proxy do mouse-click '{"x":100,"y":200}'`
+            → {"x": 100, "y": 200, "button": "left", "clicks": 1}
+
+        - Double-click:
+            `desk-proxy do mouse-click '{"x":100,"y":200,"clicks":2}'`
+            → {"x": 100, "y": 200, "button": "left", "clicks": 2}
+
+        - Right-click:
+            `desk-proxy do mouse-click '{"x":50,"y":50,"button":"right"}'`
+            → {"x": 50, "y": 50, "button": "right", "clicks": 1}
+    """
+    return input_api.click(p.x, p.y, button=p.button, clicks=p.clicks)
+
+
+def mouse_drag(p: MouseDragPayload) -> dict[str, Any]:
+    """Drag from ``(x1,y1)`` to ``(x2,y2)`` with a button held.
+
+    Parameters:
+        - x1 (int): Start X.
+        - y1 (int): Start Y.
+        - x2 (int): End X.
+        - y2 (int): End Y.
+        - button (str): Button held (default left).
+        - duration_ms (int): Approximate drag duration in milliseconds.
+
+    Examples:
+        - Short drag:
+            `desk-proxy do mouse-drag '{"x1":10,"y1":10,"x2":100,"y2":100}'`
+            → {"x1": 10, "y1": 10, "x2": 100, "y2": 100, "button": "left", "duration_ms": 300}
+
+        - Fast drag:
+            `desk-proxy do mouse-drag '{"x1":0,"y1":0,"x2":50,"y2":50,"duration_ms":50}'`
+            → {"x1": 0, "y1": 0, "x2": 50, "y2": 50, "button": "left", "duration_ms": 50}
+
+        - Middle-button drag:
+            `desk-proxy do mouse-drag '{"x1":20,"y1":20,"x2":80,"y2":80,"button":"middle"}'`
+            → {"x1": 20, "y1": 20, "x2": 80, "y2": 80, "button": "middle", "duration_ms": 300}
+    """
+    return input_api.drag(
+        p.x1, p.y1, p.x2, p.y2, button=p.button, duration_ms=p.duration_ms
+    )
+
+
+def mouse_scroll(p: MouseScrollPayload) -> dict[str, Any]:
+    """Scroll at coordinates.
+
+    Parameters:
+        - x (int): Pointer X before scrolling.
+        - y (int): Pointer Y before scrolling.
+        - direction (str): ``up`` | ``down`` | ``left`` | ``right`` (default down).
+        - clicks (int): Number of scroll ticks (default 3).
+
+    Examples:
+        - Scroll down:
+            `desk-proxy do mouse-scroll '{"x":500,"y":500}'`
+            → {"x": 500, "y": 500, "direction": "down", "clicks": 3}
+
+        - Scroll up twice:
+            `desk-proxy do mouse-scroll '{"x":500,"y":500,"direction":"up","clicks":2}'`
+            → {"x": 500, "y": 500, "direction": "up", "clicks": 2}
+
+        - Horizontal:
+            `desk-proxy do mouse-scroll '{"x":100,"y":100,"direction":"right","clicks":1}'`
+            → {"x": 100, "y": 100, "direction": "right", "clicks": 1}
+    """
+    return input_api.scroll(p.x, p.y, direction=p.direction, clicks=p.clicks)
+
+
+ACTIONS = [
+    action_def("mouse-get", None, mouse_get, group="Mouse"),
+    action_def("mouse-move", MouseMovePayload, mouse_move, group="Mouse"),
+    action_def("mouse-click", MouseClickPayload, mouse_click, group="Mouse"),
+    action_def("mouse-drag", MouseDragPayload, mouse_drag, group="Mouse"),
+    action_def("mouse-scroll", MouseScrollPayload, mouse_scroll, group="Mouse"),
+]