mtrx-cli 0.1.8 → 0.1.10

package/src/matrx/cli/launcher.py

@@ -1,16 +1,18 @@
 from __future__ import annotations
 
+import datetime as dt
 import base64
 import hashlib
-import datetime as dt
-import httpx
 import json
 import os
 import platform
 import re
 import shutil
 import subprocess
+import threading
 import uuid
+
+import httpx
 try:
     import tomllib
 except ModuleNotFoundError:  # pragma: no cover - Python 3.10 compatibility
@@ -23,6 +25,7 @@ from matrx.cli.state import (
     ensure_root_url,
     ensure_v1_url,
     get_workspace_binding,
+    normalize_matrx_key,
     set_workspace_binding,
 )
 
@@ -74,6 +77,7 @@ class LaunchPlan:
     args: list[str]
     env: dict[str, str]
     auth_source: str
+    orchestration: dict | None = None
 
 
 def configured_route(state: dict, tool: str) -> str | None:
@@ -124,7 +128,8 @@ def build_launch_plan(
         raise ValueError(f"{tool} executable not found in PATH")
 
     route = resolve_route(state, tool, route_override)
-    env = dict(os.environ if base_env is None else base_env)
+    source_env = dict(os.environ if base_env is None else base_env)
+    env = dict(source_env)
     auth_source = ""
     launch_args = list(passthrough_args or [])
 
@@ -147,6 +152,12 @@ 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,
+        ),
     )
 
 
@@ -180,8 +191,20 @@ def prepare_routed_setup(
 
 
 def launch(plan: LaunchPlan) -> int:
-    result = subprocess.run([plan.executable, *plan.args], env=plan.env, check=False)
-    return int(result.returncode)
+    heartbeat_stop = None
+    heartbeat_thread = None
+    if plan.orchestration:
+        _best_effort_register_cli_agent(plan.orchestration)
+        heartbeat_stop, heartbeat_thread = _start_orchestration_heartbeat(plan.orchestration)
+
+    try:
+        result = subprocess.run([plan.executable, *plan.args], env=plan.env, check=False)
+        return int(result.returncode)
+    finally:
+        if heartbeat_stop is not None:
+            heartbeat_stop.set()
+        if heartbeat_thread is not None:
+            heartbeat_thread.join(timeout=2)
 
 
 def validate_launch_plan(plan: LaunchPlan, state: dict) -> None:
@@ -360,16 +383,16 @@ def _resolve_matrx_route_key(
     state: dict,
     env: dict[str, str],
 ) -> tuple[str, str]:
-    env_key = (env.get("MTRX_KEY") or "").strip()
+    env_key = normalize_matrx_key(env.get("MTRX_KEY"))
     if env_key:
         return env_key, "env_matrx_key"
 
     binding = get_workspace_binding(state, cwd=_workspace_cwd(env))
-    binding_key = ((binding or {}).get("matrx_key") or "").strip()
+    binding_key = normalize_matrx_key((binding or {}).get("matrx_key"))
     if binding_key:
         return binding_key, "workspace_matrx_key"
 
-    saved_key = (state.get("auth", {}).get("matrx", {}).get("key") or "").strip()
+    saved_key = normalize_matrx_key(state.get("auth", {}).get("matrx", {}).get("key"))
     if saved_key:
         return saved_key, "saved_matrx_key"
 
@@ -555,6 +578,135 @@ def _build_claude_env(
     return env, "existing_claude_auth"
 
 
+def _build_orchestration_metadata(
+    *,
+    state: dict,
+    tool: str,
+    route: str,
+    env: dict[str, str],
+) -> dict | None:
+    if route != "matrx":
+        return None
+
+    mx_key, _ = _resolve_matrx_route_key(state, env)
+    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"
+
+    _, project_id = _resolve_matrx_context_overrides(state, env)
+    return {
+        "base_url": ensure_root_url(state.get("auth", {}).get("matrx", {}).get("base_url")),
+        "matrx_key": mx_key,
+        "agent_id": agent_id,
+        "provider": provider,
+        "name": name,
+        "capabilities": capabilities,
+        "project_id": project_id or None,
+        "heartbeat_interval_seconds": 60,
+    }
+
+
+def _best_effort_register_cli_agent(orchestration: dict) -> None:
+    if not orchestration:
+        return
+    base_url = (orchestration.get("base_url") or "").rstrip("/")
+    matrx_key = (orchestration.get("matrx_key") or "").strip()
+    agent_id = (orchestration.get("agent_id") or "").strip()
+    if not base_url or not matrx_key or not agent_id:
+        return
+
+    payload = {
+        "agent_id": agent_id,
+        "name": orchestration.get("name") or agent_id,
+        "capabilities": list(orchestration.get("capabilities") or []),
+        "max_concurrent_tasks": 1,
+    }
+    headers = {
+        "X-Matrx-Key": matrx_key,
+        "X-Matrx-Agent-Id": agent_id,
+        "X-Matrx-Provider": orchestration.get("provider") or "cli",
+        "Content-Type": "application/json",
+    }
+    project_id = (orchestration.get("project_id") or "").strip()
+    if project_id:
+        headers["X-Matrx-Project-Id"] = project_id
+
+    try:
+        with httpx.Client(timeout=5) as client:
+            response = client.post(
+                f"{base_url}/v1/orchestration/agents/register",
+                headers=headers,
+                json=payload,
+            )
+        if response.status_code in {404, 401, 403}:
+            return
+        response.raise_for_status()
+    except httpx.HTTPError:
+        return
+
+
+def _heartbeat_cli_agent(orchestration: dict, stop_event) -> None:
+    base_url = (orchestration.get("base_url") or "").rstrip("/")
+    matrx_key = (orchestration.get("matrx_key") or "").strip()
+    agent_id = (orchestration.get("agent_id") or "").strip()
+    if not base_url or not matrx_key or not agent_id:
+        return
+
+    headers = {
+        "X-Matrx-Key": matrx_key,
+        "X-Matrx-Agent-Id": agent_id,
+        "X-Matrx-Provider": orchestration.get("provider") or "cli",
+    }
+    project_id = (orchestration.get("project_id") or "").strip()
+    if project_id:
+        headers["X-Matrx-Project-Id"] = project_id
+
+    interval = int(orchestration.get("heartbeat_interval_seconds") or 60)
+    while True:
+        try:
+            with httpx.Client(timeout=5) as client:
+                response = client.patch(
+                    f"{base_url}/v1/orchestration/agents/{agent_id}/heartbeat",
+                    headers=headers,
+                )
+            if response.status_code in {404, 401, 403}:
+                return
+        except httpx.HTTPError:
+            return
+        if stop_event.wait(interval):
+            return
+
+
+def _start_orchestration_heartbeat(
+    orchestration: dict,
+) -> tuple[threading.Event, threading.Thread] | tuple[None, None]:
+    if not orchestration:
+        return None, None
+    stop_event = threading.Event()
+    thread = threading.Thread(
+        target=_heartbeat_cli_agent,
+        args=(orchestration, stop_event),
+        daemon=True,
+    )
+    thread.start()
+    return stop_event, thread
+
+
 def _validate_claude_launch_plan(plan: LaunchPlan, state: dict) -> None:
     """Validate Claude launch plan before spawning."""
     if plan.route != "matrx":

package/src/matrx/cli/main.py

@@ -9,6 +9,7 @@ import sys
 import threading
 import urllib.parse
 import webbrowser
+from pathlib import Path
 
 import httpx
 
@@ -29,6 +30,15 @@ from matrx.cli.launcher import (
     resolve_route,
     validate_launch_plan,
 )
+from matrx.cli.cursor_config import (
+    configure_cursor_for_proxy,
+    cursor_is_running,
+    cursor_state_db_path,
+    print_manual_setup_instructions,
+    read_cursor_settings,
+    restore_cursor_settings,
+)
+from matrx.cli.cursor_proxy import CursorProxyServer
 from matrx.cli.state import (
     ensure_app_url,
     ensure_root_url,
@@ -36,6 +46,7 @@ from matrx.cli.state import (
     get_workspace_binding,
     load_state,
     mask_secret,
+    normalize_matrx_key,
     save_state,
 )
 
@@ -62,6 +73,8 @@ def main(argv: list[str] | None = None) -> int:
         return _cmd_personal(args)
     if args.command in {"codex", "claude"}:
         return _cmd_launch(args.command, args.route, remainder)
+    if args.command == "cursor":
+        return _cmd_cursor(args.route, args.port)
 
     parser.print_help()
     return 1
@@ -81,7 +94,7 @@ def _build_parser() -> argparse.ArgumentParser:
     login.add_argument("--import", dest="do_import", action="store_true")
 
     use = subparsers.add_parser("use")
-    use.add_argument("tool", choices=["codex", "claude"])
+    use.add_argument("tool", choices=["codex", "claude", "cursor"])
     use.add_argument("route", choices=["direct", "matrx"])
 
     subparsers.add_parser("help")
@@ -100,6 +113,10 @@ def _build_parser() -> argparse.ArgumentParser:
     claude = subparsers.add_parser("claude")
     claude.add_argument("--route", choices=["direct", "matrx"])
 
+    cursor = subparsers.add_parser("cursor")
+    cursor.add_argument("--route", choices=["direct", "matrx"])
+    cursor.add_argument("--port", type=int, default=0)
+
     return parser
 
 
@@ -123,6 +140,73 @@ def _prompt_for_secret(prompt: str) -> str:
     return input(f"{prompt}: ").strip()
 
 
+def _legacy_shell_proxy_profiles() -> list[Path]:
+    markers = (
+        "# BEGIN MATRX PROXY (CODEX)",
+        'claude() { matrx_refresh_routing; command claude "$@"; }',
+    )
+    profiles: list[Path] = []
+    for path in (
+        Path.home() / ".zshrc",
+        Path.home() / ".zprofile",
+        Path.home() / ".bashrc",
+        Path.home() / ".bash_profile",
+    ):
+        if not path.exists():
+            continue
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        if any(marker in text for marker in markers):
+            profiles.append(path)
+    return profiles
+
+
+def _active_claude_proxy_env(env: dict[str, str] | None = None) -> dict[str, str]:
+    env = env or os.environ
+    active: dict[str, str] = {}
+
+    base_url = (env.get("ANTHROPIC_BASE_URL") or "").strip()
+    if base_url and "api.anthropic.com" not in base_url:
+        active["ANTHROPIC_BASE_URL"] = base_url
+
+    custom_headers = (env.get("ANTHROPIC_CUSTOM_HEADERS") or "").strip()
+    if "x-matrx-" in custom_headers.lower():
+        active["ANTHROPIC_CUSTOM_HEADERS"] = "x-matrx-*"
+
+    active_route = (env.get("MATRX_ACTIVE_ROUTE") or "").strip()
+    if active_route in {"proxy", "proxy_forced"}:
+        active["MATRX_ACTIVE_ROUTE"] = active_route
+
+    return active
+
+
+def _print_claude_shell_proxy_hint(*, stream=None) -> None:
+    stream = stream or sys.stdout
+    profiles = _legacy_shell_proxy_profiles()
+    active_env = _active_claude_proxy_env()
+    if not profiles and not active_env:
+        return
+
+    if profiles:
+        joined = ", ".join(str(path) for path in profiles)
+        print(
+            f"[warn] Legacy shell MATRX proxy setup found in {joined}; plain `claude` will still be proxied outside `mtrx claude`.",
+            file=stream,
+        )
+    if active_env:
+        keys = ", ".join(sorted(active_env))
+        print(
+            f"[warn] Current shell still exports Claude proxy env ({keys}); plain `claude` in this shell will still be proxied.",
+            file=stream,
+        )
+    print(
+        "[warn] Cleanup: run `unfunction claude 2>/dev/null || true` and `unset ANTHROPIC_BASE_URL ANTHROPIC_CUSTOM_HEADERS ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN MATRX_ACTIVE_ROUTE MATRX_BASE_URL MATRX_API_KEY MATRX_CLAUDE_MODE MATRX_FALLBACK_ENABLED MATRX_PROXY_TIMEOUT_SEC ANTHROPIC_DIRECT_BASE_URL`.",
+        file=stream,
+    )
+
+
 def _derive_callback_payload(params: dict[str, list[str]]) -> dict[str, str | None]:
     def _one(name: str) -> str | None:
         values = params.get(name) or []
@@ -140,7 +224,22 @@ def _derive_callback_payload(params: dict[str, list[str]]) -> dict[str, str | No
     }
 
 
-def _matrx_browser_callback_html(payload: dict[str, str | None]) -> bytes:
+def _matrx_browser_redirect_url(app_url: str | None, payload: dict[str, str | None]) -> str | None:
+    base = (app_url or "").strip().rstrip("/")
+    if not base:
+        return None
+
+    project_id = (payload.get("project_id") or "").strip()
+    if project_id:
+        return f"{base}/dashboard/projects/{urllib.parse.quote(project_id, safe='')}"
+    return f"{base}/dashboard"
+
+
+def _matrx_browser_callback_html(
+    payload: dict[str, str | None],
+    *,
+    app_url: str | None = None,
+) -> bytes:
     error = (payload.get("error") or "").strip()
     if error:
         escaped_error = html.escape(error)
@@ -152,11 +251,23 @@ def _matrx_browser_callback_html(payload: dict[str, str | None]) -> bytes:
             "</body></html>"
         )
     else:
-        body = (
-            "<html><body><h1>Matrx login complete.</h1>"
-            "<p>You can close this window and return to the terminal.</p>"
-            "</body></html>"
-        )
+        redirect_url = _matrx_browser_redirect_url(app_url, payload)
+        if redirect_url:
+            escaped_url = html.escape(redirect_url, quote=True)
+            body = (
+                "<html><head>"
+                f'<meta http-equiv="refresh" content="0;url={escaped_url}">'
+                "</head><body><h1>Matrx login complete.</h1>"
+                "<p>Redirecting to the Matrx dashboard.</p>"
+                f'<p>If you are not redirected automatically, <a href="{escaped_url}">open the dashboard</a>.</p>'
+                "</body></html>"
+            )
+        else:
+            body = (
+                "<html><body><h1>Matrx login complete.</h1>"
+                "<p>You can close this window and return to the terminal.</p>"
+                "</body></html>"
+            )
     return body.encode("utf-8")
 
 
@@ -184,7 +295,7 @@ def _run_matrx_browser_login(
             payload = _derive_callback_payload(urllib.parse.parse_qs(parsed.query))
             result.update(payload)
             event.set()
-            body = _matrx_browser_callback_html(payload)
+            body = _matrx_browser_callback_html(payload, app_url=app_url)
             self.send_response(200)
             self.send_header("Content-Type", "text/html; charset=utf-8")
             self.send_header("Content-Length", str(len(body)))
@@ -376,6 +487,8 @@ def _cmd_use(args) -> int:
     path = save_state(state)
     print(f"Default route for {args.tool}: {args.route}")
     print(f"Saved to {path}")
+    if args.tool == "claude" and args.route == "direct":
+        _print_claude_shell_proxy_hint()
     return 0
 
 
@@ -385,6 +498,7 @@ def _cmd_status() -> int:
     print("Defaults:")
     print(f"  codex: {_default_route_label(configured_route(state, 'codex'))}")
     print(f"  claude: {_default_route_label(configured_route(state, 'claude'))}")
+    print(f"  cursor: {_default_route_label(configured_route(state, 'cursor'))}")
     print("Auth:")
     print(
         "  matrx: "
@@ -415,6 +529,16 @@ def _cmd_status() -> int:
     print("Executables:")
     print(f"  codex: {find_executable('codex') or 'not found'}")
     print(f"  claude: {find_executable('claude') or 'not found'}")
+    profiles = _legacy_shell_proxy_profiles()
+    active_env = _active_claude_proxy_env()
+    if profiles or active_env:
+        print("Shell:")
+        if profiles:
+            joined = ", ".join(str(path) for path in profiles)
+            print(f"  legacy claude proxy setup: present in {joined}")
+        if active_env:
+            keys = ", ".join(sorted(active_env))
+            print(f"  active claude proxy env: {keys}")
     return 0
 
 
@@ -527,6 +651,17 @@ def _cmd_doctor() -> int:
             print(f"[fail] {tool} executable not found")
             failures += 1
 
+    db_path = cursor_state_db_path()
+    if db_path.exists():
+        print(f"[ok] Cursor settings DB: {db_path}")
+        cursor_settings = read_cursor_settings(db_path)
+        if cursor_settings:
+            print("[ok] Cursor settings readable")
+        else:
+            print("[warn] Cursor settings key not found (set a custom API key in Cursor first)")
+    else:
+        print(f"[warn] Cursor settings DB not found at {db_path}")
+
     matrx_key = (state["auth"]["matrx"].get("key") or "").strip()
     if matrx_key:
         print("[ok] Matrx key saved")
@@ -558,13 +693,30 @@ def _cmd_doctor() -> int:
     else:
         print(f"[warn] Local Claude OAuth not found at {claude_credentials_path()}")
 
-    for tool in ("codex", "claude"):
+    profiles = _legacy_shell_proxy_profiles()
+    if profiles:
+        joined = ", ".join(str(path) for path in profiles)
+        print(
+            f"[warn] Legacy shell MATRX proxy setup found in {joined}; plain `claude` will still be proxied outside `mtrx claude`.",
+        )
+
+    active_env = _active_claude_proxy_env()
+    if active_env:
+        keys = ", ".join(sorted(active_env))
+        print(f"[warn] Current shell still exports Claude proxy env ({keys})")
+        print(
+            "[warn] Cleanup: `unfunction claude 2>/dev/null || true` and `unset ANTHROPIC_BASE_URL ANTHROPIC_CUSTOM_HEADERS ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN MATRX_ACTIVE_ROUTE MATRX_BASE_URL MATRX_API_KEY MATRX_CLAUDE_MODE MATRX_FALLBACK_ENABLED MATRX_PROXY_TIMEOUT_SEC ANTHROPIC_DIRECT_BASE_URL`",
+        )
+
+    for tool in ("codex", "claude", "cursor"):
         route = configured_route(state, tool)
         if route == "matrx" and not _has_matrx_login(state, env=os.environ):
             print(f"[fail] Default {tool} route is matrx but no Matrx key is saved")
             failures += 1
         elif route is None:
             print(f"[warn] Default {tool} route not chosen yet (first `mtrx {tool}` launch will initialize it to matrx)")
+        if tool == "cursor":
+            continue
         config_status = get_tool_config_status(state, tool)
         if tool == "codex" and config_status["verified"] and not config_status["configured"]:
             if route == "matrx":
@@ -591,6 +743,8 @@ def _cmd_launch(tool: str, route: str | None, remainder: list[str]) -> int:
         if effective_route == "matrx":
             state, login_changed = _complete_matrx_login(state)
             auth_changed = auth_changed or login_changed
+            if login_changed:
+                save_state(state)
             if tool == "codex":
                 _complete_codex_login()
             if tool == "claude":
@@ -626,16 +780,128 @@ def _cmd_launch(tool: str, route: str | None, remainder: list[str]) -> int:
     return launch(plan)
 
 
+def _cmd_cursor(route: str | None, port: int) -> int:
+    import signal as _signal
+
+    state = load_state()
+    route, promoted = _maybe_promote_direct_route(state, "cursor", route)
+    effective_route = resolve_route(state, "cursor", route)
+
+    if effective_route == "direct":
+        print("Cursor route set to direct — MTRX proxy disabled.")
+        return 0
+
+    try:
+        state, login_changed = _complete_matrx_login(state)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    initialized = initialize_first_launch_route(state, "cursor", route)
+
+    mx_key = (
+        normalize_matrx_key(os.environ.get("MTRX_KEY"))
+        or normalize_matrx_key(
+            (get_workspace_binding(state, cwd=os.getcwd()) or {}).get("matrx_key")
+        )
+        or normalize_matrx_key(state.get("auth", {}).get("matrx", {}).get("key"))
+    )
+    if not mx_key:
+        print("No Matrx key available. Run: mtrx login matrx --key mx_...", file=sys.stderr)
+        return 1
+
+    matrx_base_url = ensure_root_url(state.get("auth", {}).get("matrx", {}).get("base_url"))
+
+    binding = get_workspace_binding(state, cwd=os.getcwd()) or {}
+    group_id = (os.environ.get("MTRX_GROUP_ID") or binding.get("group_id") or "").strip()
+    project_id = (os.environ.get("MTRX_PROJECT_ID") or binding.get("project_id") or "").strip()
+
+    if initialized or login_changed or promoted:
+        save_state(state)
+    if initialized:
+        print(
+            "First-time setup: default route for cursor set to matrx. "
+            "Use `mtrx use cursor direct` to opt out.",
+        )
+
+    proxy = CursorProxyServer(
+        matrx_key=mx_key,
+        matrx_base_url=matrx_base_url,
+        group_id=group_id,
+        project_id=project_id,
+        port=port,
+    )
+    try:
+        proxy.start_background()
+    except RuntimeError as exc:
+        print(f"Failed to start proxy: {exc}", file=sys.stderr)
+        return 1
+
+    proxy_url = proxy.url
+    print(f"MTRX Cursor proxy running at {proxy_url}")
+    print(f"  session:    {proxy.session_id}")
+    print(f"  matrx_key:  {mask_secret(mx_key)}")
+    print(f"  upstream:   {matrx_base_url}")
+    if group_id:
+        print(f"  group:      {group_id}")
+    if project_id:
+        print(f"  project:    {project_id}")
+
+    previous_settings = None
+    db_path = cursor_state_db_path()
+    if db_path.exists():
+        if cursor_is_running():
+            print()
+            print("  [warn] Cursor is currently running.")
+            print("  Settings changes may require restarting Cursor to take effect.")
+        previous_settings = configure_cursor_for_proxy(proxy_url, db_path=db_path)
+        if previous_settings is not None:
+            print()
+            print("  Cursor settings configured automatically.")
+            print("  Restart Cursor if it is already open.")
+        else:
+            print_manual_setup_instructions(proxy_url)
+    else:
+        print_manual_setup_instructions(proxy_url)
+
+    print()
+    print("Press Ctrl+C to stop the proxy and restore settings.")
+
+    stop_event = threading.Event()
+
+    def _on_signal(sig, frame):
+        stop_event.set()
+
+    _signal.signal(_signal.SIGINT, _on_signal)
+    _signal.signal(_signal.SIGTERM, _on_signal)
+
+    stop_event.wait()
+
+    print()
+    print("Shutting down MTRX Cursor proxy...")
+    proxy.stop()
+
+    if previous_settings is not None:
+        if restore_cursor_settings(previous_settings, db_path=db_path):
+            print("Cursor settings restored to previous values.")
+        else:
+            print("[warn] Could not restore Cursor settings automatically.")
+            print("  You may need to reset your OpenAI API Key and Base URL in Cursor Settings > Models.")
+
+    print("Done.")
+    return 0
+
+
 def _has_matrx_login(state: dict, env: dict[str, str] | None = None) -> bool:
     env = env or {}
-    env_key = (env.get("MTRX_KEY") or "").strip()
+    env_key = normalize_matrx_key(env.get("MTRX_KEY"))
     if env_key:
         return True
     workspace_binding = get_workspace_binding(state, cwd=env.get("PWD") or os.getcwd()) or {}
-    workspace_key = (workspace_binding.get("matrx_key") or "").strip()
+    workspace_key = normalize_matrx_key(workspace_binding.get("matrx_key"))
     if workspace_key:
         return True
-    return bool((state.get("auth", {}).get("matrx", {}).get("key") or "").strip())
+    return bool(normalize_matrx_key(state.get("auth", {}).get("matrx", {}).get("key")))
 
 
 def _default_route_label(route: str | None) -> str: