codeaway 0.1.0__py3-none-any.whl

codeaway/__init__.py

@@ -0,0 +1,4 @@
+from importlib.metadata import version
+
+
+__version__ = version("codeaway")

codeaway/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codeaway/agents.py

@@ -0,0 +1,427 @@
+import math
+import os
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Literal, Protocol
+
+from PIL import Image
+
+from .desktop import (
+    AccessibilityAction,
+    AccessibilityNode,
+    DesktopBackend,
+    DesktopWindow,
+    FractionalRegion,
+    PixelPoint,
+)
+
+
+@dataclass(frozen=True)
+class SurfaceMap:
+    sidebar: FractionalRegion
+    conversation: FractionalRegion
+    composer: FractionalRegion
+
+
+@dataclass(frozen=True)
+class AgentTarget:
+    agent_id: str
+    window: DesktopWindow
+    surfaces: SurfaceMap
+
+
+@dataclass(frozen=True)
+class TaskSnapshot:
+    title: str
+    state: Literal["done", "busy", "idle", "unknown"]
+    worktree: bool = False
+    selected: bool = False
+
+
+@dataclass(frozen=True)
+class ProjectSnapshot:
+    name: str
+    host: str | None
+    connected: bool
+    state: Literal["connected", "busy", "idle"]
+    expanded: bool
+    tasks: tuple[TaskSnapshot, ...]
+
+
+@dataclass(frozen=True)
+class AgentSnapshot:
+    available: bool
+    source: str
+    projects: tuple[ProjectSnapshot, ...]
+    captured_at: str
+    error: str | None = None
+
+
+@dataclass(frozen=True)
+class NavigationAction:
+    kind: Literal["project", "task"]
+    project: str
+    title: str | None = None
+    expanded: bool | None = None
+
+
+@dataclass(frozen=True)
+class ClickAction:
+    surface: Literal["sidebar", "conversation"]
+    x: float
+    y: float
+
+
+class AgentBackend(Protocol):
+    id: str
+
+    def matches(self, window: DesktopWindow) -> bool: ...
+
+    def default_surfaces(self, window: DesktopWindow) -> SurfaceMap: ...
+
+    def inspect(self, desktop: DesktopBackend, target: AgentTarget) -> AgentSnapshot: ...
+
+    def navigate(
+        self, desktop: DesktopBackend, target: AgentTarget, action: NavigationAction
+    ) -> None: ...
+
+    def click(
+        self, desktop: DesktopBackend, target: AgentTarget, action: ClickAction
+    ) -> None: ...
+
+    def scroll(self, desktop: DesktopBackend, target: AgentTarget, amount: int) -> None: ...
+
+    def send(self, desktop: DesktopBackend, target: AgentTarget, text: str) -> None: ...
+
+
+class AgentRegistry:
+    def __init__(self, agents: list[AgentBackend] | tuple[AgentBackend, ...]):
+        self._agents = tuple(agents)
+
+    def discover(self, desktop: DesktopBackend) -> list[AgentTarget]:
+        windows = desktop.list_windows()
+        return [
+            AgentTarget(agent.id, window, agent.default_surfaces(window))
+            for window in windows
+            for agent in self._agents
+            if agent.matches(window)
+        ]
+
+    def resolve(
+        self,
+        desktop: DesktopBackend,
+        agent_id: str,
+        process_path: str,
+        title_hint: str | None,
+        surfaces: SurfaceMap,
+    ) -> AgentTarget | None:
+        agent = next((agent for agent in self._agents if agent.id == agent_id), None)
+        if agent is None:
+            return None
+        windows = desktop.list_windows()
+        normalized_process_path = os.path.normcase(os.path.normpath(process_path))
+        candidates = [
+            window
+            for window in windows
+            if os.path.normcase(os.path.normpath(window.process_path))
+            == normalized_process_path
+            and agent.matches(window)
+        ]
+        if title_hint is None:
+            return None
+        exact_matches = [window for window in candidates if window.title == title_hint]
+        if len(exact_matches) != 1:
+            return None
+        return AgentTarget(agent_id, exact_matches[0], surfaces)
+
+
+class TargetUnavailable(RuntimeError):
+    """The selected window could not be activated safely."""
+
+
+@dataclass(frozen=True)
+class _ProjectRow:
+    node: AccessibilityNode
+    name: str
+    host: str | None
+    tasks: tuple[AccessibilityNode, ...]
+
+
+class CodexAgent:
+    id = "codex"
+
+    _PROJECT_CLASS_TOKENS = frozenset({"group/folder-row", "sidebar-item"})
+    _TASK_CLASS_TOKENS = frozenset({"sidebar-item", "py-row-y"})
+    _WORKTREE_CLASS_TOKENS = frozenset(
+        {"icon-2xs", "text-codex-description", "no-drag", "shrink-0"}
+    )
+    _BUSY_CLASS_TOKENS = frozenset({"icon-xs", "shrink-0"})
+
+    def matches(self, window: DesktopWindow) -> bool:
+        path = window.process_path.replace("/", "\\").casefold()
+        return "openai.codex_" in path or "\\openai\\codex\\" in path
+
+    def default_surfaces(self, window: DesktopWindow) -> SurfaceMap:
+        del window
+        return SurfaceMap(
+            sidebar=FractionalRegion(0.00, 0.03, 0.21, 0.97),
+            conversation=FractionalRegion(0.21, 0.08, 0.79, 0.82),
+            composer=FractionalRegion(0.33, 0.90, 0.55, 0.06),
+        )
+
+    @staticmethod
+    def _position(node: AccessibilityNode) -> tuple[int, int]:
+        return node.region.y, node.region.x
+
+    @staticmethod
+    def _same_row(first: AccessibilityNode, second: AccessibilityNode) -> bool:
+        return (
+            first.region.y < second.region.y + second.region.height
+            and second.region.y < first.region.y + first.region.height
+        )
+
+    @staticmethod
+    def _overlaps_horizontally(
+        first: AccessibilityNode, second: AccessibilityNode
+    ) -> bool:
+        return (
+            first.region.x < second.region.x + second.region.width
+            and second.region.x < first.region.x + first.region.width
+        )
+
+    @staticmethod
+    def _has_class_tokens(class_name: str, required_tokens: frozenset[str]) -> bool:
+        return required_tokens.issubset(class_name.split())
+
+    def _project_identity(
+        self, project: AccessibilityNode, nodes: list[AccessibilityNode]
+    ) -> tuple[str, str | None]:
+        names: list[str] = []
+        for node in nodes:
+            if node.role.casefold() not in {"button", "buttoncontrol"}:
+                continue
+            if not self._same_row(project, node) or not self._overlaps_horizontally(
+                project, node
+            ):
+                continue
+            for prefix in ("Start new chat in ", "Project actions for "):
+                if node.name.startswith(prefix):
+                    names.append(node.name[len(prefix) :])
+        candidates = [
+            name
+            for name in names
+            if project.name == name or project.name.startswith(f"{name} ")
+        ]
+        name = max(candidates, key=len) if candidates else project.name
+        suffix = project.name[len(name) :].strip()
+        return name, suffix or None
+
+    def _rows(self, nodes: list[AccessibilityNode]) -> tuple[_ProjectRow, ...]:
+        projects = sorted(
+            (
+                node
+                for node in nodes
+                if self._has_class_tokens(node.class_name, self._PROJECT_CLASS_TOKENS)
+            ),
+            key=self._position,
+        )
+        tasks = sorted(
+            (
+                node
+                for node in nodes
+                if self._has_class_tokens(node.class_name, self._TASK_CLASS_TOKENS)
+                and not self._has_class_tokens(
+                    node.class_name, self._PROJECT_CLASS_TOKENS
+                )
+                and node.name not in {"Pin chat", "Archive chat"}
+            ),
+            key=self._position,
+        )
+        rows: list[_ProjectRow] = []
+        for index, project in enumerate(projects):
+            next_y = projects[index + 1].region.y if index + 1 < len(projects) else None
+            project_tasks = tuple(
+                task
+                for task in tasks
+                if task.region.y >= project.region.y
+                and (next_y is None or task.region.y < next_y)
+            )
+            name, host = self._project_identity(project, nodes)
+            rows.append(_ProjectRow(project, name, host, project_tasks))
+        return tuple(rows)
+
+    def _has_class_on_row(
+        self,
+        task: AccessibilityNode,
+        nodes: list[AccessibilityNode],
+        required_tokens: frozenset[str],
+    ) -> bool:
+        return any(
+            self._has_class_tokens(node.class_name, required_tokens)
+            and self._same_row(task, node)
+            and self._overlaps_horizontally(task, node)
+            for node in nodes
+        )
+
+    @staticmethod
+    def _is_done(
+        task: AccessibilityNode,
+        sidebar_region,
+        sidebar_image: Image.Image | None,
+    ) -> bool:
+        if sidebar_image is None:
+            return False
+        left = max(0, task.region.x - sidebar_region.x)
+        right = min(sidebar_image.width, task.region.x + task.region.width - sidebar_region.x)
+        top = max(0, task.region.y - sidebar_region.y)
+        bottom = min(sidebar_image.height, task.region.y + task.region.height - sidebar_region.y)
+        left = max(left, right - 64)
+        if left >= right or top >= bottom:
+            return False
+        blue_pixels = 0
+        pixels = sidebar_image.convert("RGB")
+        for y in range(top, bottom):
+            for x in range(left, right):
+                red, green, blue = pixels.getpixel((x, y))
+                if blue >= 150 and blue >= red + 45 and blue >= green + 20:
+                    blue_pixels += 1
+                    if blue_pixels >= 6:
+                        return True
+        return False
+
+    def inspect(self, desktop: DesktopBackend, target: AgentTarget) -> AgentSnapshot:
+        nodes = desktop.accessibility_tree(target.window)
+        sidebar_region = target.surfaces.sidebar.resolve(target.window.region)
+        sidebar_image = None
+        if desktop.is_foreground(target.window):
+            try:
+                sidebar_image = desktop.capture(sidebar_region)
+            except Exception:
+                sidebar_image = None
+
+        projects: list[ProjectSnapshot] = []
+        for row in self._rows(nodes):
+            tasks: list[TaskSnapshot] = []
+            for task in row.tasks:
+                busy = self._has_class_on_row(task, nodes, self._BUSY_CLASS_TOKENS)
+                state: Literal["done", "busy", "idle", "unknown"]
+                if self._is_done(task, sidebar_region, sidebar_image):
+                    state = "done"
+                elif busy:
+                    state = "busy"
+                else:
+                    state = "unknown"
+                tasks.append(
+                    TaskSnapshot(
+                        title=task.name,
+                        state=state,
+                        worktree=self._has_class_on_row(
+                            task, nodes, self._WORKTREE_CLASS_TOKENS
+                        ),
+                        selected="bg-primary-ghost-hover" in task.class_name,
+                    )
+                )
+            connected = any(
+                node.role.casefold() in {"image", "imagecontrol"}
+                and node.name == "Connected"
+                and self._same_row(row.node, node)
+                and self._overlaps_horizontally(row.node, node)
+                for node in nodes
+            )
+            project_state: Literal["connected", "busy", "idle"]
+            if connected:
+                project_state = "connected"
+            elif any(task.state == "busy" for task in tasks):
+                project_state = "busy"
+            else:
+                project_state = "idle"
+            projects.append(
+                ProjectSnapshot(
+                    name=row.name,
+                    host=row.host,
+                    connected=connected,
+                    state=project_state,
+                    expanded=row.node.expanded is True,
+                    tasks=tuple(tasks),
+                )
+            )
+        return AgentSnapshot(
+            available=True,
+            source="accessibility+pixels" if sidebar_image is not None else "accessibility",
+            projects=tuple(projects),
+            captured_at=datetime.now(timezone.utc).isoformat(),
+        )
+
+    @staticmethod
+    def _activate(desktop: DesktopBackend, target: AgentTarget) -> None:
+        if not desktop.activate(target.window):
+            raise TargetUnavailable("the selected Codex window is unavailable")
+
+    def navigate(
+        self,
+        desktop: DesktopBackend,
+        target: AgentTarget,
+        action: NavigationAction,
+    ) -> None:
+        self._activate(desktop, target)
+        rows = self._rows(desktop.accessibility_tree(target.window))
+        project = next((row for row in rows if row.name == action.project), None)
+        if project is None:
+            raise TargetUnavailable(f"project {action.project!r} is unavailable")
+        if action.kind == "project":
+            if action.expanded is None:
+                raise ValueError("project navigation requires an expanded state")
+            if project.node.expanded is action.expanded:
+                return
+            accessibility_action = (
+                AccessibilityAction.EXPAND
+                if action.expanded
+                else AccessibilityAction.COLLAPSE
+            )
+            desktop.accessibility_action(project.node, accessibility_action)
+            return
+        if action.title is None:
+            raise ValueError("task navigation requires a title")
+        task = next((task for task in project.tasks if task.name == action.title), None)
+        if task is None:
+            raise TargetUnavailable(f"task {action.title!r} is unavailable")
+        desktop.accessibility_action(task, AccessibilityAction.INVOKE)
+
+    def click(
+        self,
+        desktop: DesktopBackend,
+        target: AgentTarget,
+        action: ClickAction,
+    ) -> None:
+        self._activate(desktop, target)
+        surface = getattr(target.surfaces, action.surface).resolve(target.window.region)
+        if surface.width <= 0 or surface.height <= 0:
+            raise TargetUnavailable("the calibrated surface has no usable pixels")
+        point = PixelPoint(
+            surface.x + min(surface.width - 1, math.floor(surface.width * action.x)),
+            surface.y + min(surface.height - 1, math.floor(surface.height * action.y)),
+        )
+        if action.surface == "sidebar" and surface.x + surface.width - point.x <= 64:
+            offset = max(24, round(target.window.region.width * 0.025))
+            point = PixelPoint(max(surface.x, point.x - offset), point.y)
+        desktop.click(target.window, point)
+
+    def scroll(
+        self,
+        desktop: DesktopBackend,
+        target: AgentTarget,
+        amount: int,
+    ) -> None:
+        self._activate(desktop, target)
+        conversation = target.surfaces.conversation.resolve(target.window.region)
+        desktop.scroll(target.window, conversation.center, amount)
+
+    def send(
+        self,
+        desktop: DesktopBackend,
+        target: AgentTarget,
+        text: str,
+    ) -> None:
+        self._activate(desktop, target)
+        composer = target.surfaces.composer.resolve(target.window.region)
+        desktop.paste_and_submit(target.window, composer.center, text)

codeaway/cli.py

@@ -0,0 +1,221 @@
+from __future__ import annotations
+
+import argparse
+import ipaddress
+import sys
+import webbrowser
+from dataclasses import dataclass, replace
+from http.server import ThreadingHTTPServer
+from pathlib import Path
+from typing import Callable, Sequence
+
+from .agents import AgentRegistry, CodexAgent
+from .config import AppConfig, default_config_path, load_config, save_config
+from .desktop import WindowsDesktop
+from .server import AppState, Application, make_handler
+
+
+class UnsupportedPlatform(RuntimeError):
+    """The current platform has no supported desktop backend."""
+
+
+def _desktop() -> WindowsDesktop:
+    if sys.platform != "win32":
+        raise UnsupportedPlatform(
+            "CodeAway v0.1 requires Windows with Codex Desktop."
+        )
+    return WindowsDesktop()
+
+
+def _registry(agents):
+    return AgentRegistry(agents)
+
+
+@dataclass
+class Runtime:
+    server_factory: Callable = ThreadingHTTPServer
+    browser_open: Callable[[str], object] = webbrowser.open
+    config_path_factory: Callable[[], str | Path] = default_config_path
+    desktop_factory: Callable[[], object] = _desktop
+    registry_factory: Callable[[Sequence[object]], object] = _registry
+
+
+@dataclass(frozen=True)
+class StartResult:
+    exit_code: int
+    url: str | None
+
+
+def _port(value: str) -> int:
+    port = int(value)
+    if not 1 <= port <= 65535:
+        raise argparse.ArgumentTypeError("port must be between 1 and 65535")
+    return port
+
+
+def _ipv4_address(value: str) -> str:
+    try:
+        address = ipaddress.ip_address(value)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError("address must be an IPv4 address") from error
+    if not isinstance(address, ipaddress.IPv4Address):
+        raise argparse.ArgumentTypeError("CodeAway v0.1 requires an IPv4 address")
+    return str(address)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="codeaway",
+        description="Control a local Codex Desktop window from your phone.",
+    )
+    parser.add_argument(
+        "--ip",
+        type=_ipv4_address,
+        metavar="IPV4_ADDRESS",
+        help="IPv4 address to bind and cache",
+    )
+    parser.add_argument("--port", type=_port, metavar="PORT", help="port to bind and cache")
+    parser.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="do not open the setup page in a laptop browser",
+    )
+    return parser
+
+
+def _is_loopback(address: str) -> bool:
+    try:
+        return ipaddress.ip_address(address).is_loopback
+    except ValueError:
+        return False
+
+
+def _base_url(address: str, port: int) -> str:
+    host = f"[{address}]" if ":" in address else address
+    return f"http://{host}:{port}/"
+
+
+def _print_bind_error(label: str, address: str, port: int, error: OSError) -> None:
+    print(
+        f"Could not bind {label} address {address}:{port}: {error}",
+        file=sys.stderr,
+    )
+
+
+def start(
+    argv: Sequence[str] | None = None,
+    runtime: Runtime | None = None,
+    *,
+    _serve: bool = True,
+) -> StartResult:
+    options = _parser().parse_args(list(sys.argv[1:] if argv is None else argv))
+    runtime = runtime or Runtime()
+
+    config_path = Path(runtime.config_path_factory())
+    config_existed = config_path.exists()
+    loaded = load_config(config_path)
+    for warning in loaded.warnings:
+        print(warning, file=sys.stderr)
+    config = loaded.config
+
+    try:
+        desktop = runtime.desktop_factory()
+    except (OSError, RuntimeError) as error:
+        print(f"CodeAway cannot start: {error}", file=sys.stderr)
+        return StartResult(1, None)
+
+    agent = CodexAgent()
+    registry = runtime.registry_factory([agent])
+    target = None
+    if config.setup_complete:
+        assert config.selected_agent is not None
+        assert config.selected_window is not None
+        assert config.surfaces is not None
+        target = registry.resolve(
+            desktop,
+            config.selected_agent,
+            config.selected_window.process_path,
+            config.selected_window.title_hint,
+            config.surfaces,
+        )
+
+    address = options.ip if options.ip is not None else config.bind_ip
+    port = options.port if options.port is not None else config.port
+    try:
+        parsed_address = ipaddress.ip_address(address)
+    except ValueError:
+        parsed_address = None
+    if not isinstance(parsed_address, ipaddress.IPv4Address):
+        print(
+            "CodeAway v0.1 requires an IPv4 bind address; "
+            "choose one with --ip IPV4_ADDRESS.",
+            file=sys.stderr,
+        )
+        return StartResult(1, None)
+    state = AppState(config, target)
+    application = Application(
+        state,
+        registry,
+        {agent.id: agent},
+        desktop,
+        config_path,
+    )
+    handler = make_handler(application)
+
+    try:
+        server = runtime.server_factory((address, port), handler)
+    except OSError as error:
+        if options.ip is not None:
+            _print_bind_error("explicit", address, port, error)
+            return StartResult(1, None)
+        if _is_loopback(address):
+            source = "cached" if config_existed else "default"
+            _print_bind_error(source, address, port, error)
+            return StartResult(1, None)
+        print(
+            f"Cached address {address} could not be bound: {error}; "
+            "falling back to 127.0.0.1.",
+            file=sys.stderr,
+        )
+        address = "127.0.0.1"
+        try:
+            server = runtime.server_factory((address, port), handler)
+        except OSError as fallback_error:
+            _print_bind_error("fallback", address, port, fallback_error)
+            return StartResult(1, None)
+
+    bound_port = int(server.server_address[1])
+    persisted = replace(config, bind_ip=address, port=bound_port)
+    try:
+        save_config(config_path, persisted)
+    except OSError as error:
+        server.server_close()
+        print(f"Could not save CodeAway configuration: {error}", file=sys.stderr)
+        return StartResult(1, None)
+    state.config = persisted
+
+    url = _base_url(address, bound_port)
+    if not _is_loopback(address):
+        print(
+            f"WARNING: Every device that can reach {url} receives full desktop input control."
+        )
+    print(f"CodeAway workspace: {url}")
+    if target is None and not options.no_browser:
+        runtime.browser_open(f"{url}setup")
+
+    if not _serve:
+        server.server_close()
+        return StartResult(0, url)
+
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.shutdown()
+        server.server_close()
+    return StartResult(0, url)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    return start(argv).exit_code