mtrx-cli 0.1.10 → 0.1.13

package/src/matrx/cli/cursor_proxy.py

@@ -1,119 +1,115 @@
 """
-Local HTTP proxy server for routing Cursor IDE requests through MTRX.
+Local MITM forward proxy for transparent Cursor IDE traffic interception.
 
-Sits between Cursor and the MTRX API, injecting X-Matrx-* headers on every
-request so that Cursor gets the same full-featured proxy pipeline as
-``mtrx claude`` and ``mtrx codex`` (injection, compression, memory, groups,
-observability).
+Sits between Cursor and its backend servers (api2.cursor.sh, api3.cursor.sh,
+etc.), forwarding all traffic unchanged while mirroring metadata to the MTRX
+telemetry API for observability.
 
-Cursor's "Override OpenAI Base URL" sends ALL model requests (OpenAI,
-Anthropic, Google, etc.) in OpenAI Chat Completions format to the configured
-URL.  The MTRX router auto-detects the provider from the model name.
+Cursor is configured to route through this proxy via its ``http.proxy``
+setting.  TLS is terminated and re-encrypted using dynamically-signed
+certificates from the MTRX CA (see ``cursor_ca.py``).
+
+Design choices (informed by cursor-tap):
+  - Force HTTP/1.1 on both client and upstream sides to avoid HTTP/2
+    multiplexing complexity.
+  - Zero-buffer bidirectional streaming: never hold SSE/gRPC frames.
+  - Async telemetry shipping: never block the forwarding path.
 """
 
 from __future__ import annotations
 
 import asyncio
-import base64
-import json
 import logging
-import platform
 import os
-import shutil
 import signal
-import socket
-import threading
+import ssl
+import time
 import uuid
+from pathlib import Path
 from typing import Any
 
 import httpx
 
-logger = logging.getLogger(__name__)
+from matrx.cli.cursor_ca import CertCache, load_ca
 
-_PROXY_API_KEY = "mtrx-cursor-proxy"
-_FORWARDED_METHODS = {"POST", "GET", "PUT", "PATCH", "DELETE", "OPTIONS"}
+logger = logging.getLogger(__name__)
 
+DEFAULT_PORT = 8842
+PROXY_HOST = "127.0.0.1"
+HEALTH_PATH = "/__mtrx_health__"
 
-def _capture_env_snapshot() -> dict:
-    out: dict = {
-        "os": platform.system(),
-        "shell": os.environ.get("SHELL", os.environ.get("COMSPEC", "")),
-        "cwd": os.getcwd(),
-    }
-    out["venv"] = os.environ.get("VIRTUAL_ENV", "") or None
-    node = shutil.which("node")
-    if node:
-        import subprocess as _sp
-        try:
-            r = _sp.run([node, "-v"], capture_output=True, text=True, timeout=2)
-            out["node"] = r.stdout.strip() if r.returncode == 0 else None
-        except Exception:
-            out["node"] = None
-    else:
-        out["node"] = None
-    return out
+# Domains whose TLS we intercept for observability.
+_INTERCEPT_DOMAINS = {
+    "api2.cursor.sh",
+    "api3.cursor.sh",
+    "api4.cursor.sh",
+    "api5.cursor.sh",
+    "agentn.global.api5.cursor.sh",
+}
 
 
-class CursorProxyServer:
-    """Async HTTP proxy that injects MTRX headers and forwards to the MTRX API."""
+class MITMProxy:
+    """Async MITM forward proxy with telemetry mirroring."""
 
     def __init__(
         self,
         *,
         matrx_key: str,
         matrx_base_url: str,
-        session_id: str | None = None,
-        group_id: str = "",
-        project_id: str = "",
-        host: str = "127.0.0.1",
-        port: int = 0,
+        host: str = PROXY_HOST,
+        port: int = DEFAULT_PORT,
     ):
         self.matrx_key = matrx_key
         self.matrx_base_url = matrx_base_url.rstrip("/")
-        self.session_id = session_id or str(uuid.uuid4())
-        self.group_id = group_id
-        self.project_id = project_id
         self.host = host
         self.port = port
-
-        env_snap = _capture_env_snapshot()
-        self._env_b64 = (
-            base64.b64encode(json.dumps(env_snap).encode()).decode()
-            if env_snap
-            else ""
-        )
         self._server: asyncio.Server | None = None
-        self._http_client: httpx.AsyncClient | None = None
-        self._loop: asyncio.AbstractEventLoop | None = None
+        self._telemetry_client: httpx.AsyncClient | None = None
+        self._cert_cache: CertCache | None = None
+        self._request_count = 0
+
+    async def start(self) -> None:
+        ca_key, ca_cert = load_ca()
+        self._cert_cache = CertCache(ca_key, ca_cert)
+        self._telemetry_client = httpx.AsyncClient(timeout=10)
+        self._server = await asyncio.start_server(
+            self._handle_client, self.host, self.port
+        )
+        logger.info("MITM proxy listening on %s:%d", self.host, self.port)
+
+    async def serve_forever(self) -> None:
+        if self._server is None:
+            await self.start()
+        assert self._server is not None
+        async with self._server:
+            await self._server.serve_forever()
+
+    async def stop(self) -> None:
+        if self._server:
+            self._server.close()
+            await self._server.wait_closed()
+        if self._telemetry_client:
+            await self._telemetry_client.aclose()
 
     @property
-    def url(self) -> str:
-        return f"http://{self.host}:{self.port}/v1"
-
-    def _build_matrx_headers(self) -> dict[str, str]:
-        headers: dict[str, str] = {
-            "X-Matrx-Key": self.matrx_key,
-            "X-Matrx-Agent-Id": "cursor",
-            "X-Matrx-Provider": "cursor",
-            "X-Matrx-Session-Id": self.session_id,
-        }
-        if self.group_id:
-            headers["X-Matrx-Group"] = self.group_id
-        if self.project_id:
-            headers["X-Matrx-Project-Id"] = self.project_id
-        if self._env_b64:
-            headers["X-Matrx-Env"] = self._env_b64
-        return headers
-
-    async def _handle_request(
+    def request_count(self) -> int:
+        return self._request_count
+
+    # -----------------------------------------------------------------
+    # Connection handling
+    # -----------------------------------------------------------------
+
+    async def _handle_client(
         self,
         reader: asyncio.StreamReader,
         writer: asyncio.StreamWriter,
     ) -> None:
         try:
-            await self._process_http(reader, writer)
+            await self._process(reader, writer)
+        except (ConnectionResetError, BrokenPipeError, asyncio.IncompleteReadError):
+            pass
         except Exception:
-            logger.debug("cursor_proxy: connection error", exc_info=True)
+            logger.debug("proxy: connection error", exc_info=True)
         finally:
             try:
                 writer.close()
@@ -121,7 +117,7 @@ class CursorProxyServer:
             except Exception:
                 pass
 
-    async def _process_http(
+    async def _process(
         self,
         reader: asyncio.StreamReader,
         writer: asyncio.StreamWriter,
@@ -129,223 +125,425 @@ class CursorProxyServer:
         request_line = await reader.readline()
         if not request_line:
             return
-        parts = request_line.decode("utf-8", errors="replace").strip().split(" ", 2)
+        parts = request_line.decode("utf-8", errors="replace").strip().split()
         if len(parts) < 3:
             return
-        method, raw_path, _ = parts
+        method = parts[0].upper()
 
+        # Consume remaining request headers
         headers_raw: dict[str, str] = {}
         while True:
             line = await reader.readline()
-            decoded = line.decode("utf-8", errors="replace").strip()
-            if not decoded:
+            if not line or line in (b"\r\n", b"\n"):
                 break
+            decoded = line.decode("utf-8", errors="replace").strip()
             if ":" in decoded:
-                key, _, value = decoded.partition(":")
-                headers_raw[key.strip().lower()] = value.strip()
+                k, _, v = decoded.partition(":")
+                headers_raw[k.strip().lower()] = v.strip()
+
+        if method == "CONNECT":
+            target = parts[1]
+            hostname, _, port_str = target.rpartition(":")
+            port = int(port_str) if port_str else 443
+            if not hostname:
+                hostname = target
+                port = 443
+
+            writer.write(b"HTTP/1.1 200 Connection Established\r\n\r\n")
+            await writer.drain()
+
+            if hostname in _INTERCEPT_DOMAINS:
+                await self._mitm_intercept(reader, writer, hostname, port)
+            else:
+                await self._tunnel_passthrough(reader, writer, hostname, port)
+        elif method in ("GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"):
+            # Plain HTTP proxy request (non-CONNECT) -- handle health check
+            path = parts[1] if len(parts) > 1 else "/"
+            if HEALTH_PATH in path:
+                body = f'{{"status":"ok","requests":{self._request_count}}}'
+                resp = (
+                    f"HTTP/1.1 200 OK\r\n"
+                    f"Content-Type: application/json\r\n"
+                    f"Content-Length: {len(body)}\r\n"
+                    f"Connection: close\r\n\r\n{body}"
+                )
+                writer.write(resp.encode())
+                await writer.drain()
+            else:
+                writer.write(b"HTTP/1.1 405 Method Not Allowed\r\n\r\n")
+                await writer.drain()
+        else:
+            writer.write(b"HTTP/1.1 405 Method Not Allowed\r\n\r\n")
+            await writer.drain()
 
-        content_length = int(headers_raw.get("content-length", "0"))
-        body = b""
-        if content_length > 0:
-            body = await reader.readexactly(content_length)
+    # -----------------------------------------------------------------
+    # Opaque tunnel (non-intercepted domains)
+    # -----------------------------------------------------------------
 
-        if method not in _FORWARDED_METHODS:
-            self._send_response(writer, 405, {"error": "Method not allowed"})
+    async def _tunnel_passthrough(
+        self,
+        client_reader: asyncio.StreamReader,
+        client_writer: asyncio.StreamWriter,
+        hostname: str,
+        port: int,
+    ) -> None:
+        try:
+            up_reader, up_writer = await asyncio.open_connection(hostname, port)
+        except Exception:
             return
+        await self._pipe_bidirectional(client_reader, client_writer, up_reader, up_writer)
 
-        upstream_path = raw_path
-        if upstream_path.startswith("/v1/"):
-            upstream_path = "/" + upstream_path[4:]
-        elif upstream_path == "/v1":
-            upstream_path = "/"
+    # -----------------------------------------------------------------
+    # MITM interception (Cursor AI endpoints)
+    # -----------------------------------------------------------------
 
-        upstream_url = f"{self.matrx_base_url}/v1{upstream_path}"
+    async def _mitm_intercept(
+        self,
+        client_reader: asyncio.StreamReader,
+        client_writer: asyncio.StreamWriter,
+        hostname: str,
+        port: int,
+    ) -> None:
+        assert self._cert_cache is not None
 
-        upstream_headers: dict[str, str] = {}
-        for key, value in headers_raw.items():
-            if key in {"host", "connection", "transfer-encoding"}:
-                continue
-            if key == "authorization":
-                continue
-            upstream_headers[key] = value
+        # Use the hostname from the CONNECT request for the cert
+        # (matches SNI in virtually all cases, avoids ClientHello peeking)
+        server_ctx = self._cert_cache.get_ssl_context(hostname)
 
-        upstream_headers.update(self._build_matrx_headers())
-        upstream_headers["Authorization"] = f"Bearer {self.matrx_key}"
+        # Upgrade client connection to TLS (we are the "server")
+        loop = asyncio.get_running_loop()
+        transport = client_writer.transport
+        protocol = transport.get_protocol()
+        try:
+            new_transport = await loop.start_tls(
+                transport, protocol, server_ctx, server_side=True
+            )
+        except (ssl.SSLError, ConnectionError) as exc:
+            logger.debug("TLS handshake with client failed for %s: %s", hostname, exc)
+            return
+
+        tls_writer = asyncio.StreamWriter(new_transport, protocol, client_reader, loop)
+
+        # Connect to real upstream with TLS
+        upstream_ctx = ssl.create_default_context()
+        upstream_ctx.set_alpn_protocols(["http/1.1"])
+        try:
+            up_reader, up_writer = await asyncio.open_connection(
+                hostname, port, ssl=upstream_ctx
+            )
+        except Exception:
+            logger.debug("Failed to connect to upstream %s:%d", hostname, port)
+            return
 
-        is_stream = False
-        if body and method == "POST":
+        # Forward HTTP/1.1 traffic between decrypted client and upstream
+        try:
+            await self._forward_http(
+                client_reader, tls_writer, up_reader, up_writer, hostname
+            )
+        finally:
             try:
-                parsed = json.loads(body)
-                is_stream = parsed.get("stream", False)
-            except (json.JSONDecodeError, AttributeError):
+                up_writer.close()
+                await up_writer.wait_closed()
+            except Exception:
                 pass
 
-        assert self._http_client is not None
+    # -----------------------------------------------------------------
+    # HTTP/1.1 forwarding with telemetry
+    # -----------------------------------------------------------------
+
+    async def _forward_http(
+        self,
+        client_reader: asyncio.StreamReader,
+        client_writer: asyncio.StreamWriter,
+        up_reader: asyncio.StreamReader,
+        up_writer: asyncio.StreamWriter,
+        hostname: str,
+    ) -> None:
+        """Forward HTTP/1.1 request-response pairs, logging each to telemetry."""
+        while True:
+            req_line = await client_reader.readline()
+            if not req_line:
+                break
+            req_line_str = req_line.decode("utf-8", errors="replace").strip()
+            if not req_line_str:
+                break
+
+            parts = req_line_str.split(" ", 2)
+            method = parts[0] if parts else "?"
+            path = parts[1] if len(parts) > 1 else "/"
 
-        if is_stream:
-            await self._proxy_streaming(
-                writer, method, upstream_url, upstream_headers, body
+            up_writer.write(req_line)
+
+            req_headers, req_cl, req_chunked = await self._forward_headers(
+                client_reader, up_writer
             )
-        else:
-            await self._proxy_buffered(
-                writer, method, upstream_url, upstream_headers, body
+
+            req_body_size = await self._forward_body(
+                client_reader, up_writer, req_cl, req_chunked
+            )
+
+            started = time.monotonic()
+
+            resp_line = await up_reader.readline()
+            if not resp_line:
+                break
+            client_writer.write(resp_line)
+
+            resp_line_str = resp_line.decode("utf-8", errors="replace").strip()
+            status_code = 0
+            rp = resp_line_str.split(" ", 2)
+            if len(rp) >= 2:
+                try:
+                    status_code = int(rp[1])
+                except ValueError:
+                    pass
+
+            resp_headers, resp_cl, resp_chunked = await self._forward_headers(
+                up_reader, client_writer
+            )
+
+            content_type = resp_headers.get("content-type", "")
+            is_streaming = any(
+                t in content_type
+                for t in ("text/event-stream", "grpc", "proto", "connect")
+            )
+
+            resp_body_size = await self._forward_body(
+                up_reader, client_writer, resp_cl, resp_chunked
+            )
+
+            elapsed_ms = int((time.monotonic() - started) * 1000)
+            self._request_count += 1
+
+            asyncio.create_task(
+                self._ship_telemetry(
+                    hostname=hostname,
+                    method=method,
+                    path=path,
+                    status_code=status_code,
+                    req_body_size=req_body_size,
+                    resp_body_size=resp_body_size,
+                    elapsed_ms=elapsed_ms,
+                    content_type=content_type,
+                    is_streaming=is_streaming,
+                )
             )
 
-    async def _proxy_buffered(
+            conn_h = (
+                req_headers.get("connection", "")
+                + resp_headers.get("connection", "")
+            ).lower()
+            if "close" in conn_h:
+                break
+
+    async def _forward_headers(
         self,
+        reader: asyncio.StreamReader,
         writer: asyncio.StreamWriter,
-        method: str,
-        url: str,
-        headers: dict[str, str],
-        body: bytes,
-    ) -> None:
-        assert self._http_client is not None
-        try:
-            resp = await self._http_client.request(
-                method, url, headers=headers, content=body, timeout=120
-            )
-            resp_headers = {
-                "Content-Type": resp.headers.get("content-type", "application/json"),
-                "Content-Length": str(len(resp.content)),
-            }
-            for h in ("x-matrx-request-id", "x-matrx-latency-ms", "x-matrx-tokens-saved"):
-                if h in resp.headers:
-                    resp_headers[h] = resp.headers[h]
-            self._send_raw_response(writer, resp.status_code, resp_headers, resp.content)
-        except httpx.HTTPError as exc:
-            logger.warning("cursor_proxy: upstream error: %s", exc)
-            self._send_response(writer, 502, {"error": f"Upstream error: {exc}"})
-
-    async def _proxy_streaming(
+    ) -> tuple[dict[str, str], int, bool]:
+        """Read headers from *reader*, write to *writer*.
+
+        Returns (headers_dict, content_length, is_chunked).
+        """
+        headers: dict[str, str] = {}
+        content_length = -1
+        chunked = False
+        while True:
+            line = await reader.readline()
+            writer.write(line)
+            decoded = line.decode("utf-8", errors="replace").strip()
+            if not decoded:
+                break
+            if ":" in decoded:
+                k, _, v = decoded.partition(":")
+                k_lower = k.strip().lower()
+                v_stripped = v.strip()
+                headers[k_lower] = v_stripped
+                if k_lower == "content-length":
+                    content_length = int(v_stripped)
+                elif k_lower == "transfer-encoding" and "chunked" in v_stripped.lower():
+                    chunked = True
+        await writer.drain()
+        return headers, content_length, chunked
+
+    async def _forward_body(
         self,
+        reader: asyncio.StreamReader,
         writer: asyncio.StreamWriter,
-        method: str,
-        url: str,
-        headers: dict[str, str],
-        body: bytes,
-    ) -> None:
-        assert self._http_client is not None
-        try:
-            async with self._http_client.stream(
-                method, url, headers=headers, content=body, timeout=300
-            ) as resp:
-                resp_headers = {
-                    "Content-Type": resp.headers.get(
-                        "content-type", "text/event-stream"
-                    ),
-                    "Cache-Control": "no-cache",
-                    "Transfer-Encoding": "chunked",
-                }
-                for h in ("x-matrx-request-id", "x-matrx-latency-ms", "x-matrx-tokens-saved"):
-                    if h in resp.headers:
-                        resp_headers[h] = resp.headers[h]
-
-                header_block = f"HTTP/1.1 {resp.status_code} OK\r\n"
-                for k, v in resp_headers.items():
-                    header_block += f"{k}: {v}\r\n"
-                header_block += "\r\n"
-                writer.write(header_block.encode("utf-8"))
-                await writer.drain()
-
-                async for chunk in resp.aiter_bytes():
-                    chunk_header = f"{len(chunk):x}\r\n".encode("utf-8")
-                    writer.write(chunk_header + chunk + b"\r\n")
-                    await writer.drain()
-
-                writer.write(b"0\r\n\r\n")
-                await writer.drain()
-        except httpx.HTTPError as exc:
-            logger.warning("cursor_proxy: streaming error: %s", exc)
-            self._send_response(writer, 502, {"error": f"Upstream error: {exc}"})
+        content_length: int,
+        chunked: bool,
+    ) -> int:
+        """Forward request/response body.  Returns total bytes forwarded."""
+        if content_length > 0:
+            return await self._forward_fixed(reader, writer, content_length)
+        if chunked:
+            return await self._forward_chunked(reader, writer)
+        return 0
 
-    @staticmethod
-    def _send_response(
+    async def _forward_fixed(
+        self,
+        reader: asyncio.StreamReader,
         writer: asyncio.StreamWriter,
-        status: int,
-        body: dict[str, Any],
-    ) -> None:
-        content = json.dumps(body).encode("utf-8")
-        CursorProxyServer._send_raw_response(
-            writer,
-            status,
-            {"Content-Type": "application/json", "Content-Length": str(len(content))},
-            content,
-        )
+        length: int,
+    ) -> int:
+        total = 0
+        remaining = length
+        while remaining > 0:
+            chunk = await reader.read(min(remaining, 65536))
+            if not chunk:
+                break
+            writer.write(chunk)
+            await writer.drain()
+            total += len(chunk)
+            remaining -= len(chunk)
+        return total
 
-    @staticmethod
-    def _send_raw_response(
+    async def _forward_chunked(
+        self,
+        reader: asyncio.StreamReader,
         writer: asyncio.StreamWriter,
-        status: int,
-        headers: dict[str, str],
-        content: bytes,
+    ) -> int:
+        total = 0
+        while True:
+            size_line = await reader.readline()
+            if not size_line:
+                break
+            writer.write(size_line)
+            await writer.drain()
+            size_str = size_line.decode("utf-8", errors="replace").strip()
+            try:
+                chunk_size = int(size_str.split(";")[0], 16)
+            except ValueError:
+                break
+            if chunk_size == 0:
+                trailer = await reader.readline()
+                writer.write(trailer)
+                await writer.drain()
+                break
+            remaining = chunk_size
+            while remaining > 0:
+                data = await reader.read(min(remaining, 65536))
+                if not data:
+                    return total
+                writer.write(data)
+                await writer.drain()
+                total += len(data)
+                remaining -= len(data)
+            crlf = await reader.readline()
+            writer.write(crlf)
+            await writer.drain()
+        return total
+
+    # -----------------------------------------------------------------
+    # Raw bidirectional pipe (for opaque tunnels)
+    # -----------------------------------------------------------------
+
+    async def _pipe_bidirectional(
+        self,
+        r1: asyncio.StreamReader,
+        w1: asyncio.StreamWriter,
+        r2: asyncio.StreamReader,
+        w2: asyncio.StreamWriter,
     ) -> None:
-        reason = "OK" if 200 <= status < 300 else "Error"
-        header_block = f"HTTP/1.1 {status} {reason}\r\n"
-        for k, v in headers.items():
-            header_block += f"{k}: {v}\r\n"
-        header_block += "\r\n"
-        writer.write(header_block.encode("utf-8") + content)
-
-    def _pick_port(self) -> int:
-        if self.port:
-            return self.port
-        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-            s.bind(("127.0.0.1", 0))
-            return s.getsockname()[1]
-
-    async def _run(self) -> None:
-        self.port = self._pick_port()
-        self._http_client = httpx.AsyncClient(http2=False, follow_redirects=True)
-        self._server = await asyncio.start_server(
-            self._handle_request, self.host, self.port
-        )
-        logger.info("cursor_proxy: listening on %s:%s", self.host, self.port)
-        async with self._server:
-            await self._server.serve_forever()
-
-    async def _shutdown(self) -> None:
-        if self._server:
-            self._server.close()
-            await self._server.wait_closed()
-        if self._http_client:
-            await self._http_client.aclose()
-
-    def start_background(self) -> None:
-        """Start the proxy in a background daemon thread. Returns once listening."""
-        ready = threading.Event()
-
-        def _run_loop() -> None:
-            loop = asyncio.new_event_loop()
-            asyncio.set_event_loop(loop)
-            self._loop = loop
-
-            async def _start_and_signal() -> None:
-                self.port = self._pick_port()
-                self._http_client = httpx.AsyncClient(
-                    http2=False, follow_redirects=True
-                )
-                self._server = await asyncio.start_server(
-                    self._handle_request, self.host, self.port
-                )
-                ready.set()
-                async with self._server:
-                    await self._server.serve_forever()
-
+        async def _copy(src: asyncio.StreamReader, dst: asyncio.StreamWriter) -> None:
             try:
-                loop.run_until_complete(_start_and_signal())
-            except asyncio.CancelledError:
+                while True:
+                    data = await src.read(65536)
+                    if not data:
+                        break
+                    dst.write(data)
+                    await dst.drain()
+            except Exception:
                 pass
             finally:
-                loop.run_until_complete(self._shutdown())
-                loop.close()
-
-        thread = threading.Thread(target=_run_loop, daemon=True)
-        thread.start()
-        ready.wait(timeout=10)
-        if not ready.is_set():
-            raise RuntimeError("Cursor proxy failed to start within 10 seconds")
-
-    def stop(self) -> None:
-        """Stop the background proxy."""
-        if self._server and self._loop and self._loop.is_running():
-            self._loop.call_soon_threadsafe(self._server.close)
+                try:
+                    dst.close()
+                except Exception:
+                    pass
+
+        await asyncio.gather(_copy(r1, w2), _copy(r2, w1))
+
+    # -----------------------------------------------------------------
+    # Telemetry
+    # -----------------------------------------------------------------
+
+    async def _ship_telemetry(
+        self,
+        *,
+        hostname: str,
+        method: str,
+        path: str,
+        status_code: int,
+        req_body_size: int,
+        resp_body_size: int,
+        elapsed_ms: int,
+        content_type: str,
+        is_streaming: bool,
+    ) -> None:
+        if self._telemetry_client is None:
+            return
+
+        payload = {
+            "timestamp": time.time(),
+            "hostname": hostname,
+            "method": method,
+            "path": path,
+            "status_code": status_code,
+            "req_bytes": req_body_size,
+            "resp_bytes": resp_body_size,
+            "elapsed_ms": elapsed_ms,
+            "content_type": content_type,
+            "streaming": is_streaming,
+        }
+        url = f"{self.matrx_base_url}/v1/telemetry/cursor"
+        try:
+            await self._telemetry_client.post(
+                url,
+                json=payload,
+                headers={"X-Matrx-Key": self.matrx_key},
+            )
+        except Exception:
+            logger.debug("telemetry ship failed", exc_info=True)
+
+
+# ---------------------------------------------------------------------------
+# Entry-point for running the proxy as a standalone process (daemon use)
+# ---------------------------------------------------------------------------
+
+def run_proxy(
+    *,
+    matrx_key: str,
+    matrx_base_url: str,
+    host: str = PROXY_HOST,
+    port: int = DEFAULT_PORT,
+    pid_file: Path | None = None,
+) -> None:
+    """Run the MITM proxy (blocking).  Intended for daemon/service use."""
+    if pid_file:
+        pid_file.parent.mkdir(parents=True, exist_ok=True)
+        pid_file.write_text(str(os.getpid()), encoding="utf-8")
+
+    proxy = MITMProxy(
+        matrx_key=matrx_key,
+        matrx_base_url=matrx_base_url,
+        host=host,
+        port=port,
+    )
+
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        try:
+            loop.add_signal_handler(sig, lambda: loop.create_task(proxy.stop()))
+        except NotImplementedError:
+            pass
+
+    try:
+        loop.run_until_complete(proxy.serve_forever())
+    except (KeyboardInterrupt, SystemExit):
+        loop.run_until_complete(proxy.stop())
+    finally:
+        if pid_file and pid_file.exists():
+            pid_file.unlink(missing_ok=True)
+        loop.close()