@moejay/wrightty 0.0.0

package/sdks/python/wrightty/terminal.py

@@ -0,0 +1,333 @@
+"""High-level Terminal API for AI agents and automation."""
+
+from __future__ import annotations
+
+import re
+import time
+from typing import Any
+
+from wrightty.client import WrighttyClient, WrighttyError
+
+PORT_RANGE_START = 9420
+PORT_RANGE_END = 9520
+
+
+class Terminal:
+    """High-level terminal automation interface.
+
+    Usage:
+        # Connect to a running wrightty server (daemon or native emulator)
+        term = Terminal.connect()
+        output = term.run("ls -la")
+        print(output)
+
+        # Spawn a new session on a wrightty-server daemon
+        term = Terminal.spawn()
+        term.run("echo hello")
+        term.close()
+    """
+
+    def __init__(self, client: WrighttyClient, session_id: str):
+        self._client = client
+        self._session_id = session_id
+        self._prompt_pattern = r"[$#>%]\s*$"
+
+    @staticmethod
+    def discover(host: str = "127.0.0.1") -> list[dict]:
+        """Scan for running wrightty servers on ports 9420-9520.
+
+        Returns a list of dicts with keys: url, version, implementation, capabilities.
+
+        Example:
+            servers = Terminal.discover()
+            for s in servers:
+                print(f"{s['url']} — {s['implementation']}")
+            # ws://127.0.0.1:9420 — wrightty (headless)
+            # ws://127.0.0.1:9421 — wrightty (wezterm bridge)
+        """
+        found = []
+        for port in range(PORT_RANGE_START, PORT_RANGE_END + 1):
+            url = f"ws://{host}:{port}"
+            try:
+                client = WrighttyClient.connect(url)
+                info = client.request("Wrightty.getInfo")
+                client.close()
+                found.append({
+                    "url": url,
+                    "port": port,
+                    "version": info.get("version", "unknown"),
+                    "implementation": info.get("implementation", "unknown"),
+                    "capabilities": info.get("capabilities", {}),
+                })
+            except (ConnectionError, ConnectionRefusedError, OSError, WrighttyError):
+                continue
+        return found
+
+    @classmethod
+    def connect(
+        cls,
+        url: str | None = None,
+        session_id: str | None = None,
+    ) -> Terminal:
+        """Connect to a wrightty server.
+
+        If no URL is given, auto-discovers the first available server
+        by scanning ports 9420-9440.
+        """
+        if url is None:
+            servers = cls.discover()
+            if not servers:
+                raise ConnectionError(
+                    "No wrightty server found. Start one with:\n"
+                    "  wrightty term --headless\n"
+                    "  wrightty term --bridge-tmux\n"
+                    "  wrightty term --bridge-wezterm"
+                )
+            url = servers[0]["url"]
+
+        client = WrighttyClient.connect(url)
+
+        if session_id is None:
+            result = client.request("Session.list")
+            sessions = result.get("sessions", [])
+            if sessions:
+                session_id = sessions[0]["sessionId"]
+            else:
+                session_id = "0"
+
+        return cls(client, session_id)
+
+    @classmethod
+    def spawn(
+        cls,
+        shell: str | None = None,
+        cols: int = 120,
+        rows: int = 40,
+        cwd: str | None = None,
+        server_url: str = "ws://127.0.0.1:9420",
+    ) -> Terminal:
+        """Connect to a wrightty-server daemon and create a new session."""
+        client = WrighttyClient.connect(server_url)
+
+        params: dict[str, Any] = {"cols": cols, "rows": rows}
+        if shell:
+            params["shell"] = shell
+        if cwd:
+            params["cwd"] = cwd
+
+        result = client.request("Session.create", params)
+        session_id = result["sessionId"]
+
+        term = cls(client, session_id)
+        term.wait_for_prompt(timeout=5)
+        return term
+
+    def close(self):
+        """Close the connection."""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    # --- High-level API ---
+
+    def run(self, command: str, timeout: float = 30) -> str:
+        """Run a command and return its output.
+
+        Sends the command, waits for the prompt to reappear, and returns
+        everything between the command echo and the next prompt.
+        """
+        self.send_text(command + "\n")
+
+        # Wait for prompt to come back.
+        self.wait_for_prompt(timeout=timeout)
+
+        # Read screen and extract output.
+        screen = self.read_screen()
+        lines = screen.strip().split("\n")
+
+        output_lines = []
+        found_cmd = False
+        for line in lines:
+            if not found_cmd:
+                if command in line:
+                    found_cmd = True
+                continue
+            if re.search(self._prompt_pattern, line):
+                break
+            output_lines.append(line)
+
+        return "\n".join(output_lines)
+
+    def send_text(self, text: str):
+        """Send raw text to the terminal."""
+        self._client.request("Input.sendText", {"sessionId": self._session_id, "text": text})
+
+    def send_keys(self, *keys: str):
+        """Send structured keystrokes.
+
+        Examples:
+            term.send_keys("Ctrl+c")
+            term.send_keys("ArrowUp", "Enter")
+            term.send_keys("Escape", ":", "w", "q", "Enter")  # vim :wq
+        """
+        self._client.request(
+            "Input.sendKeys", {"sessionId": self._session_id, "keys": list(keys)}
+        )
+
+    def read_screen(self) -> str:
+        """Read the current visible screen as text."""
+        result = self._client.request("Screen.getText", {"sessionId": self._session_id})
+        return result["text"]
+
+    def screenshot(self, format: str = "svg") -> str | bytes:
+        """Take a screenshot. Returns str for text/svg, bytes for png."""
+        result = self._client.request(
+            "Screen.screenshot", {"sessionId": self._session_id, "format": format}
+        )
+        data = result["data"]
+        if format == "png":
+            import base64
+            return base64.b64decode(data)
+        return data
+
+    def wait_for(self, pattern: str, timeout: float = 30, regex: bool = False) -> str:
+        """Wait until a pattern appears on screen. Returns the screen text when found."""
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            screen = self.read_screen()
+            if regex:
+                if re.search(pattern, screen):
+                    return screen
+            else:
+                if pattern in screen:
+                    return screen
+            time.sleep(0.2)
+        raise TimeoutError(f"Pattern {pattern!r} not found within {timeout}s")
+
+    def wait_for_prompt(self, timeout: float = 10) -> str:
+        """Wait for the shell prompt to appear."""
+        return self.wait_for(self._prompt_pattern, timeout=timeout, regex=True)
+
+    def set_prompt_pattern(self, pattern: str):
+        """Override the regex used to detect the shell prompt."""
+        self._prompt_pattern = pattern
+
+    def get_size(self) -> tuple[int, int]:
+        """Get terminal dimensions as (cols, rows)."""
+        result = self._client.request("Terminal.getSize", {"sessionId": self._session_id})
+        return result["cols"], result["rows"]
+
+    def resize(self, cols: int, rows: int):
+        """Resize the terminal."""
+        self._client.request(
+            "Terminal.resize", {"sessionId": self._session_id, "cols": cols, "rows": rows}
+        )
+
+    def get_info(self) -> dict:
+        """Get server info and capabilities."""
+        return self._client.request("Wrightty.getInfo")
+
+    # --- Recording ---
+
+    def start_session_recording(self, include_input: bool = False) -> str:
+        """Start recording raw PTY I/O (asciicast v2 format).
+
+        Returns a recording ID. Stop with stop_session_recording().
+        The recording can be played back with `asciinema play`.
+        """
+        result = self._client.request(
+            "Recording.startSession",
+            {"sessionId": self._session_id, "includeInput": include_input},
+        )
+        return result["recordingId"]
+
+    def stop_session_recording(self, recording_id: str) -> dict:
+        """Stop a session recording and return asciicast data.
+
+        Returns dict with keys: format, data, duration, events.
+        Save `data` to a .cast file for asciinema playback.
+        """
+        return self._client.request("Recording.stopSession", {"recordingId": recording_id})
+
+    def start_action_recording(self, format: str = "python") -> str:
+        """Start recording wrightty API calls as a replayable script.
+
+        Args:
+            format: "python", "json", or "cli"
+
+        Returns a recording ID. Stop with stop_action_recording().
+        """
+        result = self._client.request(
+            "Recording.startActions",
+            {"sessionId": self._session_id, "format": format},
+        )
+        return result["recordingId"]
+
+    def stop_action_recording(self, recording_id: str) -> dict:
+        """Stop action recording and return the generated script.
+
+        Returns dict with keys: format, data, actions, duration.
+        """
+        return self._client.request("Recording.stopActions", {"recordingId": recording_id})
+
+    def capture_screen(self, format: str = "svg") -> dict:
+        """Capture a single screen frame.
+
+        Returns dict with keys: frameId, timestamp, format, data.
+        """
+        return self._client.request(
+            "Recording.captureScreen",
+            {"sessionId": self._session_id, "format": format},
+        )
+
+    def start_screen_recording(self, interval_ms: int = 1000, format: str = "svg") -> str:
+        """Start periodic screen capture.
+
+        Args:
+            interval_ms: Capture interval in milliseconds (default: 1000)
+            format: "svg", "text", or "png"
+
+        Returns a recording ID. Stop with stop_screen_recording().
+        """
+        result = self._client.request(
+            "Recording.startScreenCapture",
+            {"sessionId": self._session_id, "intervalMs": interval_ms, "format": format},
+        )
+        return result["recordingId"]
+
+    def stop_screen_recording(self, recording_id: str) -> dict:
+        """Stop screen capture and return all frames.
+
+        Returns dict with keys: frames, duration, frameCount, format.
+        """
+        return self._client.request("Recording.stopScreenCapture", {"recordingId": recording_id})
+
+    def start_video(self, fps: int = 30, format: str = "mp4") -> str:
+        """Start framebuffer video recording (native emulators only).
+
+        Captures the actual rendered pixels via glReadPixels and pipes to ffmpeg.
+        Requires ffmpeg installed on the system.
+
+        Args:
+            fps: Frames per second (default: 30)
+            format: "mp4", "webm", or "gif"
+
+        Returns a recording ID. Stop with stop_video().
+        """
+        result = self._client.request(
+            "Recording.startVideo",
+            {"sessionId": self._session_id, "fps": fps, "format": format},
+        )
+        return result["recordingId"]
+
+    def stop_video(self, recording_id: str) -> dict:
+        """Stop video recording and return metadata.
+
+        Returns dict with keys: format, path, duration, frames, width, height, size.
+        The video file is at the returned `path`.
+        """
+        return self._client.request("Recording.stopVideo", {"recordingId": recording_id})

package/skills/wrightty/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: wrightty
+description: Control terminal emulators programmatically via the wrightty protocol. Use when you need to run commands in a real terminal, interact with TUI applications, read terminal screen output, take screenshots, send keystrokes, or automate terminal workflows. Triggers on tasks involving terminal automation, running shell commands through a real PTY, controlling vim/htop/other TUI apps, or capturing terminal output.
+license: MIT
+metadata:
+  author: moejay
+  version: "0.1.0"
+---
+
+# wrightty — Terminal Automation Protocol
+
+Wrightty lets you control terminal emulators over WebSocket JSON-RPC. You can run commands, read the screen, send keystrokes, and take screenshots — just like a human would interact with a terminal, but programmatically.
+
+## When to use
+
+- Running shell commands in a real terminal (not subprocess) where you need the full PTY environment
+- Interacting with TUI applications (vim, htop, less, etc.)
+- Reading terminal screen output with colors and formatting
+- Taking terminal screenshots (SVG)
+- Automating interactive terminal workflows
+- Waiting for specific output to appear before proceeding
+
+## Setup
+
+Wrightty needs a terminal backend. Pick one:
+
+**Alacritty (native, zero overhead):**
+```bash
+git clone -b wrightty-support https://github.com/moejay/alacritty.git
+cd alacritty && cargo build --features wrightty
+./target/debug/alacritty --wrightty  # listens on ws://127.0.0.1:9420
+```
+
+**WezTerm (via bridge):**
+```bash
+# Start WezTerm normally, then:
+cargo run -p wrightty-bridge-wezterm  # listens on ws://127.0.0.1:9421
+
+# For flatpak:
+WEZTERM_CMD="flatpak run --command=wezterm org.wezfurlong.wezterm" cargo run -p wrightty-bridge-wezterm
+```
+
+**Headless daemon (no GUI):**
+```bash
+cargo run -p wrightty-server  # listens on ws://127.0.0.1:9420
+```
+
+## Python SDK
+
+The SDK has zero external dependencies.
+
+```python
+from wrightty import Terminal
+
+# Connect to a running terminal
+term = Terminal.connect()                          # ws://127.0.0.1:9420
+term = Terminal.connect("ws://127.0.0.1:9421")    # WezTerm bridge
+
+# Run a command and get output
+output = term.run("cargo test", timeout=120)
+
+# Read the current screen
+screen = term.read_screen()
+
+# Wait for text to appear
+term.wait_for("tests passed", timeout=60)
+term.wait_for(r"error\[\w+\]", regex=True)
+
+# Send keystrokes (TUI apps)
+term.send_keys("Escape", ":", "w", "q", "Enter")  # vim: save and quit
+term.send_keys("Ctrl+c")                           # interrupt
+term.send_keys("ArrowUp", "Enter")                 # repeat last command
+
+# Screenshots
+svg = term.screenshot("svg")
+
+# Terminal info
+cols, rows = term.get_size()
+
+term.close()
+```
+
+Install: `pip install /path/to/wrightty/sdks/python` or set `PYTHONPATH=/path/to/wrightty/sdks/python`.
+
+## CLI
+
+```bash
+wrightty run "ls -la"                              # run command, print output
+wrightty run "cargo test" --timeout 120            # with timeout
+wrightty read                                       # dump current screen
+wrightty send-text "echo hello\n"                   # send raw text
+wrightty send-keys Ctrl+c                           # send keystroke
+wrightty send-keys Escape : w q Enter               # vim: :wq
+wrightty wait-for "BUILD SUCCESS" --timeout 60      # block until text appears
+wrightty screenshot --format svg -o terminal.svg    # take screenshot
+wrightty info                                       # server capabilities
+wrightty size                                       # terminal dimensions
+wrightty --url ws://127.0.0.1:9421 run "ls"         # connect to different server
+```
+
+## MCP Server
+
+Add to your MCP config (Claude, Cursor, etc.):
+
+```json
+{
+  "mcpServers": {
+    "wrightty": {
+      "command": "python3",
+      "args": ["-m", "wrightty.mcp_server"],
+      "env": {
+        "PYTHONPATH": "/path/to/wrightty/sdks/python",
+        "WRIGHTTY_SOCKET": "ws://127.0.0.1:9420"
+      }
+    }
+  }
+}
+```
+
+Available MCP tools:
+
+| Tool | Description |
+|------|-------------|
+| `run_command` | Run a shell command, return output |
+| `read_terminal` | Read current screen text |
+| `send_keys` | Send keystrokes (`["Ctrl+c"]`, `["Escape", ":", "q", "Enter"]`) |
+| `send_text` | Send raw text (use `\n` for newline) |
+| `screenshot` | Terminal screenshot as SVG |
+| `wait_for_text` | Block until pattern appears on screen |
+| `terminal_info` | Terminal dimensions and capabilities |
+
+## Protocol reference
+
+WebSocket JSON-RPC 2.0 on `ws://127.0.0.1:9420`. Full spec: [PROTOCOL.md](https://github.com/moejay/wrightty/blob/main/PROTOCOL.md).
+
+### Core methods
+
+**Run a command:**
+```json
+{"jsonrpc":"2.0","id":1,"method":"Input.sendText","params":{"sessionId":"0","text":"ls -la\n"}}
+```
+
+**Read the screen:**
+```json
+{"jsonrpc":"2.0","id":2,"method":"Screen.getText","params":{"sessionId":"0"}}
+// → {"result":{"text":"$ ls -la\ntotal 140\ndrwxr-xr-x  8 user user 4096 ...\n$"}}
+```
+
+**Send keystrokes:**
+```json
+{"jsonrpc":"2.0","id":3,"method":"Input.sendKeys","params":{"sessionId":"0","keys":["Ctrl+c"]}}
+```
+
+**Take a screenshot:**
+```json
+{"jsonrpc":"2.0","id":4,"method":"Screen.screenshot","params":{"sessionId":"0","format":"svg"}}
+// → {"result":{"format":"svg","data":"<svg ...>"}}
+```
+
+**Get terminal size:**
+```json
+{"jsonrpc":"2.0","id":5,"method":"Terminal.getSize","params":{"sessionId":"0"}}
+// → {"result":{"cols":120,"rows":40}}
+```
+
+**Server capabilities:**
+```json
+{"jsonrpc":"2.0","id":6,"method":"Wrightty.getInfo","params":{}}
+```
+
+### Key names for sendKeys
+
+Single characters: `a`, `1`, `/`, `.`
+Special keys: `Enter`, `Tab`, `Escape`, `Backspace`, `Delete`, `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`, `Home`, `End`, `PageUp`, `PageDown`, `F1`-`F12`
+Modifiers: `Ctrl+c`, `Alt+x`, `Shift+Tab`
+
+### Session management (headless daemon only)
+
+```json
+// Create session
+{"jsonrpc":"2.0","id":1,"method":"Session.create","params":{"cols":80,"rows":24}}
+// → {"result":{"sessionId":"abc-123"}}
+
+// List sessions
+{"jsonrpc":"2.0","id":2,"method":"Session.list","params":{}}
+
+// Destroy session
+{"jsonrpc":"2.0","id":3,"method":"Session.destroy","params":{"sessionId":"abc-123"}}
+```
+
+Native emulator mode uses `"sessionId":"0"` for the active terminal. Session create/destroy is not supported — the emulator manages its own sessions.
+
+## Recording
+
+Three types of recording:
+
+### Session recording (asciicast)
+Records raw PTY I/O with timestamps. Compatible with `asciinema play`.
+
+```python
+rec_id = term.start_session_recording(include_input=True)
+# ... do stuff ...
+result = term.stop_session_recording(rec_id)
+with open("session.cast", "w") as f:
+    f.write(result["data"])
+# Play back: asciinema play session.cast
+```
+
+### Action recording (script generation)
+Records wrightty API calls as a replayable Python/JSON/CLI script. Like Playwright codegen.
+
+```python
+rec_id = term.start_action_recording(format="python")
+# ... do stuff ...
+result = term.stop_action_recording(rec_id)
+print(result["data"])  # prints a Python script that replays the actions
+```
+
+### Screen capture
+Capture individual frames or record periodic screenshots.
+
+```python
+# Single frame
+frame = term.capture_screen(format="svg")
+
+# Periodic capture
+rec_id = term.start_screen_recording(interval_ms=500, format="svg")
+# ... do stuff ...
+result = term.stop_screen_recording(rec_id)
+# result["frames"] is a list of SVG frames with timestamps
+```
+
+### Video recording (native emulators only, requires ffmpeg)
+Captures the actual rendered framebuffer — pixel perfect, including colors, fonts, sixel images, everything on screen.
+
+```python
+rec_id = term.start_video(fps=30, format="mp4")
+# ... do stuff ...
+result = term.stop_video(rec_id)
+print(result["path"])  # /tmp/wrightty-rec_001.mp4
+```
+
+### CLI
+```bash
+wrightty record -o session.cast            # Ctrl+C to stop
+wrightty record-actions -o script.py       # generates Python script
+wrightty record-actions --format cli       # generates shell commands
+```
+
+### MCP tools
+- `start_recording` — starts session + action recording
+- `stop_recording` — stops and returns asciicast data + Python script
+- `capture_screen_frame` — single SVG snapshot
+
+## Tips
+
+- Use `term.run()` for most commands — it sends the command and waits for the prompt to return
+- Use `term.send_keys()` for interactive/TUI apps where you need specific keystrokes
+- Use `term.wait_for()` before reading output from slow commands (builds, tests)
+- The default prompt detection pattern is `[$#>%]\s*$` — override with `term.set_prompt_pattern()` if your prompt is different
+- Screenshots are SVG by default — good for rendering in browsers and docs, and readable by vision models

package/src/lib.rs

@@ -0,0 +1 @@
+// Root package exists only for integration tests.