remotedev-agent 1.3.0__tar.gz

remotedev_agent-1.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

remotedev_agent-1.3.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+recursive-include remotedev_agent *.py

remotedev_agent-1.3.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: remotedev-agent
+Version: 1.3.0
+Summary: Agent daemon for Remote AI Maestro — manages PTY sessions and AI agent subprocesses on remote machines
+Author-email: Shaun <scwj1210@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/shaunchew/remote-ai-maestro
+Project-URL: Repository, https://github.com/shaunchew/remote-ai-maestro
+Project-URL: Documentation, https://github.com/shaunchew/remote-ai-maestro#readme
+Project-URL: Issues, https://github.com/shaunchew/remote-ai-maestro/issues
+Keywords: remote,ai,agent,terminal,pty,tmux,claude,codex
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: Terminals :: Terminal Emulators/X Terminals
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: websockets>=13.0
+Requires-Dist: click>=8.0
+Requires-Dist: ptyprocess>=0.7.0
+Requires-Dist: watchdog>=3.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Requires-Dist: pytest-mock>=3.12; extra == "test"
+Dynamic: license-file
+
+# remotedev-agent
+
+Agent daemon for [Remote AI Maestro](https://remote-ai-maestro.thesavvydeveloper.com) -- connects your machine to the platform so you can remotely control AI coding agents (Claude Code, Codex, Aider, Copilot, Cursor) via a browser-based terminal.
+
+## What it does
+
+- Opens tmux-backed PTY sessions that survive disconnects and daemon restarts
+- Discovers AI agents available on your machine's PATH
+- Streams terminal I/O to the Remote AI Maestro relay over WebSocket
+- Manages sandbox directories (create, clone repos, delete)
+- Installs as a background service (launchd on macOS, systemd on Linux)
+
+## Requirements
+
+- Python 3.10+
+- tmux installed and on PATH
+- macOS or Linux
+
+## Installation
+
+```bash
+pip install remotedev-agent
+```
+
+## Quick start
+
+1. Register a machine on the [Remote AI Maestro dashboard](https://remote-ai-maestro.thesavvydeveloper.com) to get your machine ID and token.
+
+2. Configure the agent:
+
+```bash
+remotedev-agent configure \
+  --relay-url wss://relay.thesavvydeveloper.com \
+  --machine-id YOUR_MACHINE_ID \
+  --token YOUR_MACHINE_TOKEN
+```
+
+3. Start the agent:
+
+```bash
+remotedev-agent start
+```
+
+The agent connects to the relay and begins accepting terminal sessions from the web dashboard.
+
+## Interactive setup
+
+If you prefer prompts instead of flags:
+
+```bash
+remotedev-agent setup
+```
+
+## Install as a background service
+
+```bash
+remotedev-agent install-service
+```
+
+This creates a launchd plist (macOS) or systemd unit (Linux) so the agent starts automatically on boot.
+
+To remove the service:
+
+```bash
+remotedev-agent uninstall-service
+```
+
+## Configuration
+
+Config is stored at `~/.remotedev-agent/config.json` with three fields:
+
+| Field | Description |
+|-------|-------------|
+| `relay_url` | WebSocket URL of the relay server |
+| `machine_id` | UUID assigned when you register the machine |
+| `token` | Machine authentication token |
+
+## How it works
+
+The agent daemon maintains a persistent WebSocket connection to the Remote AI Maestro relay server. When a user opens a sandbox terminal in their browser, the relay forwards the request to the agent, which creates a tmux-backed PTY session on your machine. All terminal input/output is streamed in real time through the relay.
+
+AI agents (Claude Code, Codex, etc.) are discovered by probing your PATH at startup. Users can invoke any discovered agent from the browser terminal.
+
+## Development
+
+```bash
+# Install in editable mode with test dependencies
+pip install -e ".[test]"
+
+# Run tests
+pytest
+```
+
+## License
+
+MIT

remotedev_agent-1.3.0/README.md

@@ -0,0 +1,96 @@
+# remotedev-agent
+
+Agent daemon for [Remote AI Maestro](https://remote-ai-maestro.thesavvydeveloper.com) -- connects your machine to the platform so you can remotely control AI coding agents (Claude Code, Codex, Aider, Copilot, Cursor) via a browser-based terminal.
+
+## What it does
+
+- Opens tmux-backed PTY sessions that survive disconnects and daemon restarts
+- Discovers AI agents available on your machine's PATH
+- Streams terminal I/O to the Remote AI Maestro relay over WebSocket
+- Manages sandbox directories (create, clone repos, delete)
+- Installs as a background service (launchd on macOS, systemd on Linux)
+
+## Requirements
+
+- Python 3.10+
+- tmux installed and on PATH
+- macOS or Linux
+
+## Installation
+
+```bash
+pip install remotedev-agent
+```
+
+## Quick start
+
+1. Register a machine on the [Remote AI Maestro dashboard](https://remote-ai-maestro.thesavvydeveloper.com) to get your machine ID and token.
+
+2. Configure the agent:
+
+```bash
+remotedev-agent configure \
+  --relay-url wss://relay.thesavvydeveloper.com \
+  --machine-id YOUR_MACHINE_ID \
+  --token YOUR_MACHINE_TOKEN
+```
+
+3. Start the agent:
+
+```bash
+remotedev-agent start
+```
+
+The agent connects to the relay and begins accepting terminal sessions from the web dashboard.
+
+## Interactive setup
+
+If you prefer prompts instead of flags:
+
+```bash
+remotedev-agent setup
+```
+
+## Install as a background service
+
+```bash
+remotedev-agent install-service
+```
+
+This creates a launchd plist (macOS) or systemd unit (Linux) so the agent starts automatically on boot.
+
+To remove the service:
+
+```bash
+remotedev-agent uninstall-service
+```
+
+## Configuration
+
+Config is stored at `~/.remotedev-agent/config.json` with three fields:
+
+| Field | Description |
+|-------|-------------|
+| `relay_url` | WebSocket URL of the relay server |
+| `machine_id` | UUID assigned when you register the machine |
+| `token` | Machine authentication token |
+
+## How it works
+
+The agent daemon maintains a persistent WebSocket connection to the Remote AI Maestro relay server. When a user opens a sandbox terminal in their browser, the relay forwards the request to the agent, which creates a tmux-backed PTY session on your machine. All terminal input/output is streamed in real time through the relay.
+
+AI agents (Claude Code, Codex, etc.) are discovered by probing your PATH at startup. Users can invoke any discovered agent from the browser terminal.
+
+## Development
+
+```bash
+# Install in editable mode with test dependencies
+pip install -e ".[test]"
+
+# Run tests
+pytest
+```
+
+## License
+
+MIT

remotedev_agent-1.3.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "remotedev-agent"
+version = "1.3.0"
+description = "Agent daemon for Remote AI Maestro — manages PTY sessions and AI agent subprocesses on remote machines"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Shaun", email = "scwj1210@gmail.com" },
+]
+keywords = ["remote", "ai", "agent", "terminal", "pty", "tmux", "claude", "codex"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Shells",
+    "Topic :: Terminals :: Terminal Emulators/X Terminals",
+]
+dependencies = [
+    "websockets>=13.0",
+    "click>=8.0",
+    "ptyprocess>=0.7.0",
+    "watchdog>=3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/shaunchew/remote-ai-maestro"
+Repository = "https://github.com/shaunchew/remote-ai-maestro"
+Documentation = "https://github.com/shaunchew/remote-ai-maestro#readme"
+Issues = "https://github.com/shaunchew/remote-ai-maestro/issues"
+
+[project.scripts]
+remotedev-agent = "remotedev_agent.cli:cli"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-mock>=3.12",
+]
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["remotedev_agent*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

remotedev_agent-1.3.0/remotedev_agent/__init__.py

@@ -0,0 +1,3 @@
+"""Remote AI Maestro agent daemon."""
+
+__version__ = "1.0.0"

remotedev_agent-1.3.0/remotedev_agent/cli.py

@@ -0,0 +1,265 @@
+import asyncio
+import os
+
+import click
+
+from remotedev_agent.config import AgentConfig
+
+
+def _package_version() -> str:
+    """Resolve the installed package version. Falls back to the literal in
+    pyproject.toml when running from a source checkout without metadata."""
+    try:
+        from importlib.metadata import version as _v
+        return _v("remotedev-agent")
+    except Exception:
+        return "unknown"
+
+
+@click.group()
+@click.version_option(version=_package_version(), prog_name="remotedev-agent")
+def cli():
+    """Remote AI Maestro Agent — connects your machine to Remote AI Maestro."""
+
+
+@cli.command()
+@click.option("--relay-url", prompt="Relay URL", help="WebSocket relay URL (e.g. ws://localhost:8001)")
+@click.option("--machine-id", prompt="Machine ID", help="Machine UUID from dashboard")
+@click.option("--token", prompt="Machine token", hide_input=True, help="Machine registration token")
+def setup(relay_url: str, machine_id: str, token: str):
+    """Configure the agent with relay connection details."""
+    config = AgentConfig(relay_url=relay_url, machine_id=machine_id, token=token)
+    config.save()
+    click.echo("Config saved.")
+    click.echo("To run hidden in the background (recommended): remotedev-agent install-service")
+    click.echo("Or quick-detach for one-off:                   remotedev-agent start --detach")
+
+
+@cli.command()
+@click.option("--relay-url", default=None)
+@click.option("--machine-id", default=None)
+@click.option("--token", default=None)
+@click.option(
+    "--no-verify", is_flag=True,
+    help="Skip the post-config connectivity smoke check.",
+)
+def configure(relay_url: str | None, machine_id: str | None, token: str | None, no_verify: bool):
+    """Non-interactive configuration (for scripting/EC2 user-data).
+
+    By default, runs a 10-second connectivity check against the relay after
+    saving — surfaces token mismatches or network problems immediately
+    instead of letting the daemon retry-loop in silence. Pass `--no-verify`
+    to skip (e.g. when configuring offline before bringing the network up).
+    """
+    if not all([relay_url, machine_id, token]):
+        click.echo("All of --relay-url, --machine-id, --token are required.", err=True)
+        raise SystemExit(1)
+    config = AgentConfig(relay_url=relay_url, machine_id=machine_id, token=token)
+    config.save()
+    click.echo("Config saved.")
+    if no_verify:
+        return
+    # Smoke check — informational. We don't exit non-zero on failure because
+    # configure is a config-write op (the user may be configuring on one
+    # network and connecting from another). The output is enough to catch
+    # the common cases without blocking the install.
+    from remotedev_agent.diagnostics import probe_ws_connect, summarize, probe_tcp_v4, probe_tcp_v6
+    click.echo("Verifying connectivity (10s)...")
+    async def _check():
+        v4 = await probe_tcp_v4(relay_url)
+        v6 = await probe_tcp_v6(relay_url)
+        ws = await probe_ws_connect(relay_url, machine_id, token)
+        return [v4, v6, ws]
+    try:
+        probes = asyncio.run(_check())
+    except Exception as e:
+        click.echo(f"  (smoke check skipped: {e})")
+        return
+    click.echo(summarize(probes))
+
+
+@cli.command()
+def diagnose():
+    """Run a full self-diagnostic against the configured relay.
+
+    Output is designed to be pasted into a bug report. Probes:
+      - DNS A/AAAA records
+      - raw TCP connect over IPv4 and IPv6 (isolates blackholed-v6 networks)
+      - full WebSocket handshake against /ws/agent/{id} with the saved token
+        (distinguishes auth failures from network problems)
+    """
+    from remotedev_agent.diagnostics import run_full_diagnose, format_report, summarize
+    try:
+        config = AgentConfig.load()
+    except FileNotFoundError as e:
+        click.echo(str(e), err=True)
+        raise SystemExit(1)
+    click.echo(f"Diagnosing connectivity for machine {config.machine_id}")
+    click.echo(f"Relay URL: {config.relay_url}\n")
+    probes = asyncio.run(run_full_diagnose(config))
+    click.echo(format_report(probes))
+    click.echo("")
+    click.echo(summarize(probes))
+    # Exit non-zero if the WS probe failed — makes diagnose usable in scripts
+    # ("if remotedev-agent diagnose; then ... fi").
+    if not probes[-1].ok:
+        raise SystemExit(2)
+
+
+@cli.command()
+@click.option(
+    "--detach", "-d", is_flag=True,
+    help="Run in the background, detached from the terminal. Logs go to ~/.remotedev/agent.log.",
+)
+def start(detach: bool):
+    """Start the agent daemon. Use --detach to run in the background."""
+    from remotedev_agent import process_manager
+
+    try:
+        config = AgentConfig.load()
+    except FileNotFoundError as e:
+        click.echo(str(e), err=True)
+        click.echo("Run 'remotedev-agent setup' or 'remotedev-agent configure ...' first.", err=True)
+        raise SystemExit(1)
+
+    def _run():
+        # Imported post-fork to avoid copying daemon-side resources (websockets,
+        # asyncio, ptyprocess) into the short-lived parent.
+        from remotedev_agent.daemon import AgentDaemon
+        daemon = AgentDaemon(config)
+        asyncio.run(daemon.run())
+
+    if not detach:
+        click.echo(f"Starting agent for machine {config.machine_id}...")
+        _run()
+        return
+
+    try:
+        pid = process_manager.detach_and_run(_run)
+    except RuntimeError as e:
+        click.echo(str(e), err=True)
+        raise SystemExit(1)
+    click.echo(f"Agent running in background (PID {pid}).")
+    click.echo(f"Logs:   {process_manager.LOG_FILE}")
+    click.echo("View:   remotedev-agent logs -f")
+    click.echo("Stop:   remotedev-agent stop")
+    click.echo("Status: remotedev-agent status")
+
+
+@cli.command("stop")
+def cmd_stop():
+    """Stop the detached agent (no effect on tmux sandbox sessions)."""
+    from remotedev_agent import process_manager
+    svc = process_manager.service_status()
+    if svc["running"]:
+        click.echo(
+            f"Agent is running as a {svc['kind']} service, not in detached mode.\n"
+            "Stop the service with 'remotedev-agent uninstall-service' "
+            f"(or '{'launchctl unload ~/Library/LaunchAgents/' + process_manager.LAUNCHD_LABEL + '.plist' if svc['kind'] == 'launchd' else 'systemctl --user stop ' + process_manager.SYSTEMD_UNIT}').",
+            err=True,
+        )
+        raise SystemExit(1)
+    ok, message = process_manager.stop()
+    click.echo(message)
+    # Stale-PID cleanup is a successful no-op for callers, not a failure.
+    if not ok and "stale" not in message.lower() and "not running" not in message.lower():
+        raise SystemExit(1)
+
+
+@cli.command("status")
+def cmd_status():
+    """Show whether the agent is running (detached or as a service)."""
+    from remotedev_agent import process_manager
+    info = process_manager.status()
+    if info["service_running"]:
+        click.echo(f"Agent is running as a {info['service_kind']} service.")
+    elif info["detached_running"]:
+        click.echo(f"Agent is running in detached mode (PID {info['pid']}).")
+    elif info["pid"]:
+        click.echo(f"Agent is NOT running (stale PID {info['pid']} in PID file).")
+    else:
+        click.echo("Agent is NOT running.")
+    if info["service_kind"]:
+        click.echo(f"Service:  {info['service_kind']} ({'running' if info['service_running'] else 'stopped/not loaded'})")
+    click.echo(f"PID file: {info['pid_file']}")
+    click.echo(f"Log file: {info['log_file']}")
+
+
+@cli.command()
+@click.option("--follow", "-f", is_flag=True, help="Stream new log lines as they arrive.")
+@click.option("--lines", "-n", type=click.IntRange(min=1), default=200, show_default=True, help="Number of recent lines to print.")
+def logs(follow: bool, lines: int):
+    """View agent logs without affecting any running session."""
+    from remotedev_agent import process_manager
+    process_manager.tail_log(lines=lines, follow=follow)
+
+
+@cli.command()
+def restart():
+    """Restart the agent (works for both detached and service mode)."""
+    import subprocess
+    import sys
+    from remotedev_agent import process_manager
+    svc = process_manager.service_status()
+    if svc["kind"] == "launchd":
+        # `kickstart -k` is the atomic stop+restart on macOS; falls back to
+        # legacy stop/start if the modern domain syntax isn't supported.
+        uid = os.getuid() if hasattr(os, "getuid") else None
+        target = f"gui/{uid}/{process_manager.LAUNCHD_LABEL}" if uid is not None else process_manager.LAUNCHD_LABEL
+        res = subprocess.run(["launchctl", "kickstart", "-k", target], capture_output=True, text=True)
+        if res.returncode == 0:
+            click.echo("Service restarted (launchd).")
+            return
+        stop_res = subprocess.run(["launchctl", "stop", process_manager.LAUNCHD_LABEL], capture_output=True, text=True)
+        start_res = subprocess.run(["launchctl", "start", process_manager.LAUNCHD_LABEL], capture_output=True, text=True)
+        if start_res.returncode == 0:
+            click.echo("Service restarted (launchd, fallback path).")
+        else:
+            click.echo(f"Failed to restart launchd service: {start_res.stderr.strip() or stop_res.stderr.strip() or res.stderr.strip()}", err=True)
+            raise SystemExit(1)
+        return
+    if svc["kind"] == "systemd":
+        # If the unit exists at all, prefer systemctl restart — even if the
+        # unit is currently inactive/failed, restart will bring it up cleanly
+        # and avoid forking a competing detached agent.
+        subprocess.run(["systemctl", "--user", "restart", process_manager.SYSTEMD_UNIT], check=True)
+        click.echo("Service restarted (systemd).")
+        return
+    process_manager.stop()
+    subprocess.run([sys.executable, "-m", "remotedev_agent.cli", "start", "--detach"], check=False)
+
+
+@cli.command("install-service")
+def install_service():
+    """Install as a background service (launchd on macOS, systemd on Linux)."""
+    import platform
+    system = platform.system()
+    if system == "Darwin":
+        from remotedev_agent.service.macos import install
+        install()
+    elif system == "Linux":
+        from remotedev_agent.service.linux import install
+        install()
+    else:
+        click.echo(f"Unsupported platform: {system}", err=True)
+        raise SystemExit(1)
+
+
+@cli.command("uninstall-service")
+def uninstall_service():
+    """Uninstall the background service."""
+    import platform
+    system = platform.system()
+    if system == "Darwin":
+        from remotedev_agent.service.macos import uninstall
+        uninstall()
+    elif system == "Linux":
+        from remotedev_agent.service.linux import uninstall
+        uninstall()
+    else:
+        click.echo(f"Unsupported platform: {system}", err=True)
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    cli()

remotedev_agent-1.3.0/remotedev_agent/config.py

@@ -0,0 +1,37 @@
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".remotedev"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+
+@dataclass
+class AgentConfig:
+    relay_url: str
+    machine_id: str
+    token: str
+    sandboxes_root: str = ""
+
+    def __post_init__(self):
+        if not self.sandboxes_root:
+            self.sandboxes_root = str(Path.home() / "Documents")
+
+    def save(self):
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        os.chmod(CONFIG_DIR, 0o700)
+        CONFIG_FILE.write_text(json.dumps({
+            "relay_url": self.relay_url,
+            "machine_id": self.machine_id,
+            "token": self.token,
+            "sandboxes_root": self.sandboxes_root,
+        }, indent=2))
+        os.chmod(CONFIG_FILE, 0o600)
+
+    @classmethod
+    def load(cls) -> "AgentConfig":
+        if not CONFIG_FILE.exists():
+            raise FileNotFoundError(f"Config not found at {CONFIG_FILE}. Run 'remotedev-agent setup' first.")
+        data = json.loads(CONFIG_FILE.read_text())
+        return cls(**data)