relay-backend 0.0.1__py3-none-any.whl

relay_agent/__init__.py

@@ -0,0 +1,7 @@
+"""Relay's local API tester and native FastAPI integration."""
+
+from .integration import install_relay
+
+__version__ = "0.0.1"
+
+__all__ = ["install_relay"]

relay_agent/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

relay_agent/app.py

@@ -0,0 +1,216 @@
+import json
+import secrets
+import ipaddress
+import posixpath
+import asyncio
+from html import escape
+from urllib.parse import unquote
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Literal
+
+import httpx
+from fastapi import APIRouter, FastAPI, HTTPException, Request
+from fastapi.responses import JSONResponse, HTMLResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel, Field
+
+from .executor import send
+from .openapi import SpecError, normalize
+from .security import MAX_REQUEST, MAX_RESPONSE, Settings, safe_headers, validate_path
+from .workspace import Workspace
+from .git_source import GitSource
+
+
+class ExecuteRequest(BaseModel):
+    method: Literal["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]
+    path: str = Field(max_length=8192)
+    headers: dict[str, str] = Field(default_factory=dict)
+    query: dict[str, str] = Field(default_factory=dict)
+    body_mode: Literal["none", "json", "text", "form"] = "none"
+    body: str = ""
+
+
+class EndpointUpdate(BaseModel):
+    endpoint_id: str = Field(max_length=8192)
+    fingerprint: str = Field(min_length=64, max_length=64)
+    progress: Literal["not_started", "in_progress", "done", "needs_fixing"] | None = None
+    note: str | None = Field(default=None, max_length=4000)
+
+
+def create_app(settings: Settings | None = None, transport=None, static_dir: Path | None = None, db_path: str | Path = ":memory:", project: Path | None = None, native_host: FastAPI | None = None):
+    settings = settings or Settings()
+    token = secrets.token_urlsafe(32)
+
+    @asynccontextmanager
+    async def lifespan(app):
+        workspace = Workspace(db_path, project=project)
+        app.state.workspace = workspace
+        app.state.git_source = GitSource(workspace.shared.root if workspace.shared else None)
+        app.state.snapshot = None
+        app.state.raw_spec = None
+        try:
+            async with httpx.AsyncClient(timeout=20, follow_redirects=False, trust_env=False, transport=transport) as client:
+                app.state.client = client
+                yield
+        finally:
+            workspace.close()
+
+    app = FastAPI(title="Relay Local Companion", docs_url=None, redoc_url=None, openapi_url=None, lifespan=lifespan)
+    app.state.snapshot = None
+    app.state.raw_spec = None
+
+    @app.middleware("http")
+    async def guard(request: Request, call_next):
+        expected_origin = f"{request.url.scheme}://{request.url.netloc}" if native_host else settings.origin
+        if native_host:
+            def local(host):
+                try:
+                    return ipaddress.ip_address(host).is_loopback
+                except ValueError:
+                    return host == "localhost"
+            if not request.client or not local(request.client.host) or not local(request.url.hostname or ""):
+                return JSONResponse({"detail": "Relay is available only on the developer's local machine."}, 403)
+        elif request.headers.get("host") != f"127.0.0.1:{settings.port}":
+            return JSONResponse({"detail": f"Open Relay at {settings.origin}; this host is not allowed."}, 403)
+        origin = request.headers.get("origin")
+        if origin and origin != expected_origin:
+            return JSONResponse({"detail": "Untrusted browser origin."}, 403)
+        if request.headers.get("sec-fetch-site") not in {None, "none", "same-origin"}:
+            return JSONResponse({"detail": "Cross-origin access to the local runner is forbidden."}, 403)
+        if request.method not in {"GET", "HEAD"}:
+            if origin != expected_origin or not secrets.compare_digest(request.headers.get("x-relay-csrf", "").encode(), token.encode()):
+                return JSONResponse({"detail": "Local session expired or CSRF check failed. Reload Relay."}, 403)
+            # Read the stream with a hard cap before Pydantic allocates the request body.
+            body = bytearray()
+            async for chunk in request.stream():
+                body.extend(chunk)
+                if len(body) > MAX_REQUEST:
+                    return JSONResponse({"detail": "Request exceeds the 1 MiB limit."}, 413)
+            request._body = bytes(body)
+        response = await call_next(request)
+        response.headers.update({"Cache-Control": "no-store", "X-Content-Type-Options": "nosniff",
+                                 "Referrer-Policy": "no-referrer", "X-Frame-Options": "DENY",
+                                 "Content-Security-Policy": "default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self' data:; frame-ancestors 'none'; base-uri 'self'"})
+        return response
+
+    def target_base(request: Request):
+        if not native_host:
+            return settings.base_url.rstrip("/")
+        root = request.scope.get("root_path", "").removesuffix("/relay")
+        return f"{request.url.scheme}://{request.url.netloc}{root}"
+
+    @app.get("/__relay/health")
+    def health(request: Request):
+        return {"status": "ok", "mode": "local", "version": "0.0.1", "csrf_token": token,
+                "base_url": target_base(request), "spec_url": target_base(request) + (native_host.openapi_url or "") if native_host else settings.target(settings.spec_path)}
+
+    @app.post("/__relay/sources/inspect")
+    async def inspect():
+        try:
+            if native_host:
+                raw = native_host.openapi()
+                if len(json.dumps(raw).encode()) > MAX_RESPONSE:
+                    raise HTTPException(413, "OpenAPI document exceeds the 2 MiB limit.")
+            else:
+                result = await send(app.state.client, "GET", settings.target(settings.spec_path), limit=MAX_RESPONSE)
+                if result["status"] != 200:
+                    raise HTTPException(502, f"OpenAPI returned HTTP {result['status']}. Check the configured spec path; redirects are not followed.")
+                if result["truncated"]:
+                    raise HTTPException(413, "OpenAPI document exceeds the 2 MiB limit.")
+                raw = json.loads(result["body"])
+            snapshot = normalize(raw)
+        except (ValueError, SpecError, RecursionError, TypeError, AttributeError) as exc:
+            raise HTTPException(422, f"Could not import OpenAPI: {exc}. Last good import is preserved.")
+        app.state.workspace.sync(snapshot)
+        if native_host:
+            app.state.workspace.sources = await asyncio.to_thread(app.state.git_source.collect, native_host)
+        app.state.snapshot, app.state.raw_spec = snapshot, raw
+        return snapshot
+
+    @app.get("/__relay/workspace")
+    def read_workspace():
+        return app.state.workspace.read()
+
+    @app.post("/__relay/endpoints/update")
+    def update_endpoint(payload: EndpointUpdate):
+        app.state.workspace.update(payload.endpoint_id, payload.fingerprint, payload.progress, payload.note)
+        return app.state.workspace.read()
+
+    @app.get("/__relay/sources/current")
+    def current():
+        return {"snapshot": app.state.snapshot, "raw_spec": app.state.raw_spec}
+
+    @app.post("/__relay/execute")
+    async def execute(payload: ExecuteRequest, request: Request):
+        validate_path(payload.path)
+        decoded_path = posixpath.normpath(unquote(payload.path))
+        if native_host and (decoded_path == "/relay" or decoded_path.startswith("/relay/")):
+            raise HTTPException(400, "Relay's own routes cannot be executed.")
+        url = target_base(request) + payload.path
+        root = request.scope.get("root_path", "").removesuffix("/relay") if native_host else ""
+        if native_host:
+            resolved_path = posixpath.normpath(unquote(httpx.URL(url).path))
+            if root and not resolved_path.startswith(root + "/"):
+                raise HTTPException(400, "Request path escapes the application's mount.")
+            route_path = resolved_path.removeprefix(root)
+            if route_path == "/relay" or route_path.startswith("/relay/"):
+                raise HTTPException(400, "Relay's own routes cannot be executed.")
+        headers = safe_headers(dict(payload.headers))
+        content = None
+        if payload.body_mode == "json":
+            try:
+                json.loads(payload.body)
+            except (ValueError, RecursionError):
+                raise HTTPException(400, "Invalid JSON body. Fix the JSON before executing.")
+            content = payload.body.encode()
+            headers = {k: v for k, v in headers.items() if k.lower() != "content-type"}
+            headers["Content-Type"] = "application/json"
+        elif payload.body_mode != "none":
+            content = payload.body.encode()
+            if not any(k.lower() == "content-type" for k in headers):
+                headers["Content-Type"] = "application/x-www-form-urlencoded" if payload.body_mode == "form" else "text/plain"
+        if native_host:
+            async def bounded_host(scope, receive, send_message):
+                # HTTPX's ASGI transport buffers response chunks. Cap what it
+                # retains, while allowing the application to finish normally.
+                retained = 0
+                scope["state"] = dict(request.scope.get("state", {}))
+                async def bounded_send(message):
+                    nonlocal retained
+                    if message["type"] == "http.response.body":
+                        chunk = message.get("body", b"")[:max(0, MAX_RESPONSE + 1 - retained)]
+                        retained += len(chunk)
+                        message = {**message, "body": chunk}
+                    await send_message(message)
+                await native_host(scope, receive, bounded_send)
+            native_transport = httpx.ASGITransport(app=bounded_host, root_path=root, raise_app_exceptions=False,
+                                                 client=(request.client.host, request.client.port))
+            # Never reuse cookies from a previous response as implicit auth.
+            async with httpx.AsyncClient(transport=native_transport, follow_redirects=False, trust_env=False) as client:
+                return await send(client, payload.method, url, headers=headers, query=payload.query, content=content)
+        return await send(app.state.client, payload.method, url, headers=headers, query=payload.query, content=content)
+
+    bundled = Path(__file__).resolve().parent / "static"
+    static_dir = static_dir or (bundled if bundled.is_dir() else Path(__file__).resolve().parents[2] / "web" / "dist")
+    if static_dir.is_dir():
+        # Preserve CLI API URLs while the browser uses namespaced URLs.
+        if not native_host:
+            aliases = APIRouter()
+            aliases.routes = list(app.router.routes)
+            app.include_router(aliases, prefix="/relay", include_in_schema=False)
+        @app.get("/" if native_host else "/relay", include_in_schema=False)
+        @app.get("/index.html" if native_host else "/relay/", include_in_schema=False)
+        def relay_ui(request: Request):
+            base = request.scope.get("root_path", "") if native_host else request.scope.get("root_path", "") + "/relay"
+            html = (static_dir / "index.html").read_text(encoding="utf-8")
+            html = html.replace("<head>", f'<head><base href="{escape(base + "/", quote=True)}">', 1)
+            return HTMLResponse(html)
+        if not native_host:
+            app.mount("/relay", StaticFiles(directory=static_dir, html=True), name="relay-web")
+        app.mount("/", StaticFiles(directory=static_dir, html=True), name="web")
+    else:
+        @app.get("/")
+        def missing_ui():
+            return JSONResponse({"detail": "Relay's bundled UI is missing. Reinstall the Relay package."}, 503)
+    return app

relay_agent/cli.py

@@ -0,0 +1,47 @@
+import argparse
+import hashlib
+import sys
+from pathlib import Path
+
+import uvicorn
+
+from .app import create_app
+from .security import Settings
+
+
+def main():
+    if len(sys.argv) > 1 and sys.argv[1] in {"open", "associate"}:
+        from .files import associate_windows, open_report
+        action = sys.argv[1]
+        file_parser = argparse.ArgumentParser(description="Open Relay reports or enable Windows double-click support.")
+        if action == "open":
+            file_parser.add_argument("file", type=Path)
+        file_args = file_parser.parse_args(sys.argv[2:])
+        try:
+            if action == "open":
+                open_report(file_args.file)
+            else:
+                associate_windows()
+                print("Relay .relay reports now open in your default browser. Existing Windows user choices remain unchanged.")
+        except (OSError, UnicodeError, ValueError, RuntimeError) as error:
+            file_parser.error(str(error))
+        return
+    parser = argparse.ArgumentParser(description="Relay local API explorer. Targets are approved explicitly at startup.")
+    parser.add_argument("--target", default="http://127.0.0.1:8000")
+    parser.add_argument("--spec-path", default="/openapi.json")
+    parser.add_argument("--port", type=int, default=4477)
+    parser.add_argument("--static-dir", type=Path)
+    parser.add_argument("--data-dir", type=Path, default=Path.home() / ".relay")
+    parser.add_argument("--project", type=Path, help="Git repository for shared .relay/status.json metadata")
+    args = parser.parse_args()
+    try:
+        settings = Settings(args.target, args.spec_path, args.port)
+    except Exception as exc:
+        parser.error(str(exc))
+    workspace_id = hashlib.sha256((str(args.project.resolve()) if args.project else settings.base_url.rstrip("/")).encode()).hexdigest()[:16]
+    db_path = args.data_dir / workspace_id / "workspace.sqlite3"
+    try:
+        app = create_app(settings, static_dir=args.static_dir, db_path=db_path, project=args.project)
+    except ValueError as exc:
+        parser.error(str(exc))
+    uvicorn.run(app, host="127.0.0.1", port=args.port, access_log=False)

relay_agent/executor.py

@@ -0,0 +1,32 @@
+import asyncio
+import time
+
+import httpx
+from fastapi import HTTPException
+
+from .security import MAX_RESPONSE
+
+
+async def send(client: httpx.AsyncClient, method: str, url: str, *, headers=None, query=None,
+               content=None, limit=MAX_RESPONSE):
+    started = time.perf_counter()
+    try:
+        async with asyncio.timeout(20):
+            async with client.stream(method, url, headers=headers, params=query, content=content) as response:
+                data = bytearray()
+                truncated = False
+                async for chunk in response.aiter_bytes(chunk_size=65536):
+                    remaining = limit - len(data)
+                    data.extend(chunk[:remaining])
+                    if len(chunk) > remaining:
+                        truncated = True
+                        break
+                return {"status": response.status_code, "reason": response.reason_phrase,
+                        "headers": dict(response.headers), "body": data.decode(response.encoding or "utf-8", errors="replace"),
+                        "content_type": response.headers.get("content-type", ""), "bytes": len(data),
+                        "truncated": truncated, "duration_ms": round((time.perf_counter() - started) * 1000, 1),
+                        "url": str(response.url), "method": method}
+    except (httpx.TimeoutException, TimeoutError):
+        raise HTTPException(504, "Request timed out after 20 seconds. Check the backend and try again.")
+    except httpx.RequestError:
+        raise HTTPException(502, "Could not connect to the configured API. Start your backend and check its address and port.")

relay_agent/files.py

@@ -0,0 +1,88 @@
+"""Open portable Relay reports and register their Windows file association."""
+import argparse
+import hashlib
+import sys
+import webbrowser
+from pathlib import Path
+
+REPORT_MARKER = '<meta name="relay-format" content="relay.endpoint.report.v1">'
+PROG_ID = "Relay.EndpointReport"
+
+
+def prepare_report(path: Path, cache_dir: Path | None = None) -> Path:
+    path = path.expanduser().resolve(strict=True)
+    if path.suffix.lower() != ".relay":
+        raise ValueError("Choose a .relay endpoint report.")
+    if path.stat().st_size > 32 * 1024 * 1024:
+        raise ValueError("Relay report exceeds the 32 MiB limit.")
+    data = path.read_bytes()
+    content = data.decode("utf-8-sig")
+    if REPORT_MARKER not in content or not content.lstrip().lower().startswith("<!doctype html>"):
+        raise ValueError("This is not a supported Relay browser report.")
+    # A .html copy gives every browser the correct local-file content type.
+    # Keep the original report intact; no backend or HTTP server is required.
+    root = cache_dir or Path.home() / ".relay" / "reports"
+    root.mkdir(parents=True, exist_ok=True)
+    destination = root / (hashlib.sha256(data).hexdigest() + ".html")
+    destination.write_bytes(data)
+    return destination
+
+
+def open_report(path: Path) -> Path:
+    destination = prepare_report(path)
+    if not webbrowser.open(destination.as_uri()):
+        raise RuntimeError(f"Could not open your browser. Open {destination} manually.")
+    return destination
+
+
+def associate_windows() -> str:
+    if sys.platform != "win32":
+        raise ValueError("Automatic association currently supports Windows. Use relay open <file.relay> on this platform.")
+    import ctypes
+    import subprocess
+    import winreg
+
+    extension = r"Software\Classes\.relay"
+    # Do not replace another application's association.
+    for hive, key_path in ((winreg.HKEY_CURRENT_USER, extension), (winreg.HKEY_CLASSES_ROOT, ".relay")):
+        try:
+            with winreg.OpenKey(hive, key_path) as key:
+                existing = winreg.QueryValue(key, None)
+                if existing and existing != PROG_ID:
+                    raise ValueError(".relay already belongs to another application. Choose Relay explicitly in Windows Open with settings.")
+        except FileNotFoundError:
+            pass
+    python = Path(sys.executable)
+    pythonw = python.with_name("pythonw.exe")
+    executable = pythonw if pythonw.is_file() else python
+    command = subprocess.list2cmdline([str(executable), "-m", "relay_agent.files"]) + ' "%1"'
+    values = {
+        extension: PROG_ID,
+        rf"Software\Classes\{PROG_ID}": "Relay endpoint report",
+        rf"Software\Classes\{PROG_ID}\shell\open\command": command,
+    }
+    for key_path, value in values.items():
+        with winreg.CreateKey(winreg.HKEY_CURRENT_USER, key_path) as key:
+            winreg.SetValueEx(key, "", 0, winreg.REG_SZ, value)
+    with winreg.CreateKey(winreg.HKEY_CURRENT_USER, extension) as key:
+        winreg.SetValueEx(key, "Content Type", 0, winreg.REG_SZ, "text/html")
+    ctypes.windll.shell32.SHChangeNotify(0x08000000, 0, None, None)
+    return command
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Open a Relay endpoint report in your default browser.")
+    parser.add_argument("file", type=Path)
+    args = parser.parse_args()
+    try:
+        open_report(args.file)
+    except (OSError, UnicodeError, ValueError, RuntimeError) as error:
+        if sys.platform == "win32" and sys.executable.lower().endswith("pythonw.exe"):
+            import ctypes
+            ctypes.windll.user32.MessageBoxW(None, str(error), "Relay report", 0x10)
+        else:
+            parser.error(str(error))
+
+
+if __name__ == "__main__":
+    main()

relay_agent/git_source.py

@@ -0,0 +1,128 @@
+"""Read-only source attribution for native FastAPI endpoints.
+
+Creation is inferred from the oldest available history of the handler's
+definition line. It is not ownership or verified identity.
+"""
+import ast
+import inspect
+import subprocess
+from pathlib import Path
+
+from fastapi.routing import APIRoute
+
+
+def api_routes(routes, prefix=""):
+    """Support flattened routes and FastAPI's newer included-router branches."""
+    for route in routes:
+        if isinstance(route, APIRoute):
+            if route.include_in_schema:
+                yield route, prefix + route.path
+        else:
+            router = getattr(route, "original_router", None)
+            context = getattr(route, "include_context", None)
+            if router is not None and context is not None and context.include_in_schema:
+                yield from api_routes(router.routes, prefix + context.prefix)
+
+
+class GitSource:
+    def __init__(self, root: Path | None):
+        self.root = root
+        self.cache = {}
+        self.files = {}
+
+    def git(self, *args):
+        result = subprocess.run(["git", "-C", str(self.root), "-c", "core.quotepath=false", *args],
+                                capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=5)
+        if result.returncode:
+            raise ValueError("Git history unavailable")
+        return result.stdout
+
+    def collect(self, app):
+        try:
+            head = self.git("rev-parse", "HEAD").strip() if self.root else None
+        except (ValueError, OSError, subprocess.TimeoutExpired):
+            head = None
+        sources = {}
+        for route, route_path in api_routes(app.routes):
+            try:
+                handler = inspect.unwrap(route.endpoint)
+                file = Path(inspect.getsourcefile(handler)).resolve()
+                lines, start = inspect.getsourcelines(handler)
+                # inspect includes route decorators; the definition itself is
+                # the stable anchor for tracing this handler back through Git.
+                import textwrap
+                tree = ast.parse(textwrap.dedent("".join(lines)))
+                node = next(n for n in tree.body if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef)))
+                definition = start + node.lineno - 1
+                end = start + len(lines) - 1
+                relative = file.relative_to(self.root).as_posix() if self.root else file.name
+                key = (head, relative, start, definition, end, file.stat().st_mtime_ns)
+                if key not in self.cache:
+                    self.cache[key] = self.history(relative, start, definition, end, head, handler.__name__)
+                source = self.cache[key]
+            except (ValueError, TypeError, OSError, StopIteration, SyntaxError):
+                source = {"state": "unavailable"}
+            for method in route.methods:
+                sources[f"{method} {route_path}"] = source
+        # Bound the cache across auto-sync and edits.
+        if len(self.cache) > 1024:
+            self.cache.clear()
+            self.files.clear()
+        return sources
+
+    def history(self, file, start, definition, end, head, name):
+        source = {"file": file, "line": definition, "state": "unavailable"}
+        if not head:
+            if self.root:
+                source["state"] = "uncommitted"
+            return source
+        try:
+            file_key = (head, file)
+            if file_key not in self.files:
+                try:
+                    self.files[file_key] = ast.parse(self.git("show", f"{head}:{file}"))
+                except ValueError:
+                    source["state"] = "uncommitted"
+                    return source
+            definitions = [n for n in ast.walk(self.files[file_key])
+                           if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef)) and n.name == name]
+            if definitions:
+                node = min(definitions, key=lambda n: abs(n.lineno - definition))
+                committed_start = min([node.lineno, *(d.lineno for d in node.decorator_list)])
+                history = self.git("log", "--no-patch", "--format=%H%x00%an%x00%ae%x00%aI",
+                                   "-L", f"{committed_start},{node.end_lineno}:{file}", head)
+                entries = [line.split("\0") for line in history.splitlines() if line.count("\0") == 3]
+                if entries:
+                    commit, author, email, date = entries[0]
+                    source.update(last_changed_by={"name": author, "email": email}, commit=commit, changed_at=date)
+            output = self.git("blame", "--line-porcelain", "-L", f"{start},{end}", "--", file)
+            records = []
+            record = {}
+            for line in output.splitlines():
+                if not record:
+                    sha, original, final, *_ = line.split()
+                    record = {"commit": sha, "original": int(original), "final": int(final)}
+                elif line.startswith("\t"):
+                    records.append(record)
+                    record = {}
+                else:
+                    name, _, value = line.partition(" ")
+                    record[name] = value
+            committed = [r for r in records if set(r["commit"]) != {"0"}]
+            source["state"] = "uncommitted" if len(committed) != len(records) else "tracked"
+            anchor = next((r for r in committed if r["final"] == definition), None)
+            if anchor:
+                old_file = anchor["filename"]
+                if old_file.startswith('"'):
+                    old_file = ast.literal_eval(old_file)
+                history = self.git("log", "--no-patch", "--format=%H%x00%an%x00%ae%x00%aI",
+                                   "-L", f'{anchor["original"]},{anchor["original"]}:{old_file}', anchor["commit"])
+                entries = [line.split("\0") for line in history.splitlines() if line.count("\0") == 3]
+                if entries:
+                    commit, name, email, date = entries[-1]
+                    source.update(created_by={"name": name, "email": email}, created_commit=commit, created_at=date)
+        except (ValueError, KeyError, OSError, subprocess.TimeoutExpired, SyntaxError):
+            # Missing/untracked files, shallow history, and failed Git commands
+            # never prevent API discovery or testing.
+            pass
+        return source

relay_agent/git_status.py

@@ -0,0 +1,83 @@
+"""Git-trackable status metadata. No Git commits or network operations are automatic."""
+import json
+import os
+import subprocess
+import tempfile
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+
+from fastapi import HTTPException
+
+PROGRESS = {"not_started", "in_progress", "done", "needs_fixing"}
+
+
+class GitStatus:
+    def __init__(self, project: Path):
+        self.root = Path(self._git(project, "rev-parse", "--show-toplevel")).resolve()
+        self.path = self.root / ".relay" / "status.json"
+
+    @staticmethod
+    def _git(project, *args):
+        result = subprocess.run(["git", "-C", str(project), *args], capture_output=True, text=True, timeout=5)
+        if result.returncode:
+            raise ValueError("Relay --project requires an existing Git repository.")
+        return result.stdout.strip()
+
+    def read(self):
+        if not self.path.exists():
+            return {}
+        try:
+            if self.path.stat().st_size > 2 * 1024 * 1024:
+                raise ValueError("Status file is too large")
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+            if data.get("version") != 1 or not isinstance(data.get("endpoints"), dict):
+                raise ValueError("Unknown status format")
+            for key, row in data["endpoints"].items():
+                if not isinstance(key, str) or not isinstance(row, dict) or row.get("progress") not in PROGRESS:
+                    raise ValueError("Invalid endpoint status")
+                if not isinstance(row.get("fingerprint"), str) or len(row["fingerprint"]) != 64:
+                    raise ValueError("Invalid contract fingerprint")
+                author = row.get("updated_by")
+                if not isinstance(author, dict) or not all(isinstance(author.get(k), str) for k in ("name", "email")):
+                    raise ValueError("Invalid author")
+                if not isinstance(row.get("updated_at"), str):
+                    raise ValueError("Invalid timestamp")
+            return data["endpoints"]
+        except (ValueError, OSError, AttributeError, TypeError) as exc:
+            raise HTTPException(409, "Cannot read .relay/status.json. Resolve Git conflicts or fix the file before changing status.") from exc
+
+    @contextmanager
+    def _lock(self):
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        lock = self.path.with_suffix(".lock")
+        try:
+            fd = os.open(lock, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        except FileExistsError as exc:
+            raise HTTPException(409, "Another Relay process is updating statuses. Retry shortly; remove a stale .relay/status.lock after stopping Relay.") from exc
+        try:
+            os.close(fd)
+            yield
+        finally:
+            lock.unlink(missing_ok=True)
+
+    def update(self, endpoint_id, fingerprint, progress):
+        try:
+            name = self._git(self.root, "config", "user.name")
+            email = self._git(self.root, "config", "user.email")
+            if not name or not email:
+                raise ValueError("Missing identity")
+        except ValueError as exc:
+            raise HTTPException(409, "Configure Git user.name and user.email before changing a shared status.") from exc
+        with self._lock():
+            rows = self.read()
+            rows[endpoint_id] = {"fingerprint": fingerprint, "progress": progress,
+                "updated_by": {"name": name, "email": email}, "updated_at": datetime.now(timezone.utc).isoformat()}
+            fd, temporary = tempfile.mkstemp(prefix="status-", suffix=".tmp", dir=self.path.parent)
+            try:
+                with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as stream:
+                    json.dump({"version": 1, "endpoints": dict(sorted(rows.items()))}, stream, indent=2, ensure_ascii=False)
+                    stream.write("\n")
+                os.replace(temporary, self.path)
+            finally:
+                Path(temporary).unlink(missing_ok=True)

relay_agent/integration.py

@@ -0,0 +1,48 @@
+"""Opt-in, same-process FastAPI integration."""
+import hashlib
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI
+from .app import create_app
+
+
+def install_relay(app: FastAPI, *, enabled: bool = True, project: Path | None = None,
+                  data_dir: Path | None = None, db_path: str | Path | None = None,
+                  static_dir: Path | None = None) -> FastAPI | None:
+    """Mount the bundled tester at /relay. Enable only in development.
+
+    No target URL, subprocess, or extra port is required. The parent lifespan
+    runs normally; Relay owns only its client/workspace resources.
+    """
+    if not enabled:
+        return None
+    if getattr(app.state, "relay", None) is not None:
+        raise ValueError("Relay is already installed on this application.")
+    for route in app.routes:
+        path = getattr(route, "path", "")
+        if path == "/relay" or path.startswith("/relay/"):
+            raise ValueError("The /relay namespace is already in use.")
+    if project is None:
+        project = next((p for p in (Path.cwd(), *Path.cwd().parents)
+                        if (p / ".git").exists()), None)
+    if db_path is None:
+        identity = f"{Path(project or Path.cwd()).resolve()}:{app.title}"
+        workspace_id = hashlib.sha256(identity.encode()).hexdigest()[:16]
+        db_path = Path(data_dir or Path.home() / ".relay") / workspace_id / "workspace.sqlite3"
+    relay = create_app(native_host=app, static_dir=static_dir, db_path=db_path, project=project)
+    previous = app.router.lifespan_context
+
+    @asynccontextmanager
+    async def lifespan(application):
+        async with previous(application) as state:
+            # Mounted apps do not receive lifespan automatically.
+            async with relay.router.lifespan_context(relay):
+                yield state
+
+    app.router.lifespan_context = lifespan
+    app.mount("/relay", relay, name="relay")
+    # Reserve this namespace even when the host has a catch-all route.
+    app.router.routes.insert(0, app.router.routes.pop())
+    app.state.relay = relay
+    return relay