simdrive 0.2.0a1__py3-none-any.whl

simdrive/__init__.py

@@ -0,0 +1,3 @@
+"""simdrive — hand your iOS simulator to your agent."""
+
+__version__ = "0.2.0a1"

simdrive/act.py

@@ -0,0 +1,245 @@
+"""Synthetic input dispatch.
+
+Internal module. Coordinates passed in are screenshot pixels from the most
+recent observe; translated to logical iOS device points using the cached
+scale, then dispatched via the HID-injection backend.
+
+Three backends, in preference order:
+  1. hid    — bundled native helper (real UITouch events; focuses TextFields)
+  2. cliclick — synthetic mouse via the macOS window (fallback)
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import time
+from typing import Iterable, Optional
+
+from . import hid_inject, sim
+from .sim import cliclick_path
+from .window import WindowBounds, activate, get_bounds
+
+
+class ActError(RuntimeError):
+    """Raised when an act dispatch fails."""
+
+
+# Cache of UDID → (logical_w, logical_h, scale) from hid_inject.device_size_points()
+_DEVICE_GEOM_CACHE: dict[str, tuple[float, float, float]] = {}
+
+
+def _backend() -> str:
+    """Return which backend will be used. Override via SIMDRIVE_INPUT_BACKEND."""
+    requested = os.environ.get("SIMDRIVE_INPUT_BACKEND", "").lower()
+    if requested == "cliclick":
+        return "cliclick"
+    if hid_inject.available():
+        return "hid"
+    return "cliclick"
+
+
+def _device_geom(udid: str) -> tuple[float, float, float]:
+    cached = _DEVICE_GEOM_CACHE.get(udid)
+    if cached is not None:
+        return cached
+    geom = hid_inject.device_size_points(udid)
+    _DEVICE_GEOM_CACHE[udid] = geom
+    return geom
+
+
+def _pixels_to_points(udid: str, pixel_x: int, pixel_y: int, screenshot_w: int, screenshot_h: int) -> tuple[float, float]:
+    """Map a screenshot pixel coord to logical iOS device points for the HID path."""
+    if screenshot_w <= 0 or screenshot_h <= 0:
+        raise ActError(f"Invalid screenshot size: {screenshot_w}x{screenshot_h}")
+    logical_w, logical_h, _scale = _device_geom(udid)
+    px = (pixel_x / screenshot_w) * logical_w
+    py = (pixel_y / screenshot_h) * logical_h
+    return px, py
+
+
+def _pixels_to_screen(
+    bounds: WindowBounds, pixel_x: int, pixel_y: int, screenshot_w: int, screenshot_h: int
+) -> tuple[int, int]:
+    if screenshot_w <= 0 or screenshot_h <= 0:
+        raise ActError(f"Invalid screenshot size: {screenshot_w}x{screenshot_h}")
+    sx = bounds.x + (pixel_x / screenshot_w) * bounds.width
+    sy = bounds.y + (pixel_y / screenshot_h) * bounds.height
+    return int(round(sx)), int(round(sy))
+
+
+def _run_cliclick(args: Iterable[str], timeout: float = 5.0) -> None:
+    cli = cliclick_path()
+    cmd = [cli, *args]
+    res = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, check=False)
+    if res.returncode != 0:
+        raise ActError(f"cliclick failed (rc={res.returncode}): {res.stderr.strip() or res.stdout.strip()}")
+
+
+# ----------------------------- Public API ------------------------------ #
+
+
+def tap(pixel_x: int, pixel_y: int, screenshot_w: int, screenshot_h: int, udid: Optional[str] = None) -> tuple[int, int]:
+    """Click at screenshot-pixel coordinates. Returns the macOS screen coords used (or 0,0 for HID path)."""
+    if _backend() == "hid" and udid:
+        x_pt, y_pt = _pixels_to_points(udid, pixel_x, pixel_y, screenshot_w, screenshot_h)
+        hid_inject.tap(udid, x_pt, y_pt)
+        return (0, 0)
+
+    bounds = get_bounds()
+    sx, sy = _pixels_to_screen(bounds, pixel_x, pixel_y, screenshot_w, screenshot_h)
+    activate()
+    time.sleep(0.15)
+    _run_cliclick([f"c:{sx},{sy}"])
+    return sx, sy
+
+
+def swipe(
+    x1: int, y1: int, x2: int, y2: int, screenshot_w: int, screenshot_h: int, duration_ms: int = 300,
+    udid: Optional[str] = None,
+) -> None:
+    if _backend() == "hid" and udid:
+        x1p, y1p = _pixels_to_points(udid, x1, y1, screenshot_w, screenshot_h)
+        x2p, y2p = _pixels_to_points(udid, x2, y2, screenshot_w, screenshot_h)
+        steps = max(4, duration_ms // 25)
+        hid_inject.swipe(udid, x1p, y1p, x2p, y2p, steps=steps, step_delay_ms=25)
+        return
+
+    bounds = get_bounds()
+    sx1, sy1 = _pixels_to_screen(bounds, x1, y1, screenshot_w, screenshot_h)
+    sx2, sy2 = _pixels_to_screen(bounds, x2, y2, screenshot_w, screenshot_h)
+    activate()
+    time.sleep(0.15)
+    duration_ms = max(50, min(duration_ms, 5000))
+    steps = max(2, duration_ms // 30)
+    moves: list[str] = []
+    for i in range(1, steps + 1):
+        t = i / steps
+        mx = int(round(sx1 + (sx2 - sx1) * t))
+        my = int(round(sy1 + (sy2 - sy1) * t))
+        moves.append(f"m:{mx},{my}")
+    args = ["-w", "30", f"dd:{sx1},{sy1}", *moves, f"du:{sx2},{sy2}"]
+    _run_cliclick(args, timeout=10.0)
+
+
+def type_text(text: str, udid: Optional[str] = None) -> None:
+    """Send keystrokes. Caller is responsible for tapping a focused field first.
+
+    For non-ASCII characters (accented, emoji, non-Latin), falls back to the
+    pasteboard path: simctl pbcopy + Cmd-V — preserves the focused-field state
+    and works around the HID keyboard's US-ASCII-only key map.
+    """
+    if not text:
+        return
+
+    is_ascii = all(ord(c) < 128 for c in text)
+
+    if _backend() == "hid" and udid:
+        if is_ascii:
+            hid_inject.type_text(udid, text)
+            return
+        # Non-ASCII path: pbcopy + paste-shortcut
+        sim.set_pasteboard(udid, text)
+        time.sleep(0.05)
+        # Cmd-V via HID — issue Cmd modifier hold + V keypress
+        # HID usage 0xE3 = Left Cmd; 0x19 = V
+        _hid_paste(udid)
+        return
+
+    activate()
+    time.sleep(0.15)
+    _run_cliclick(["t:" + text])
+
+
+def _hid_paste(udid: str) -> None:
+    """Cmd-V via the HID helper — works in background mode."""
+    hid_inject.chord(udid, "cmd", "v")
+
+
+_CLICLICK_KEY_MAP = {
+    "return": "kp:return",
+    "enter": "kp:return",
+    "tab": "kp:tab",
+    "escape": "kp:esc",
+    "esc": "kp:esc",
+    "space": "kp:space",
+    "delete": "kp:delete",
+    "backspace": "kp:delete",
+    "arrow-up": "kp:arrow-up",
+    "arrow-down": "kp:arrow-down",
+    "arrow-left": "kp:arrow-left",
+    "arrow-right": "kp:arrow-right",
+}
+
+# HID usage codes for special keys (US layout, HID Keyboard/Keypad page)
+_HID_KEY_MAP = {
+    "return": 40,
+    "enter": 40,
+    "tab": 43,
+    "escape": 41,
+    "esc": 41,
+    "space": 44,
+    "delete": 42,
+    "backspace": 42,
+    "arrow-up": 82,
+    "arrow-down": 81,
+    "arrow-left": 80,
+    "arrow-right": 79,
+}
+
+_DEVICE_BUTTONS = {"home", "lock", "siri"}  # buttons routed to hid_inject.press_button
+
+# Sim-only buttons that go through Simulator's "Device" menu (cliclick fallback path).
+_DEVICE_MENU_KEYS = {
+    "home": "Home",
+    "lock": "Lock",
+    "shake": "Shake",
+    "siri": "Siri",
+    "app-switcher": "App Switcher",
+    "screenshot": "Trigger Screenshot",
+    "rotate-left": "Rotate Left",
+    "rotate-right": "Rotate Right",
+    "action-button": "Action Button",
+}
+
+
+def press_key(key: str, udid: Optional[str] = None) -> None:
+    key_lower = key.lower().strip()
+
+    if _backend() == "hid" and udid:
+        if key_lower in _DEVICE_BUTTONS:
+            hid_inject.press_button(udid, key_lower)
+            return
+        hid_code = _HID_KEY_MAP.get(key_lower)
+        if hid_code is not None:
+            hid_inject.press_key(udid, hid_code)
+            return
+        # fall through to cliclick path for unknown keys
+
+    if key_lower in _DEVICE_MENU_KEYS:
+        _menu_click("Device", _DEVICE_MENU_KEYS[key_lower])
+        return
+
+    cli_arg = _CLICLICK_KEY_MAP.get(key_lower)
+    if cli_arg is None:
+        raise ActError(
+            f"unsupported key: {key!r}. Supported: {sorted(_CLICLICK_KEY_MAP)} "
+            f"+ {sorted(_DEVICE_MENU_KEYS)}"
+        )
+    activate()
+    time.sleep(0.15)
+    _run_cliclick([cli_arg])
+
+
+def _menu_click(menu_title: str, item_title: str) -> None:
+    script = f'''
+    tell application "System Events"
+      tell process "Simulator"
+        click menu item "{item_title}" of menu "{menu_title}" of menu bar 1
+      end tell
+    end tell
+    '''
+    res = subprocess.run(
+        ["osascript", "-e", script], capture_output=True, text=True, timeout=5.0, check=False
+    )
+    if res.returncode != 0:
+        raise ActError(f"menu click {menu_title} > {item_title} failed: {res.stderr.strip()}")

simdrive/device.py

@@ -0,0 +1,235 @@
+"""Real-device backend — screenshot + logs + app lifecycle for connected iPhones / iPads.
+
+Internal module. Mirrors the surface of ``sim.py`` but for physical devices
+reachable via Apple's ``devicectl`` and libimobiledevice. Touch input is NOT
+implemented here; that's a v0.2.x follow-up that needs WebDriverAgent.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+class DeviceError(RuntimeError):
+    """Raised when a real-device operation fails."""
+
+
+@dataclass(frozen=True)
+class RealDevice:
+    udid: str
+    name: str
+    model: str
+    transport: Optional[str]  # "wired" | "localNetwork" | None
+    state: str  # "available" | "unavailable"
+
+    @property
+    def is_available(self) -> bool:
+        return self.state == "available"
+
+
+# ----------------------- Tool path resolution ----------------------- #
+
+
+def _which(name: str) -> Optional[str]:
+    p = shutil.which(name)
+    if p:
+        return p
+    # Common Homebrew locations
+    for cand in (f"/opt/homebrew/bin/{name}", f"/usr/local/bin/{name}"):
+        if Path(cand).exists():
+            return cand
+    return None
+
+
+def libimobiledevice_available() -> tuple[bool, list[str]]:
+    """Returns (ok, missing_tools)."""
+    needed = ["idevice_id", "idevicescreenshot", "idevicesyslog", "ideviceimagemounter"]
+    missing = [n for n in needed if not _which(n)]
+    return (not missing, missing)
+
+
+def devicectl_available() -> bool:
+    return _which("xcrun") is not None  # devicectl ships with Xcode
+
+
+# ----------------------- Device discovery ----------------------- #
+
+
+def list_devices() -> list[RealDevice]:
+    """Enumerate all paired devices (Apple Silicon + libimobiledevice path)."""
+    if not devicectl_available():
+        raise DeviceError("xcrun (Xcode) not found")
+
+    import tempfile
+    with tempfile.NamedTemporaryFile(suffix=".json", delete=False) as tf:
+        json_out = tf.name
+    try:
+        res = subprocess.run(
+            ["xcrun", "devicectl", "list", "devices",
+             "--json-output", json_out, "--quiet"],
+            capture_output=True, text=True, timeout=10.0, check=False,
+        )
+        if res.returncode != 0:
+            raise DeviceError(f"devicectl list failed: {res.stderr.strip()}")
+        try:
+            with open(json_out) as f:
+                data = json.load(f)
+        except (OSError, json.JSONDecodeError) as exc:
+            raise DeviceError(f"devicectl list JSON unreadable: {exc}") from exc
+    finally:
+        try: os.unlink(json_out)
+        except OSError: pass
+
+    out: list[RealDevice] = []
+    for d in data.get("result", {}).get("devices", []):
+        hw = d.get("hardwareProperties", {}) or {}
+        dp = d.get("deviceProperties", {}) or {}
+        cp = d.get("connectionProperties", {}) or {}
+        out.append(RealDevice(
+            udid=hw.get("udid", ""),
+            name=dp.get("name", "<unknown>"),
+            model=hw.get("marketingName") or hw.get("productType") or "<unknown>",
+            transport=cp.get("transportType"),
+            state="available" if d.get("connectionProperties", {}).get("transportType") else "unavailable",
+        ))
+    return out
+
+
+def find_device(udid: str) -> Optional[RealDevice]:
+    for d in list_devices():
+        if d.udid == udid or d.udid.replace("-", "") == udid.replace("-", ""):
+            return d
+    return None
+
+
+# ----------------------- Screenshot ----------------------- #
+
+
+def screenshot(udid: str, dest_path: Path) -> Path:
+    """Capture a PNG screenshot to dest_path.
+
+    `idevicescreenshot` writes TIFF by default; pass an explicit `.png`
+    output path and it will encode as PNG.
+    """
+    bin_path = _which("idevicescreenshot")
+    if not bin_path:
+        raise DeviceError(
+            "idevicescreenshot not found. Install with: brew install libimobiledevice"
+        )
+    dest_path.parent.mkdir(parents=True, exist_ok=True)
+    res = subprocess.run(
+        [bin_path, "-u", udid, str(dest_path)],
+        capture_output=True, text=True, timeout=15.0, check=False,
+    )
+    if res.returncode != 0:
+        msg = res.stderr.strip() or res.stdout.strip()
+        if "Developer disk image" in msg or "Invalid service" in msg:
+            raise DeviceError(
+                f"screenshot service unavailable (Developer Disk Image not mounted). "
+                f"Run: ideviceimagemounter -u {udid} <path-to-DDI>. Original error: {msg}"
+            )
+        raise DeviceError(f"idevicescreenshot failed: {msg}")
+    if not dest_path.exists():
+        raise DeviceError(f"screenshot reported success but file missing: {dest_path}")
+    return dest_path
+
+
+# ----------------------- Logs ----------------------- #
+
+
+def get_log_tail(udid: str, lines: int = 50, predicate: Optional[str] = None) -> str:
+    """Capture a short live tail of syslog from the device.
+
+    `idevicesyslog` streams indefinitely, so we read for ~1 second and trim
+    to the most recent `lines` lines. `predicate`, when given, is applied as
+    a simple substring filter (NSPredicate on real device requires log
+    framework, not idevicesyslog).
+    """
+    bin_path = _which("idevicesyslog")
+    if not bin_path:
+        raise DeviceError(
+            "idevicesyslog not found. Install with: brew install libimobiledevice"
+        )
+
+    proc = subprocess.Popen(
+        [bin_path, "-u", udid],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.DEVNULL,
+        text=True,
+    )
+    try:
+        time.sleep(1.0)
+        proc.terminate()
+        out, _ = proc.communicate(timeout=2.0)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        out = ""
+
+    out_lines = (out or "").splitlines()
+    if predicate:
+        out_lines = [ln for ln in out_lines if predicate in ln]
+    return "\n".join(out_lines[-lines:])
+
+
+# ----------------------- App lifecycle ----------------------- #
+
+
+def install_app(udid: str, app_path: Path) -> None:
+    if not Path(app_path).exists():
+        raise DeviceError(f"app bundle not found: {app_path}")
+    res = subprocess.run(
+        ["xcrun", "devicectl", "device", "install", "app",
+         "--device", udid, str(app_path)],
+        capture_output=True, text=True, timeout=120.0, check=False,
+    )
+    if res.returncode != 0:
+        raise DeviceError(f"devicectl install failed: {res.stderr.strip() or res.stdout.strip()}")
+
+
+def launch_app(udid: str, bundle_id: str) -> int:
+    res = subprocess.run(
+        ["xcrun", "devicectl", "device", "process", "launch",
+         "--device", udid, "--start-stopped=false", bundle_id,
+         "--json-output", "/dev/stdout"],
+        capture_output=True, text=True, timeout=30.0, check=False,
+    )
+    if res.returncode != 0:
+        raise DeviceError(f"devicectl launch failed: {res.stderr.strip() or res.stdout.strip()}")
+    try:
+        data = json.loads(res.stdout)
+        return int(data.get("result", {}).get("process", {}).get("processIdentifier", 0))
+    except (json.JSONDecodeError, ValueError, TypeError):
+        return 0
+
+
+def terminate_app(udid: str, bundle_id: str) -> None:
+    # devicectl process kill needs PID; we don't track PIDs persistently, so
+    # do a best-effort signal via terminate-by-bundle (Xcode 26+ supports this).
+    subprocess.run(
+        ["xcrun", "devicectl", "device", "process", "signal",
+         "--device", udid, "--signal", "SIGTERM", "--bundle-id", bundle_id],
+        capture_output=True, timeout=10.0, check=False,
+    )
+
+
+# ----------------------- Developer Disk Image ----------------------- #
+
+
+def is_developer_disk_mounted(udid: str) -> bool:
+    """Best-effort check via idevicescreenshot — if it succeeds, DDI is mounted."""
+    bin_path = _which("idevicescreenshot")
+    if not bin_path:
+        return False
+    # `-l` lists capability without writing; not all idevicescreenshot builds
+    # support it. Fall back to a probe: try a quick -h, see if service errors.
+    res = subprocess.run(
+        [bin_path, "-u", udid, "/dev/null"],
+        capture_output=True, text=True, timeout=5.0, check=False,
+    )
+    return "Invalid service" not in (res.stderr + res.stdout)

simdrive/errors.py

@@ -0,0 +1,142 @@
+"""Structured error model for simdrive.
+
+Every error raised by an MCP tool can be caught as a `SimdriveError` and
+inspected via its `.code` (machine-friendly) + `.message` (human-readable).
+The MCP server serializes these to a JSON envelope so agents can switch
+on the code without parsing prose.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class SimdriveError(Exception):
+    """Base class for every error simdrive surfaces.
+
+    Subclass via `.code` rather than the Python class — code strings are the
+    stable contract; class hierarchy is implementation-internal.
+    """
+    code: str
+    message: str
+    details: dict = field(default_factory=dict)
+
+    def __str__(self) -> str:
+        return f"[{self.code}] {self.message}"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"ok": False, "error": {"code": self.code, "message": self.message, "details": self.details}}
+
+
+# --------- Standard error codes (the agent contract) --------- #
+
+
+def no_session(session_id: str) -> SimdriveError:
+    return SimdriveError(
+        code="no_session",
+        message=f"unknown session_id {session_id!r}. Call session_start first.",
+        details={"session_id": session_id},
+    )
+
+
+def no_device(query: dict) -> SimdriveError:
+    return SimdriveError(
+        code="no_device",
+        message=f"no booted simulator matched {query}. Pass `device` to boot one.",
+        details={"query": query},
+    )
+
+
+def sim_unhealthy(udid: str, reason: str) -> SimdriveError:
+    return SimdriveError(
+        code="sim_unhealthy",
+        message=(
+            f"simulator {udid} is in a degraded state ({reason}). "
+            "Recovery: quit Simulator.app and `xcrun simctl shutdown all && xcrun simctl boot {udid}`."
+        ),
+        details={"udid": udid, "reason": reason},
+    )
+
+
+def hid_unavailable(reason: str) -> SimdriveError:
+    return SimdriveError(
+        code="hid_unavailable",
+        message=(
+            f"native HID helper unavailable: {reason}. "
+            "Reinstall simdrive (the bundled binary is required) or `cd simdrive/native && make`."
+        ),
+        details={"reason": reason},
+    )
+
+
+def target_not_found(form: str, query: Any, available: Optional[list] = None) -> SimdriveError:
+    return SimdriveError(
+        code="target_not_found",
+        message=(
+            f"no {form} match for {query!r} in last observe. "
+            f"Available: {available[:30] if available else '(none)'}"
+        ),
+        details={"form": form, "query": query, "available": available},
+    )
+
+
+def missing_target() -> SimdriveError:
+    return SimdriveError(
+        code="missing_target",
+        message="tap target required: provide {x, y}, {mark: <id>}, or {text: <query>}",
+        details={},
+    )
+
+
+def invalid_argument(field: str, value: Any, why: str) -> SimdriveError:
+    return SimdriveError(
+        code="invalid_argument",
+        message=f"invalid {field}={value!r}: {why}",
+        details={"field": field, "value": value, "why": why},
+    )
+
+
+def already_recording(session_id: str, name: str) -> SimdriveError:
+    return SimdriveError(
+        code="already_recording",
+        message=f"session {session_id} already recording {name!r}; call record_stop first.",
+        details={"session_id": session_id, "name": name},
+    )
+
+
+def not_recording(session_id: str) -> SimdriveError:
+    return SimdriveError(
+        code="not_recording",
+        message=f"session {session_id} is not recording.",
+        details={"session_id": session_id},
+    )
+
+
+def recording_not_found(name: str, path: str) -> SimdriveError:
+    return SimdriveError(
+        code="recording_not_found",
+        message=f"recording {name!r} not found at {path}",
+        details={"name": name, "path": path},
+    )
+
+
+def device_input_unavailable(action: str) -> SimdriveError:
+    return SimdriveError(
+        code="device_input_unavailable",
+        message=(
+            f"'{action}' on a real device is not yet supported. simdrive v0.1.x "
+            "drives observe + logs + app lifecycle on real devices, but synthetic "
+            "touch/keyboard input requires WebDriverAgent. Coming in v0.2; track "
+            "in docs/REAL_DEVICE_FEASIBILITY.md."
+        ),
+        details={"action": action},
+    )
+
+
+def replay_drift_halt(step_id: int, similarity: float, threshold: float) -> SimdriveError:
+    return SimdriveError(
+        code="replay_drift_halt",
+        message=f"replay halted at step {step_id}: similarity {similarity:.3f} below threshold {threshold:.3f}",
+        details={"step_id": step_id, "similarity": similarity, "threshold": threshold},
+    )