codexa 0.4.0__py3-none-any.whl

semantic_code_intelligence/web/api.py

@@ -0,0 +1,289 @@
+"""REST API server — developer-friendly HTTP endpoints wrapping CodexA services.
+
+Uses only the Python standard library (``http.server``).  All endpoints
+return JSON and can be selectively enabled/disabled.
+
+Endpoints
+---------
+GET  /health           → system & index status
+GET  /api/search       → semantic search (``?q=...&top_k=5``)
+POST /api/ask          → natural-language code Q\u0026A
+POST /api/analyze      → code explanation / validation
+GET  /api/symbols      → list indexed symbols (``?file=...&kind=...``)
+GET  /api/deps         → dependency map (``?file=...``)
+GET  /api/callgraph    → call graph (``?symbol=...``)
+GET  /api/summary      → repository summary
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.parse
+from http.server import BaseHTTPRequestHandler
+from pathlib import Path
+from typing import Any
+
+from semantic_code_intelligence.bridge.context_provider import ContextProvider
+from semantic_code_intelligence.utils.logging import get_logger
+
+logger = get_logger("web.api")
+
+
+class APIHandler(BaseHTTPRequestHandler):
+    """JSON REST API handler for CodexA developer endpoints.
+
+    Class-level attributes are injected before the server starts:
+        project_root  — the root path of the project being served
+        provider      — a ``ContextProvider`` instance
+    """
+
+    project_root: Path
+    provider: ContextProvider
+
+    # Use our own logger instead of stderr.
+    def log_message(self, fmt: str, *args: Any) -> None:  # noqa: D102
+        logger.debug(fmt, *args)
+
+    # ------------------------------------------------------------------
+    # Routing
+    # ------------------------------------------------------------------
+
+    def do_GET(self) -> None:  # noqa: N802
+        parsed = urllib.parse.urlparse(self.path)
+        path = parsed.path.rstrip("/")
+        qs = urllib.parse.parse_qs(parsed.query)
+
+        routes: dict[str, Any] = {
+            "/health": self._handle_health,
+            "/api/search": self._handle_search,
+            "/api/symbols": self._handle_symbols,
+            "/api/deps": self._handle_deps,
+            "/api/callgraph": self._handle_callgraph,
+            "/api/summary": self._handle_summary,
+        }
+
+        handler = routes.get(path)
+        if handler:
+            handler(qs)
+        else:
+            self._json(404, {"error": "Not found", "path": self.path})
+
+    def do_POST(self) -> None:  # noqa: N802
+        parsed = urllib.parse.urlparse(self.path)
+        path = parsed.path.rstrip("/")
+
+        body = self._read_body()
+        if body is None:
+            return  # error already sent
+
+        routes: dict[str, Any] = {
+            "/api/ask": self._handle_ask,
+            "/api/analyze": self._handle_analyze,
+        }
+
+        handler = routes.get(path)
+        if handler:
+            handler(body)
+        else:
+            self._json(404, {"error": "Not found", "path": self.path})
+
+    def do_OPTIONS(self) -> None:  # noqa: N802
+        self.send_response(204)
+        self._cors_headers()
+        self.end_headers()
+
+    # ------------------------------------------------------------------
+    # GET handlers
+    # ------------------------------------------------------------------
+
+    def _handle_health(self, qs: dict[str, list[str]]) -> None:
+        """GET /health — project status and basic info."""
+        codex_dir = self.project_root / ".codexa"
+        self._json(200, {
+            "status": "ok",
+            "project_root": str(self.project_root),
+            "indexed": (codex_dir / "index").exists() if codex_dir.exists() else False,
+            "config_found": (codex_dir / "config.json").exists() if codex_dir.exists() else False,
+        })
+
+    def _handle_search(self, qs: dict[str, list[str]]) -> None:
+        """GET /api/search?q=...&top_k=5&threshold=0.2"""
+        query = _qs_first(qs, "q", "")
+        if not query:
+            self._json(400, {"error": "Missing required parameter: q"})
+            return
+
+        top_k = int(_qs_first(qs, "top_k", "5"))
+        threshold = float(_qs_first(qs, "threshold", "0.2"))
+
+        start = time.monotonic()
+        data = self.provider.context_for_query(
+            query, top_k=top_k, threshold=threshold,
+        )
+        elapsed = (time.monotonic() - start) * 1000
+        data["elapsed_ms"] = round(elapsed, 2)
+        self._json(200, data)
+
+    def _handle_symbols(self, qs: dict[str, list[str]]) -> None:
+        """GET /api/symbols?file=...&kind=..."""
+        builder = self.provider._ensure_indexed()
+        file_filter = _qs_first(qs, "file", "")
+        kind_filter = _qs_first(qs, "kind", "")
+
+        symbols = builder.get_all_symbols()
+        if file_filter:
+            symbols = [s for s in symbols if file_filter in s.file_path]
+        if kind_filter:
+            symbols = [s for s in symbols if s.kind == kind_filter]
+
+        self._json(200, {
+            "count": len(symbols),
+            "symbols": [s.to_dict() for s in symbols[:200]],  # cap at 200
+        })
+
+    def _handle_deps(self, qs: dict[str, list[str]]) -> None:
+        """GET /api/deps?file=..."""
+        file_path = _qs_first(qs, "file", "")
+        data = self.provider.get_dependencies(file_path=file_path)
+        self._json(200, data)
+
+    def _handle_callgraph(self, qs: dict[str, list[str]]) -> None:
+        """GET /api/callgraph?symbol=..."""
+        symbol = _qs_first(qs, "symbol", "")
+        data = self.provider.get_call_graph(symbol_name=symbol)
+        self._json(200, data)
+
+    def _handle_summary(self, qs: dict[str, list[str]]) -> None:
+        """GET /api/summary"""
+        data = self.provider.context_for_repo()
+        self._json(200, data)
+
+    # ------------------------------------------------------------------
+    # POST handlers
+    # ------------------------------------------------------------------
+
+    def _handle_ask(self, body: dict[str, Any]) -> None:
+        """POST /api/ask — natural-language question about the codebase.
+
+        Request body: ``{"question": "...", "top_k": 5}``
+        """
+        question = body.get("question", "")
+        if not question:
+            self._json(400, {"error": "Missing required field: question"})
+            return
+
+        top_k = body.get("top_k", 5)
+        start = time.monotonic()
+        # Try LLM-powered answer via ReasoningEngine
+        try:
+            from semantic_code_intelligence.config.settings import load_config, LLMConfig
+            from semantic_code_intelligence.llm.reasoning import ReasoningEngine
+
+            config = load_config(self.provider._root)
+            llm_cfg: LLMConfig = config.llm
+            provider = None
+            if llm_cfg.provider == "openai":
+                from semantic_code_intelligence.llm.openai_provider import OpenAIProvider
+                provider = OpenAIProvider(
+                    api_key=llm_cfg.api_key, model=llm_cfg.model,
+                    base_url=llm_cfg.base_url or None,
+                    temperature=llm_cfg.temperature, max_tokens=llm_cfg.max_tokens,
+                )
+            elif llm_cfg.provider == "ollama":
+                from semantic_code_intelligence.llm.ollama_provider import OllamaProvider
+                provider = OllamaProvider(
+                    model=llm_cfg.model,
+                    base_url=llm_cfg.base_url or "http://localhost:11434",
+                    temperature=llm_cfg.temperature, max_tokens=llm_cfg.max_tokens,
+                )
+            if provider is not None:
+                engine = ReasoningEngine(provider, self.provider._root)
+                result = engine.ask(question, top_k=top_k)
+                elapsed = (time.monotonic() - start) * 1000
+                self._json(200, {
+                    "question": result.question,
+                    "answer": result.answer,
+                    "snippets": result.context_snippets,
+                    "elapsed_ms": round(elapsed, 2),
+                })
+                return
+        except Exception:
+            logger.debug("LLM ask failed, falling back to context search", exc_info=True)
+
+        # Fallback: return snippets with a synthesized answer
+        data = self.provider.context_for_query(question, top_k=top_k)
+        snippets = data.get("snippets", [])
+        summary_parts = []
+        for s in snippets[:3]:
+            fp = s.get("file_path", "")
+            sl = s.get("start_line", "")
+            summary_parts.append(f"- {fp} (line {sl})")
+        answer = f"Based on {len(snippets)} relevant code snippets:\n" + "\n".join(summary_parts)
+        if not snippets:
+            answer = "No relevant code found for this question. Try rephrasing or indexing more files."
+        data["answer"] = answer
+        elapsed = (time.monotonic() - start) * 1000
+        data["elapsed_ms"] = round(elapsed, 2)
+        self._json(200, data)
+
+    def _handle_analyze(self, body: dict[str, Any]) -> None:
+        """POST /api/analyze — code validation / explanation.
+
+        Request body: ``{"code": "...", "mode": "validate|explain"}``
+        """
+        code = body.get("code", "")
+        mode = body.get("mode", "validate")
+
+        if not code:
+            self._json(400, {"error": "Missing required field: code"})
+            return
+
+        if mode == "validate":
+            data = self.provider.validate_code(code=code)
+        elif mode == "explain":
+            # File-level explanation for the provided code snippet
+            file_path = body.get("file_path", "snippet.py")
+            data = self.provider.context_for_file(file_path=file_path)
+        else:
+            self._json(400, {"error": f"Unknown mode: {mode}. Use 'validate' or 'explain'."})
+            return
+
+        self._json(200, data)
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _read_body(self) -> dict[str, Any] | None:
+        content_length = int(self.headers.get("Content-Length", 0))
+        if content_length == 0:
+            self._json(400, {"error": "Empty request body"})
+            return None
+        raw = self.rfile.read(content_length)
+        try:
+            parsed: dict[str, Any] | None = json.loads(raw.decode("utf-8"))
+            return parsed
+        except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+            self._json(400, {"error": f"Invalid JSON: {exc}"})
+            return None
+
+    def _json(self, status: int, body: dict[str, Any]) -> None:
+        payload = json.dumps(body, indent=2, default=str).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(payload)))
+        self._cors_headers()
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def _cors_headers(self) -> None:
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+        self.send_header("Access-Control-Allow-Headers", "Content-Type")
+
+
+def _qs_first(qs: dict[str, list[str]], key: str, default: str = "") -> str:
+    """Return the first value for a query-string key, or *default*."""
+    vals = qs.get(key, [])
+    return vals[0] if vals else default

semantic_code_intelligence/web/server.py

@@ -0,0 +1,397 @@
+"""Combined web server — serves both the REST API and web UI.
+
+Merges API and UI routing into a single HTTP handler so that
+a single ``codexa web`` command provides both the browser interface and the
+developer API on the same port.
+
+Uses only the Python standard library.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+import urllib.parse
+from http.server import HTTPServer, BaseHTTPRequestHandler
+from pathlib import Path
+from typing import Any
+
+from semantic_code_intelligence.bridge.context_provider import ContextProvider
+from semantic_code_intelligence.utils.logging import get_logger
+from semantic_code_intelligence.web.api import APIHandler, _qs_first
+from semantic_code_intelligence.web.ui import (
+    UIHandler,
+    page_search,
+    page_symbols,
+    page_tools,
+    page_quality,
+    page_ask,
+    page_workspace,
+    page_viz,
+    _page,
+)
+from semantic_code_intelligence.web.visualize import (
+    render_call_graph,
+    render_dependency_graph,
+)
+
+logger = get_logger("web.server")
+
+
+class _CombinedHandler(BaseHTTPRequestHandler):
+    """Routes API requests to ``APIHandler`` logic and UI requests to page builders.
+
+    Requests starting with ``/api/`` or ``/health`` are handled by API
+    logic; everything else returns server-rendered HTML pages.
+    """
+
+    project_root: Path
+    provider: ContextProvider
+
+    def log_message(self, fmt: str, *args: Any) -> None:
+        logger.debug(fmt, *args)
+
+    # ------------------------------------------------------------------
+    # Routing
+    # ------------------------------------------------------------------
+
+    def do_GET(self) -> None:  # noqa: N802
+        parsed = urllib.parse.urlparse(self.path)
+        path = parsed.path.rstrip("/") or "/"
+        qs = urllib.parse.parse_qs(parsed.query)
+
+        # API routes — delegate to APIHandler methods directly
+        if path.startswith("/api/") or path == "/health":
+            self._dispatch_api_get(path, qs)
+        else:
+            self._dispatch_ui(path, qs)
+
+    def do_POST(self) -> None:  # noqa: N802
+        parsed = urllib.parse.urlparse(self.path)
+        path = parsed.path.rstrip("/")
+        self._dispatch_api_post(path)
+
+    def do_OPTIONS(self) -> None:  # noqa: N802
+        self.send_response(204)
+        self._cors_headers()
+        self.end_headers()
+
+    # ------------------------------------------------------------------
+    # API dispatch (inline — avoids creating new handler instances)
+    # ------------------------------------------------------------------
+
+    def _dispatch_api_get(self, path: str, qs: dict[str, list[str]]) -> None:
+        import time
+
+        if path == "/health":
+            codex_dir = self.project_root / ".codexa"
+            self._json(200, {
+                "status": "ok",
+                "project_root": str(self.project_root),
+                "indexed": (codex_dir / "index").exists() if codex_dir.exists() else False,
+                "config_found": (codex_dir / "config.json").exists() if codex_dir.exists() else False,
+            })
+        elif path == "/api/search":
+            query = _qs_first(qs, "q", "")
+            if not query:
+                self._json(400, {"error": "Missing required parameter: q"})
+                return
+            top_k = int(_qs_first(qs, "top_k", "5"))
+            threshold = float(_qs_first(qs, "threshold", "0.2"))
+            start = time.monotonic()
+            data = self.provider.context_for_query(query, top_k=top_k, threshold=threshold)
+            data["elapsed_ms"] = round((time.monotonic() - start) * 1000, 2)
+            self._json(200, data)
+        elif path == "/api/symbols":
+            builder = self.provider._ensure_indexed()
+            file_filter = _qs_first(qs, "file", "")
+            kind_filter = _qs_first(qs, "kind", "")
+            symbols = builder.get_all_symbols()
+            if file_filter:
+                symbols = [s for s in symbols if file_filter in s.file_path]
+            if kind_filter:
+                symbols = [s for s in symbols if s.kind == kind_filter]
+            self._json(200, {
+                "count": len(symbols),
+                "symbols": [s.to_dict() for s in symbols[:200]],
+            })
+        elif path == "/api/deps":
+            file_path = _qs_first(qs, "file", "")
+            data = self.provider.get_dependencies(file_path=file_path)
+            self._json(200, data)
+        elif path == "/api/callgraph":
+            symbol = _qs_first(qs, "symbol", "")
+            data = self.provider.get_call_graph(symbol_name=symbol)
+            self._json(200, data)
+        elif path == "/api/summary":
+            data = self.provider.context_for_repo()
+            self._json(200, data)
+        elif path == "/api/quality":
+            try:
+                from semantic_code_intelligence.ci.quality import analyze_project
+                report = analyze_project(self.project_root)
+                self._json(200, report.to_dict())
+            except Exception as exc:
+                self._json(500, {"error": str(exc)})
+        elif path == "/api/metrics":
+            try:
+                from semantic_code_intelligence.ci.metrics import compute_project_metrics
+                pm = compute_project_metrics(self.project_root)
+                self._json(200, pm.to_dict())
+            except Exception as exc:
+                self._json(500, {"error": str(exc)})
+        elif path == "/api/hotspots":
+            try:
+                from semantic_code_intelligence.ci.hotspots import analyze_hotspots
+                from semantic_code_intelligence.context.engine import CallGraph, ContextBuilder, DependencyMap
+                builder = ContextBuilder()
+                dep_map = DependencyMap()
+                root = self.project_root
+                py_files = sorted(root.rglob("*.py"))
+                py_files = [f for f in py_files if ".venv" not in f.parts and "__pycache__" not in f.parts]
+                for fp in py_files:
+                    try:
+                        content = fp.read_text(encoding="utf-8", errors="replace")
+                        builder.index_file(str(fp), content)
+                        dep_map.add_file(str(fp), content)
+                    except Exception:
+                        continue
+                symbols = builder.get_all_symbols()
+                call_graph = CallGraph()
+                call_graph.build(symbols)
+                report = analyze_hotspots(symbols, call_graph, dep_map, root)
+                self._json(200, report.to_dict())
+            except Exception as exc:
+                self._json(500, {"error": str(exc)})
+        elif path.startswith("/api/viz/"):
+            kind = path.replace("/api/viz/", "").strip("/")
+            target = _qs_first(qs, "target", "")
+            try:
+                if kind == "callgraph":
+                    data = self.provider.get_call_graph(symbol_name=target)
+                    edges = data.get("edges", [])
+                    mermaid = render_call_graph(edges)
+                elif kind == "deps":
+                    data = self.provider.get_dependencies(file_path=target)
+                    mermaid = render_dependency_graph(data)
+                else:
+                    self._json(400, {"error": f"Unknown viz kind: {kind}"})
+                    return
+                self._json(200, {"kind": kind, "mermaid": mermaid})
+            except Exception as exc:
+                self._json(500, {"error": str(exc)})
+        else:
+            self._json(404, {"error": "Not found", "path": self.path})
+
+    def _dispatch_api_post(self, path: str) -> None:
+        import time
+
+        content_length = int(self.headers.get("Content-Length", 0))
+        if content_length == 0:
+            self._json(400, {"error": "Empty request body"})
+            return
+        raw = self.rfile.read(content_length)
+        try:
+            body = json.loads(raw.decode("utf-8"))
+        except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+            self._json(400, {"error": f"Invalid JSON: {exc}"})
+            return
+
+        if path == "/api/ask":
+            question = body.get("question", "")
+            if not question:
+                self._json(400, {"error": "Missing required field: question"})
+                return
+            top_k = body.get("top_k", 5)
+            start = time.monotonic()
+            try:
+                from semantic_code_intelligence.config.settings import load_config, LLMConfig
+                from semantic_code_intelligence.llm.reasoning import ReasoningEngine
+                config = load_config(self.project_root)
+                llm_cfg: LLMConfig = config.llm
+                if llm_cfg.provider == "openai":
+                    from semantic_code_intelligence.llm.openai_provider import OpenAIProvider
+                    provider = OpenAIProvider(
+                        api_key=llm_cfg.api_key, model=llm_cfg.model,
+                        base_url=llm_cfg.base_url or None,
+                        temperature=llm_cfg.temperature, max_tokens=llm_cfg.max_tokens,
+                    )
+                elif llm_cfg.provider == "ollama":
+                    from semantic_code_intelligence.llm.ollama_provider import OllamaProvider
+                    provider = OllamaProvider(
+                        model=llm_cfg.model,
+                        base_url=llm_cfg.base_url or "http://localhost:11434",
+                        temperature=llm_cfg.temperature, max_tokens=llm_cfg.max_tokens,
+                    )
+                else:
+                    provider = None  # type: ignore[assignment]
+                if provider is not None:
+                    engine = ReasoningEngine(provider, self.project_root)
+                    result = engine.ask(question, top_k=top_k)
+                    elapsed = (time.monotonic() - start) * 1000
+                    self._json(200, {
+                        "question": result.question,
+                        "answer": result.answer,
+                        "snippets": result.context_snippets,
+                        "elapsed_ms": round(elapsed, 2),
+                    })
+                    return
+            except Exception:
+                logger.debug("LLM ask failed, falling back to context search", exc_info=True)
+            # Fallback: return snippets with a synthesized answer
+            data = self.provider.context_for_query(question, top_k=top_k)
+            snippets = data.get("snippets", [])
+            summary_parts = []
+            for s in snippets[:3]:
+                fp = s.get("file_path", "")
+                sl = s.get("start_line", "")
+                summary_parts.append(f"- {fp} (line {sl})")
+            answer = f"Based on {len(snippets)} relevant code snippets:\n" + "\n".join(summary_parts)
+            if not snippets:
+                answer = "No relevant code found for this question. Try rephrasing or indexing more files."
+            data["answer"] = answer
+            data["elapsed_ms"] = round((time.monotonic() - start) * 1000, 2)
+            self._json(200, data)
+        elif path == "/api/analyze":
+            code = body.get("code", "")
+            mode = body.get("mode", "validate")
+            if not code:
+                self._json(400, {"error": "Missing required field: code"})
+                return
+            if mode == "validate":
+                data = self.provider.validate_code(code=code)
+            elif mode == "explain":
+                file_path = body.get("file_path", "snippet.py")
+                data = self.provider.context_for_file(file_path=file_path)
+            else:
+                self._json(400, {"error": f"Unknown mode: {mode}"})
+                return
+            self._json(200, data)
+        elif path == "/api/tools/run":
+            tool_name = body.get("tool_name", "")
+            arguments = body.get("arguments", {})
+            if not tool_name:
+                self._json(400, {"error": "Missing required field: tool_name"})
+                return
+            try:
+                from semantic_code_intelligence.tools.executor import ToolExecutor
+                from semantic_code_intelligence.tools.protocol import ToolInvocation
+                executor = ToolExecutor(self.project_root)
+                invocation = ToolInvocation(tool_name=tool_name, arguments=arguments)
+                result = executor.execute(invocation)
+                self._json(200, result.to_dict())
+            except Exception as exc:
+                self._json(500, {"error": str(exc)})
+        else:
+            self._json(404, {"error": "Not found"})
+
+    # ------------------------------------------------------------------
+    # UI dispatch
+    # ------------------------------------------------------------------
+
+    def _dispatch_ui(self, path: str, qs: dict[str, list[str]]) -> None:
+        pages: dict[str, str] = {
+            "/": page_search(),
+            "/symbols": page_symbols(),
+            "/tools": page_tools(),
+            "/quality": page_quality(),
+            "/ask": page_ask(),
+            "/workspace": page_workspace(),
+            "/viz": page_viz(),
+        }
+        content = pages.get(path)
+        if content:
+            self._html(200, content)
+        else:
+            self._html(404, _page("Not Found", '<div class="empty">Page not found.</div>'))
+
+    # ------------------------------------------------------------------
+    # Response helpers
+    # ------------------------------------------------------------------
+
+    def _json(self, status: int, body: dict[str, Any]) -> None:
+        payload = json.dumps(body, indent=2, default=str).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(payload)))
+        self._cors_headers()
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def _html(self, status: int, content: str) -> None:
+        payload = content.encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def _cors_headers(self) -> None:
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+        self.send_header("Access-Control-Allow-Headers", "Content-Type")
+
+
+class WebServer:
+    """Combined web server serving API and UI on a single port.
+
+    Usage::
+
+        server = WebServer(Path("."), host="127.0.0.1", port=8080)
+        server.start()        # blocks
+        # or
+        server.start_background()
+        server.stop()
+    """
+
+    DEFAULT_PORT = 8080
+
+    def __init__(
+        self,
+        project_root: Path,
+        host: str = "127.0.0.1",
+        port: int = DEFAULT_PORT,
+    ) -> None:
+        self._root = project_root.resolve()
+        self._host = host
+        self._port = port
+        self._httpd: HTTPServer | None = None
+        self._thread: threading.Thread | None = None
+        self._provider = ContextProvider(self._root)
+
+    @property
+    def url(self) -> str:
+        return f"http://{self._host}:{self._port}"
+
+    def _make_server(self) -> HTTPServer:
+        _CombinedHandler.project_root = self._root
+        _CombinedHandler.provider = self._provider
+        return HTTPServer((self._host, self._port), _CombinedHandler)
+
+    def start(self) -> None:
+        """Start the server (blocking)."""
+        self._httpd = self._make_server()
+        logger.info("CodexA web server listening on %s", self.url)
+        try:
+            self._httpd.serve_forever()
+        except KeyboardInterrupt:
+            pass
+        finally:
+            self._httpd.server_close()
+
+    def start_background(self) -> None:
+        """Start in a background daemon thread."""
+        self._httpd = self._make_server()
+        self._thread = threading.Thread(target=self._httpd.serve_forever, daemon=True)
+        self._thread.start()
+        logger.info("CodexA web server started in background on %s", self.url)
+
+    def stop(self) -> None:
+        """Shut down the server."""
+        if self._httpd:
+            self._httpd.shutdown()
+            self._httpd.server_close()
+            self._httpd = None
+        if self._thread:
+            self._thread.join(timeout=5)
+            self._thread = None