mtrx-cli 0.1.10 → 0.1.13

package/src/matrx/cli/cursor_service.py

@@ -0,0 +1,343 @@
+"""
+Cross-platform background service management for the MTRX Cursor proxy.
+
+Handles installing, starting, stopping, and checking the proxy daemon on
+macOS (Launch Agent), Linux (systemd user unit), and Windows (detached
+subprocess with PID tracking).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import platform
+import shutil
+import signal
+import subprocess
+import sys
+import textwrap
+import time
+from pathlib import Path
+
+import httpx
+
+from matrx.cli.cursor_proxy import DEFAULT_PORT, HEALTH_PATH, PROXY_HOST
+from matrx.cli.state import config_dir
+
+logger = logging.getLogger(__name__)
+
+_LAUNCH_AGENT_LABEL = "so.mtrx.cursor-proxy"
+_SYSTEMD_UNIT_NAME = "mtrx-cursor-proxy.service"
+
+
+def pid_file_path() -> Path:
+    return config_dir() / "cursor-proxy.pid"
+
+
+def proxy_config_path() -> Path:
+    return config_dir() / "cursor-proxy.json"
+
+
+def _find_python() -> str:
+    """Return the path to the current Python interpreter."""
+    return sys.executable
+
+
+def _launch_agent_plist_path() -> Path:
+    return Path.home() / "Library" / "LaunchAgents" / f"{_LAUNCH_AGENT_LABEL}.plist"
+
+
+def _systemd_unit_path() -> Path:
+    return Path.home() / ".config" / "systemd" / "user" / _SYSTEMD_UNIT_NAME
+
+
+# ---------------------------------------------------------------------------
+# Proxy config persistence (key + base_url needed to start the daemon)
+# ---------------------------------------------------------------------------
+
+def save_proxy_config(
+    *,
+    matrx_key: str,
+    matrx_base_url: str,
+    host: str = PROXY_HOST,
+    port: int = DEFAULT_PORT,
+) -> Path:
+    conf = proxy_config_path()
+    conf.parent.mkdir(parents=True, exist_ok=True)
+    conf.write_text(
+        json.dumps({
+            "matrx_key": matrx_key,
+            "matrx_base_url": matrx_base_url,
+            "host": host,
+            "port": port,
+        }),
+        encoding="utf-8",
+    )
+    os.chmod(conf, 0o600)
+    return conf
+
+
+def load_proxy_config() -> dict | None:
+    conf = proxy_config_path()
+    if not conf.exists():
+        return None
+    try:
+        return json.loads(conf.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Service lifecycle
+# ---------------------------------------------------------------------------
+
+def install_service(
+    *,
+    matrx_key: str,
+    matrx_base_url: str,
+    host: str = PROXY_HOST,
+    port: int = DEFAULT_PORT,
+) -> bool:
+    """Install and start the proxy as a background service."""
+    save_proxy_config(
+        matrx_key=matrx_key,
+        matrx_base_url=matrx_base_url,
+        host=host,
+        port=port,
+    )
+
+    system = platform.system()
+    if system == "Darwin":
+        return _install_macos(host, port)
+    if system == "Linux":
+        return _install_linux(host, port)
+    return _install_generic(host, port)
+
+
+def uninstall_service() -> bool:
+    """Stop and remove the background service."""
+    system = platform.system()
+    ok = True
+    if system == "Darwin":
+        ok = _uninstall_macos()
+    elif system == "Linux":
+        ok = _uninstall_linux()
+    else:
+        ok = _stop_by_pid()
+
+    proxy_config_path().unlink(missing_ok=True)
+    pid_file_path().unlink(missing_ok=True)
+    return ok
+
+
+def is_proxy_running(host: str = PROXY_HOST, port: int = DEFAULT_PORT) -> bool:
+    """Check if the proxy is running and healthy."""
+    try:
+        resp = httpx.get(
+            f"http://{host}:{port}{HEALTH_PATH}",
+            timeout=3,
+        )
+        return resp.status_code == 200
+    except Exception:
+        return False
+
+
+def get_proxy_status(host: str = PROXY_HOST, port: int = DEFAULT_PORT) -> dict | None:
+    """Get proxy status info, or None if not reachable."""
+    try:
+        resp = httpx.get(
+            f"http://{host}:{port}{HEALTH_PATH}",
+            timeout=3,
+        )
+        if resp.status_code == 200:
+            return resp.json()
+    except Exception:
+        pass
+    return None
+
+
+# ---------------------------------------------------------------------------
+# macOS: Launch Agent
+# ---------------------------------------------------------------------------
+
+def _install_macos(host: str, port: int) -> bool:
+    _unload_launchd()
+
+    python = _find_python()
+    conf = str(proxy_config_path())
+    pid = str(pid_file_path())
+    log_dir = config_dir() / "logs"
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    plist_content = textwrap.dedent(f"""\
+        <?xml version="1.0" encoding="UTF-8"?>
+        <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+          "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+        <plist version="1.0">
+        <dict>
+            <key>Label</key>
+            <string>{_LAUNCH_AGENT_LABEL}</string>
+            <key>ProgramArguments</key>
+            <array>
+                <string>{python}</string>
+                <string>-m</string>
+                <string>matrx.cli.cursor_daemon</string>
+                <string>--config</string>
+                <string>{conf}</string>
+                <string>--pid-file</string>
+                <string>{pid}</string>
+            </array>
+            <key>RunAtLoad</key>
+            <true/>
+            <key>KeepAlive</key>
+            <true/>
+            <key>StandardOutPath</key>
+            <string>{log_dir / "cursor-proxy.out.log"}</string>
+            <key>StandardErrorPath</key>
+            <string>{log_dir / "cursor-proxy.err.log"}</string>
+        </dict>
+        </plist>
+    """)
+
+    plist_path = _launch_agent_plist_path()
+    plist_path.parent.mkdir(parents=True, exist_ok=True)
+    plist_path.write_text(plist_content, encoding="utf-8")
+
+    result = subprocess.run(
+        ["launchctl", "load", "-w", str(plist_path)],
+        capture_output=True,
+        timeout=10,
+    )
+    if result.returncode != 0:
+        logger.warning("launchctl load failed: %s", result.stderr.decode(errors="replace"))
+        return _install_generic(host, port)
+
+    time.sleep(1)
+    return is_proxy_running(host, port)
+
+
+def _unload_launchd() -> None:
+    plist_path = _launch_agent_plist_path()
+    if plist_path.exists():
+        subprocess.run(
+            ["launchctl", "unload", str(plist_path)],
+            capture_output=True,
+            timeout=10,
+        )
+
+
+def _uninstall_macos() -> bool:
+    _unload_launchd()
+    plist_path = _launch_agent_plist_path()
+    plist_path.unlink(missing_ok=True)
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Linux: systemd user unit
+# ---------------------------------------------------------------------------
+
+def _install_linux(host: str, port: int) -> bool:
+    python = _find_python()
+    conf = str(proxy_config_path())
+    pid = str(pid_file_path())
+
+    unit_content = textwrap.dedent(f"""\
+        [Unit]
+        Description=MTRX Cursor MITM Proxy
+        After=network.target
+
+        [Service]
+        Type=simple
+        ExecStart={python} -m matrx.cli.cursor_daemon --config {conf} --pid-file {pid}
+        Restart=on-failure
+        RestartSec=5
+
+        [Install]
+        WantedBy=default.target
+    """)
+
+    unit_path = _systemd_unit_path()
+    unit_path.parent.mkdir(parents=True, exist_ok=True)
+    unit_path.write_text(unit_content, encoding="utf-8")
+
+    subprocess.run(["systemctl", "--user", "daemon-reload"], capture_output=True, timeout=10)
+    result = subprocess.run(
+        ["systemctl", "--user", "enable", "--now", _SYSTEMD_UNIT_NAME],
+        capture_output=True,
+        timeout=10,
+    )
+    if result.returncode != 0:
+        logger.warning("systemctl enable failed: %s", result.stderr.decode(errors="replace"))
+        return _install_generic(host, port)
+
+    time.sleep(1)
+    return is_proxy_running(host, port)
+
+
+def _uninstall_linux() -> bool:
+    subprocess.run(
+        ["systemctl", "--user", "disable", "--now", _SYSTEMD_UNIT_NAME],
+        capture_output=True,
+        timeout=10,
+    )
+    unit_path = _systemd_unit_path()
+    unit_path.unlink(missing_ok=True)
+    subprocess.run(["systemctl", "--user", "daemon-reload"], capture_output=True, timeout=10)
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Generic: detached subprocess with PID file
+# ---------------------------------------------------------------------------
+
+def _install_generic(host: str, port: int) -> bool:
+    """Start the proxy as a detached subprocess (works everywhere)."""
+    _stop_by_pid()
+
+    python = _find_python()
+    conf = str(proxy_config_path())
+    pid = str(pid_file_path())
+
+    kwargs: dict = {
+        "start_new_session": True,
+    }
+    if sys.platform == "win32":
+        kwargs = {
+            "creationflags": subprocess.CREATE_NO_WINDOW | subprocess.DETACHED_PROCESS,
+        }
+
+    log_dir = config_dir() / "logs"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    stdout_log = open(log_dir / "cursor-proxy.out.log", "a")
+    stderr_log = open(log_dir / "cursor-proxy.err.log", "a")
+
+    subprocess.Popen(
+        [python, "-m", "matrx.cli.cursor_daemon", "--config", conf, "--pid-file", pid],
+        stdout=stdout_log,
+        stderr=stderr_log,
+        stdin=subprocess.DEVNULL,
+        **kwargs,
+    )
+
+    # Wait a moment for startup
+    for _ in range(10):
+        time.sleep(0.5)
+        if is_proxy_running(host, port):
+            return True
+    return False
+
+
+def _stop_by_pid() -> bool:
+    pf = pid_file_path()
+    if not pf.exists():
+        return True
+    try:
+        pid = int(pf.read_text(encoding="utf-8").strip())
+        os.kill(pid, signal.SIGTERM)
+        time.sleep(0.5)
+    except (ValueError, ProcessLookupError, PermissionError):
+        pass
+    pf.unlink(missing_ok=True)
+    return True

package/src/matrx/cli/launcher.py

@@ -80,6 +80,15 @@ class LaunchPlan:
     orchestration: dict | None = None
 
 
+def _runtime_agent_basename(tool: str) -> tuple[str, str, list[str], str]:
+    if tool == "codex":
+        return "codex-cli", "Codex CLI", ["cli", "codex"], "codex"
+    if tool == "claude":
+        return "claude-cli", "Claude CLI", ["claude", "cli"], "claude_code"
+    normalized = f"{tool}-cli"
+    return normalized, f"{tool.capitalize()} CLI", ["cli", tool], tool
+
+
 def configured_route(state: dict, tool: str) -> str | None:
     route = state.get("defaults", {}).get(tool)
     if route in VALID_ROUTES:
@@ -132,6 +141,12 @@ def build_launch_plan(
     env = dict(source_env)
     auth_source = ""
     launch_args = list(passthrough_args or [])
+    orchestration = _build_orchestration_metadata(
+        state=state,
+        tool=tool,
+        route=route,
+        env=source_env,
+    )
 
     if tool == "codex":
         env, auth_source, launch_args = _build_codex_env(
@@ -139,9 +154,15 @@ def build_launch_plan(
             route,
             env,
             launch_args,
+            orchestration=orchestration,
         )
     elif tool == "claude":
-        env, auth_source = _build_claude_env(state, route, env)
+        env, auth_source = _build_claude_env(
+            state,
+            route,
+            env,
+            orchestration=orchestration,
+        )
     else:
         raise ValueError(f"Unsupported tool: {tool}")
 
@@ -152,12 +173,7 @@ def build_launch_plan(
         args=launch_args,
         env=env,
         auth_source=auth_source,
-        orchestration=_build_orchestration_metadata(
-            state=state,
-            tool=tool,
-            route=route,
-            env=source_env,
-        ),
+        orchestration=orchestration,
     )
 
 
@@ -438,6 +454,8 @@ def _build_codex_env(
     route: str,
     env: dict[str, str],
     passthrough_args: list[str],
+    *,
+    orchestration: dict | None = None,
 ) -> tuple[dict[str, str], str, list[str]]:
     matrx = state["auth"]["matrx"]
     openai = state["auth"]["openai"]
@@ -457,10 +475,14 @@ def _build_codex_env(
         env_b64 = base64.b64encode(json.dumps(env_snap).encode()).decode() if env_snap else ""
         session_id = str(uuid.uuid4())
         group_id, project_id = _resolve_matrx_context_overrides(state, env)
+        runtime_agent_id = (
+            (orchestration or {}).get("agent_id")
+            or _runtime_agent_basename("codex")[0]
+        )
         header_parts = [
             f'"Authorization" = "Bearer {access_token}"',
             f'"X-Matrx-Key" = "{mx_key}"',
-            '"X-Matrx-Agent-Id" = "codex-cli"',
+            f'"X-Matrx-Agent-Id" = "{runtime_agent_id}"',
             '"X-Matrx-Provider" = "codex"',
             f'"X-Matrx-Session-Id" = "{session_id}"',
         ]
@@ -501,6 +523,8 @@ def _build_claude_env(
     state: dict,
     route: str,
     env: dict[str, str],
+    *,
+    orchestration: dict | None = None,
 ) -> tuple[dict[str, str], str]:
     matrx = state["auth"]["matrx"]
     anthropic = state["auth"]["anthropic"]
@@ -520,13 +544,17 @@ def _build_claude_env(
         env.pop("ANTHROPIC_API_KEY", None)
         group_id, project_id = _resolve_matrx_context_overrides(state, env)
         session_id = str(uuid.uuid4())
+        runtime_agent_id = (
+            (orchestration or {}).get("agent_id")
+            or _runtime_agent_basename("claude")[0]
+        )
         # Evolutionary scaffolding: env snapshot for AI context injection
         env_snap = _capture_env_snapshot()
         env_b64 = base64.b64encode(json.dumps(env_snap).encode()).decode() if env_snap else ""
         custom_headers = "\n".join(
             [
                 f"x-matrx-key: {mx_key}",
-                "x-matrx-agent-id: claude-cli",
+                f"x-matrx-agent-id: {runtime_agent_id}",
                 "x-matrx-provider: claude_code",
                 f"x-matrx-session-id: {session_id}",
             ]
@@ -592,27 +620,18 @@ def _build_orchestration_metadata(
     if not mx_key:
         return None
 
-    if tool == "codex":
-        agent_id = "codex-cli"
-        provider = "codex"
-        capabilities = ["cli", "codex"]
-        name = "Codex CLI"
-    elif tool == "claude":
-        agent_id = "claude-cli"
-        provider = "claude_code"
-        capabilities = ["claude", "cli"]
-        name = "Claude CLI"
-    else:
-        agent_id = f"{tool}-cli"
-        provider = tool
-        capabilities = ["cli", tool]
-        name = f"{tool.capitalize()} CLI"
+    agent_kind, name, capabilities, provider = _runtime_agent_basename(tool)
+    agent_id = f"{agent_kind}-{uuid.uuid4().hex[:8]}"
 
     _, project_id = _resolve_matrx_context_overrides(state, env)
+    base_url = ensure_root_url(
+        env.get("MATRX_BASE_URL") or state.get("auth", {}).get("matrx", {}).get("base_url")
+    )
     return {
-        "base_url": ensure_root_url(state.get("auth", {}).get("matrx", {}).get("base_url")),
+        "base_url": base_url,
         "matrx_key": mx_key,
         "agent_id": agent_id,
+        "agent_kind": agent_kind,
         "provider": provider,
         "name": name,
         "capabilities": capabilities,
@@ -633,6 +652,7 @@ def _best_effort_register_cli_agent(orchestration: dict) -> None:
     payload = {
         "agent_id": agent_id,
         "name": orchestration.get("name") or agent_id,
+        "agent_kind": orchestration.get("agent_kind"),
         "capabilities": list(orchestration.get("capabilities") or []),
         "max_concurrent_tasks": 1,
     }
@@ -736,8 +756,8 @@ def _validate_claude_launch_plan(plan: LaunchPlan, state: dict) -> None:
         raise ValueError("Claude Matrx route is missing ANTHROPIC_CUSTOM_HEADERS with X-Matrx-Session-Id")
     if "x-matrx-provider: claude_code" not in lowered_headers:
         raise ValueError("Claude Matrx route is missing ANTHROPIC_CUSTOM_HEADERS with X-Matrx-Provider=claude_code")
-    if "x-matrx-agent-id: claude-cli" not in lowered_headers:
-        raise ValueError("Claude Matrx route is missing ANTHROPIC_CUSTOM_HEADERS with X-Matrx-Agent-Id=claude-cli")
+    if "x-matrx-agent-id:" not in lowered_headers:
+        raise ValueError("Claude Matrx route is missing ANTHROPIC_CUSTOM_HEADERS with X-Matrx-Agent-Id")
 
     if plan.env.get("ANTHROPIC_AUTH_TOKEN"):
         raise ValueError("Claude Matrx route should not set ANTHROPIC_AUTH_TOKEN")