ata-coder 2.4.2__py3-none-any.whl

ata_coder/server.py

@@ -0,0 +1,882 @@
+"""
+ATA Coder — HTTP API Server (stdlib-only, no FastAPI dependency).
+
+Uses Python's built-in http.server + httpx for maximum compatibility.
+Provides REST API and SSE streaming for the agent.
+
+Endpoints:
+  POST /chat              — Non-streaming chat
+  POST /chat/stream       — SSE streaming chat
+  GET  /health            — Health check
+  GET  /sessions          — List active sessions
+  GET  /sessions/{id}     — Get session info
+  DELETE /sessions/{id}   — Delete a session
+  GET  /tools             — List available tools
+  GET  /skills            — List available skills
+  GET  /models            — List available models
+
+Usage:
+  python server.py                        # Start on port 8000
+  python server.py --port 3000            # Custom port
+  python server.py --host 0.0.0.0         # Public access
+  python main.py --server                 # From main launcher
+"""
+
+import json
+import logging
+import os
+import queue
+import sys
+import threading
+import time
+from http.server import HTTPServer, BaseHTTPRequestHandler
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+# Allow running directly (python server.py) without pip install -e .
+_pkg = str(Path(__file__).parent.resolve())
+if _pkg not in sys.path:
+    sys.path.insert(0, _pkg)
+
+from .config import AppConfig, get_config
+from .tools import TOOL_DEFINITIONS
+from .server_session import SessionStore
+from .server_shell import shell_open, shell_ensure, shell_close, shell_close_all, get_shell_sessions
+from .skills import get_skill_manager
+from .utils import brief_args
+
+logger = logging.getLogger(__name__)
+
+
+# Session store → server_session.py (SessionStore)
+
+# ══════════════════════════════════════════════════════════════════════# HTTP Request Handler
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class AgentAPIHandler(BaseHTTPRequestHandler):
+    """HTTP handler for the ATA Coder API.
+
+    *config* and *store* are set as class attributes by :func:`create_server`
+    before the server starts accepting requests.  Each handler instance
+    accesses them via ``self`` (Python's normal attribute resolution finds
+    them on the class).  This is the standard ``http.server`` pattern and
+    is safe because ``HTTPServer`` handles requests sequentially — if you
+    switch to ``ThreadingHTTPServer``, promote these to instance attributes
+    in ``__init__``.
+    """
+
+    # Class-level references (set by server factory)
+    config: AppConfig = None
+    store: SessionStore = None
+    _ws_lock: threading.Lock = threading.Lock()  # protects workspace dir reads/writes
+
+    def __init__(self, *args, **kwargs):
+        # Per-instance copies for thread-safe access under ThreadingHTTPServer
+        self.config = self.__class__.config
+        self.store = self.__class__.store
+        super().__init__(*args, **kwargs)
+
+    def log_message(self, format, *args):
+        """Suppress default logging; use our logger."""
+        logger.debug("%s - %s", self.client_address[0], format % args)
+
+    # ── Auth ────────────────────────────────────────────────────────────
+
+    def _check_auth(self) -> bool:
+        """Verify API token if ATA_CODER_API_TOKEN is configured.
+
+        When no token is configured, authentication is disabled and all
+        requests are allowed (convenience for local/dev use).  Set
+        ATA_CODER_API_TOKEN to require Bearer token authentication.
+        """
+        expected = os.environ.get("ATA_CODER_API_TOKEN", "")
+        if not expected:
+            return True  # no token configured = allow all
+        token = (self.headers.get("Authorization", "")
+                 .removeprefix("Bearer ").strip())
+        if token != expected:
+            logger.warning("Invalid or missing API token from %s", self.client_address[0])
+            return False
+        return True
+
+    def _require_auth(self, method_name: str) -> bool:
+        """Check auth and send 403 if invalid. Returns True if ok."""
+        if self._check_auth():
+            return True
+        self._error(403, "Invalid or missing API token. "
+                   "Set ATA_CODER_API_TOKEN env var on the server, "
+                   "then send Authorization: Bearer <token> header.")
+        return False
+
+    # ── CORS ────────────────────────────────────────────────────────────
+
+    def _cors(self):
+        """Set CORS headers, reflecting localhost origins.
+
+        Allows any localhost origin (multiple ports) for development,
+        plus the Origin header itself if it is a localhost address.
+        """
+        origin = self.headers.get("Origin", "")
+        if origin and (
+            origin.startswith("http://localhost")
+            or origin.startswith("http://127.0.0.1")
+            or origin.startswith("http://[::1]")
+        ):
+            self.send_header("Access-Control-Allow-Origin", origin)
+        else:
+            self.send_header("Access-Control-Allow-Origin", "http://localhost:3000")
+        self.send_header("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS")
+        self.send_header("Access-Control-Allow-Headers", "Content-Type, Authorization")
+
+    def do_OPTIONS(self):
+        self.send_response(204)
+        self._cors()
+        self.end_headers()
+
+    # ── JSON helpers ────────────────────────────────────────────────────
+
+    def _json_response(self, data: Any, status: int = 200):
+        self.send_response(status)
+        self._cors()
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.end_headers()
+        try:
+            self.wfile.write(json.dumps(data, ensure_ascii=False).encode("utf-8"))
+        except (ConnectionAbortedError, ConnectionResetError, BrokenPipeError, OSError):
+            pass  # client disconnected before response could be sent
+
+    def _error(self, status: int, message: str):
+        self._json_response({"error": message}, status)
+
+    def _read_body(self) -> dict | None:
+        length = int(self.headers.get("Content-Length", 0))
+        if length == 0:
+            return {}
+        if length > 10_000_000:  # 10MB max
+            self._error(413, f"Request body too large ({length:,} bytes). Max 10MB.")
+            return None
+        body = self.rfile.read(length)
+        try:
+            return json.loads(body)
+        except json.JSONDecodeError as e:
+            self._error(400, f"Invalid JSON: {e}")
+            return None
+
+    def _path_parts(self) -> list[str]:
+        parsed = urlparse(self.path)
+        return [p for p in parsed.path.split("/") if p]
+
+    # ── Routing ─────────────────────────────────────────────────────────
+
+    def do_GET(self):
+        if self.path != "/favicon.ico":
+            logger.debug("GET %s", self.path)
+        parts = self._path_parts()
+
+        if self.path == "/" or self.path == "/index.html":
+            self._serve_spa()
+        elif self.path == "/health":
+            self._handle_health()
+        elif self.path == "/tools":
+            self._handle_tools()
+        elif self.path == "/skills":
+            self._handle_skills()
+        elif self.path == "/models":
+            self._handle_models()
+        elif self.path == "/sessions":
+            self._handle_list_sessions()
+        elif self.path == "/api/workspace":
+            with self._ws_lock:
+                ws = self.config.agent.workspace_dir
+            self._json_response({"workspace": ws})
+        elif self.path.startswith("/css/") or self.path.startswith("/js/"):
+            self._serve_static(self.path.lstrip("/"))
+        elif len(parts) == 2 and parts[0] == "sessions":
+            self._handle_get_session(parts[1])
+        else:
+            self._error(404, f"Not found: {self.path}")
+
+    def do_POST(self):
+        logger.debug("POST %s", self.path)
+        if self.path == "/chat":
+            self._handle_chat()
+        elif self.path == "/chat/stream":
+            self._handle_chat_stream()
+        elif self.path == "/api/workspace":
+            self._handle_set_workspace()
+        elif self.path == "/api/shell":
+            self._handle_shell()
+        else:
+            self._error(404, f"Not found: {self.path}")
+
+    def do_DELETE(self):
+        if not self._require_auth("DELETE"):
+            return
+        parts = self._path_parts()
+        if len(parts) == 2 and parts[0] == "sessions":
+            self._handle_delete_session(parts[1])
+        else:
+            self._error(404, f"Not found: {self.path}")
+
+    # ── Chat helpers ─────────────────────────────────────────────────────
+
+    def _parse_chat_request(self) -> dict | None:
+        """Read and validate the JSON body for /chat and /chat/stream.
+
+        Returns a dict with keys: message, session_id, skill, model_override,
+        thinking_override.  Returns None if the body is invalid (error response
+        already sent).
+        """
+        try:
+            body = self._read_body()
+        except Exception:
+            self._error(400, "Invalid JSON body")
+            return None
+        if body is None:
+            return None  # error response already sent by _read_body
+        message = body.get("message", "")
+        if not message:
+            self._error(400, "Missing 'message' field")
+            return None
+        return {
+            "message": message,
+            "session_id": body.get("session_id"),
+            "skill": body.get("skill", ""),
+            "model_override": body.get("model", ""),
+            "thinking_override": body.get("thinking", ""),
+        }
+
+    # ── Handlers ────────────────────────────────────────────────────────
+
+    def _handle_health(self):
+        skill_mgr = get_skill_manager()
+        with self._ws_lock:
+            ws = self.config.agent.workspace_dir
+        self._json_response({
+            "status": "ok",
+            "model": self.config.llm.model,
+            "workspace": ws,
+            "tools": len(TOOL_DEFINITIONS),
+            "skills": [s.name for s in skill_mgr.list_skills()],
+            "mcp_servers": [],
+        })
+
+    def _handle_tools(self):
+        if not self._require_auth("tools"):
+            return
+        self._json_response({
+            "tools": [
+                {"name": t["function"]["name"], "description": t["function"]["description"]}
+                for t in TOOL_DEFINITIONS
+            ]
+        })
+
+    def _handle_skills(self):
+        if not self._require_auth("skills"):
+            return
+        skill_mgr = get_skill_manager()
+        self._json_response({
+            "skills": [
+                {"name": s.name, "description": s.description, "triggers": s.triggers}
+                for s in skill_mgr.list_skills()
+            ]
+        })
+
+    def _handle_models(self):
+        """Fetch available models from API if possible, else return cached."""
+        try:
+            from .model_registry import fetch_available_models
+            models = fetch_available_models(self.config.llm.base_url, self.config.llm.api_key)
+            if models:
+                models_data = [{"id": m, "owned_by": "api"} for m in sorted(models)]
+                self._json_response({"models": models_data, "current": self.config.llm.model})
+                return
+        except Exception:
+            logger.debug("Failed to fetch models from API, using cache", exc_info=True)
+        # Fallback: cached model list
+        import os
+        cached = os.environ.get("ATA_CODER_MODELS_CACHE", self.config.llm.model)
+        models = [{"id": m.strip(), "owned_by": ""} for m in cached.split(",") if m.strip()]
+        self._json_response({"models": models, "current": self.config.llm.model})
+
+    def _handle_set_workspace(self):
+        """Change the agent workspace directory."""
+        if not self._require_auth("workspace"):
+            return
+        body = self._read_body()
+        if body is None:
+            return  # error response already sent by _read_body
+        new_ws = body.get("workspace", "")
+        if not new_ws:
+            self._error(400, "Missing 'workspace' field")
+            return
+        p = Path(new_ws).expanduser().resolve()
+        if not p.exists() or not p.is_dir():
+            self._error(400, f"Directory not found or not a directory: {p}")
+            return
+        with self._ws_lock:
+            self.config.agent.workspace_dir = str(p)
+        self._json_response({"workspace": str(p), "ok": True})
+
+    def _handle_shell(self):
+        """Interactive PowerShell — persistent session with SSE streaming output."""
+        if not self._require_auth("shell"):
+            return
+
+        body = self._read_body()
+        if body is None:
+            return  # error response already sent by _read_body
+        sid = body.get("session", "")
+        command = body.get("command", "")
+        action = body.get("action", "send")
+
+        # Open new session
+        if action == "open":
+            with self._ws_lock:
+                ws = self.config.agent.workspace_dir
+            sid = shell_open(ws)
+            default_prompt = "PS> " if os.name == "nt" else "$ "
+            _, _, _, prompt = get_shell_sessions().get(sid, (None, None, None, default_prompt))
+            self._json_response({"session": sid, "prompt": prompt})
+            return
+
+        # Close session
+        if action == "close":
+            shell_close(sid)
+            self._json_response({"ok": True})
+            return
+
+        # Send command to persistent session
+        if not command:
+            self._error(400, "Missing 'command'")
+            return
+        if not sid:
+            self._error(400, "Missing 'session'. Open a session first.")
+            return
+
+        # Safety check: run command through the same guard as the agent
+        from .safety_guard import SafetyGuard
+        with self._ws_lock:
+            ws = self.config.agent.workspace_dir
+        guard = SafetyGuard(ws)
+        safety = guard.check_shell(command)
+        if not safety.allowed:
+            logger.warning("⛔ Blocked shell command [%s]: %s", sid[:6], command[:120])
+            self._error(403, f"Command blocked: {safety.reason}")
+            return
+        if safety.warnings:
+            for w in safety.warnings:
+                logger.warning("⚠️  Shell warning [%s]: %s", sid[:6], w)
+
+        logger.info("💻 [%s] %s", sid[:6], command[:120])
+
+        proc, outq, lock, prompt = shell_ensure(sid, ws)
+        if not proc:
+            self._error(500, "Shell process not running")
+            return
+
+        # Drain any stale output, send command
+        with lock:
+            while not outq.empty():
+                try: outq.get_nowait()
+                except queue.Empty: break
+            proc.stdin.write((command + "\n").encode("utf-8"))
+            proc.stdin.flush()
+
+        # Stream output via SSE
+        self.send_response(200)
+        self._cors()
+        self.send_header("Content-Type", "text/event-stream")
+        self.send_header("Cache-Control", "no-cache")
+        self.end_headers()
+
+        # Adaptive silence timeout: short initial wait, longer between lines
+        FAST_TIMEOUT = 0.6     # initial wait for first output (per cycle)
+        SLOW_TIMEOUT = 4.0     # silence between output lines
+        FIRST_OUTPUT_DEADLINE = time.time() + 10.0  # max wait for any output at all
+        deadline = time.time() + 120
+        silence_dl = time.time() + FAST_TIMEOUT
+        has_output = False
+        while time.time() < deadline:
+            try:
+                line = outq.get(timeout=0.2)
+                try:
+                    self.wfile.write(
+                        f"data: {json.dumps({'text': line})}\n\n".encode("utf-8")
+                    )
+                    self.wfile.flush()
+                except (ConnectionAbortedError, ConnectionResetError, BrokenPipeError, OSError):
+                    return  # client disconnected
+                has_output = True
+                silence_dl = time.time() + SLOW_TIMEOUT
+            except queue.Empty:
+                pass
+            if time.time() > silence_dl:
+                if not has_output and time.time() < FIRST_OUTPUT_DEADLINE:
+                    silence_dl = time.time() + FAST_TIMEOUT  # keep waiting for first output
+                    continue
+                break  # silence deadline passed: either got output or gave up on first
+
+        try:
+            self.wfile.write(f"event: done\ndata: {json.dumps({'done': True})}\n\n".encode("utf-8"))
+            self.wfile.flush()
+        except (ConnectionAbortedError, ConnectionResetError, BrokenPipeError, OSError):
+            pass  # client disconnected
+
+    def _serve_static(self, rel_path: str):
+        """Serve a static file from the web/ directory."""
+        web_root = Path(__file__).parent / "web"
+        file_path = web_root / rel_path
+        if not file_path.exists() or not file_path.is_file():
+            self._error(404, f"Not found: {self.path}")
+            return
+        # Safety: prevent path traversal
+        try:
+            file_path.resolve().relative_to(web_root.resolve())
+        except ValueError:
+            self._error(403, "Forbidden")
+            return
+        content = file_path.read_bytes()
+        ct = "text/css" if rel_path.endswith(".css") else "application/javascript"
+        self.send_response(200)
+        self._cors()
+        self.send_header("Content-Type", ct + "; charset=utf-8")
+        self.send_header("Content-Length", str(len(content)))
+        self.send_header("Cache-Control", "public, max-age=3600")
+        self.end_headers()
+        try:
+            self.wfile.write(content)
+        except (ConnectionAbortedError, ConnectionResetError, BrokenPipeError, OSError):
+            pass  # client disconnected
+
+    def _serve_spa(self):
+        """Serve the single-page web UI from web/ directory."""
+        for fname in ("web/index.html", "web_ui.html"):
+            spa_html = Path(__file__).parent / fname
+            if spa_html.exists():
+                content = spa_html.read_text(encoding="utf-8")
+                break
+        else:
+            content = "<h1>ATA Coder Web UI</h1><p>web/index.html not found.</p>"
+        self.send_response(200)
+        self._cors()
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.end_headers()
+        try:
+            self.wfile.write(content.encode("utf-8"))
+        except (ConnectionAbortedError, ConnectionResetError, BrokenPipeError, OSError):
+            pass  # client disconnected
+
+    def _handle_list_sessions(self):
+        if not self._require_auth("sessions"):
+            return
+        self._json_response({"sessions": self.store.list_sessions()})
+
+    def _handle_get_session(self, sid: str):
+        meta = self.store.get_meta(sid)
+        if not meta:
+            self._error(404, "Session not found")
+            return
+        info = dict(meta)
+        agent = self.store.get(sid)
+        if agent:
+            info["conversation"] = agent.get_conversation_summary()
+        self._json_response(info)
+
+    def _handle_delete_session(self, sid: str):
+        if self.store.delete(sid):
+            self._json_response({"status": "deleted", "session_id": sid})
+        else:
+            self._error(404, "Session not found")
+
+    # ── Chat (non-streaming) ────────────────────────────────────────────
+
+    def _handle_chat(self):
+        if not self._require_auth("chat"):
+            return
+
+        req = self._parse_chat_request()
+        if req is None:
+            return
+
+        logger.info("📩 [%s] %.200s", time.strftime('%H:%M:%S'), self._sanitize_log(req["message"]))
+
+        is_new_session = req["session_id"] is None or self.store.get(req["session_id"]) is None
+        sid, agent = self.store.get_or_create(req["session_id"], self.config, req["skill"])
+
+        if req["model_override"]:
+            agent.llm.set_model(req["model_override"])
+            agent.llm.register_tools(agent._all_tools)
+        if req["thinking_override"]:
+            agent.llm.config.thinking_strength = req["thinking_override"]
+
+        try:
+            import asyncio as _asyncio
+            response = _asyncio.run(agent.run(req["message"], stream=False, skill_name=req["skill"] or None,
+                                               reset_context=is_new_session))
+        except Exception as e:
+            logger.exception("Agent run failed: %s", e)
+            self._error(500, "Internal server error")
+            return
+
+        self.store.update_meta(
+            sid,
+            messages=len(agent._state.messages),
+            tool_calls=agent._state.tool_call_count,
+        )
+
+        self._json_response({
+            "session_id": sid,
+            "response": response,
+            "tool_calls": agent._state.tool_call_count,
+            "tokens": {
+                "prompt": agent.llm.total_prompt_tokens,
+                "completion": agent.llm.total_completion_tokens,
+                "total": agent.llm.total_tokens,
+            },
+        })
+
+    # ── Chat (SSE streaming) ────────────────────────────────────────────
+
+    def _handle_chat_stream(self):
+        if not self._require_auth("chat/stream"):
+            return
+
+        req = self._parse_chat_request()
+        if req is None:
+            return
+
+        logger.info("📩 [%s] %.200s  skill=%s model=%s thinking=%s",
+                    time.strftime('%H:%M:%S'), req["message"],
+                    req["skill"] or "-", req["model_override"] or "-", req["thinking_override"] or "-")
+
+        is_new_session = req["session_id"] is None or self.store.get(req["session_id"]) is None
+        sid, agent = self.store.get_or_create(req["session_id"], self.config, req["skill"])
+
+        if req["model_override"]:
+            agent.llm.set_model(req["model_override"])
+            agent.llm.register_tools(agent._all_tools)
+        if req["thinking_override"]:
+            agent.llm.config.thinking_strength = req["thinking_override"]
+
+        self.send_response(200)
+        self._cors()
+        self.send_header("Content-Type", "text/event-stream")
+        self.send_header("Cache-Control", "no-cache")
+        self.send_header("Connection", "close")
+        self.send_header("X-Accel-Buffering", "no")
+        self.end_headers()
+
+        # ── Streaming loop (async, runs inside asyncio.run()) ──
+        import asyncio as _asyncio
+
+        async def _stream_agent():
+            events: _asyncio.Queue = _asyncio.Queue()
+
+            def _push_event(evt):
+                """Filter events through SSE converter; skip non-streamable ones."""
+                tup = self._sse_event_tuple(evt)
+                if tup is not None:
+                    events.put_nowait(tup)
+
+            agent.on_event(_push_event)
+
+            result_holder: dict[str, Any] = {"response": "", "error": None}
+
+            async def _run_agent():
+                try:
+                    logger.info("▶ Agent started")
+                    result_holder["response"] = await agent.run(
+                        req["message"], stream=True, skill_name=req["skill"] or None,
+                        reset_context=is_new_session
+                    )
+                    logger.info("✓ Agent completed")
+                except Exception as exc:
+                    logger.info("✗ Agent error: %s", exc)
+                    result_holder["error"] = str(exc)
+
+            agent_task = _asyncio.create_task(_run_agent())
+
+            # Stream events until agent task completes
+            while not agent_task.done():
+                try:
+                    evt_type, payload = await _asyncio.wait_for(events.get(), timeout=0.1)
+                except _asyncio.TimeoutError:
+                    continue
+
+                sse_data = _format_sse_data(evt_type, payload)
+                if sse_data is None:
+                    continue
+                line = f"event: {evt_type}\ndata: {sse_data}\n\n"
+                try:
+                    self.wfile.write(line.encode("utf-8"))
+                    self.wfile.flush()
+                except (ConnectionAbortedError, ConnectionResetError, BrokenPipeError, OSError):
+                    agent_task.cancel()
+                    return
+
+            # Drain remaining events
+            while not events.empty():
+                try:
+                    evt_type, payload = events.get_nowait()
+                    sse_data = _format_sse_data(evt_type, payload)
+                    if sse_data:
+                        line = f"event: {evt_type}\ndata: {sse_data}\n\n"
+                        self.wfile.write(line.encode("utf-8"))
+                        self.wfile.flush()
+                except _asyncio.QueueEmpty:
+                    break
+
+            return result_holder
+
+        result_holder = _asyncio.run(_stream_agent())
+
+        # Send final event with session_id so frontend can reuse it
+        final = json.dumps({
+            "session_id": sid,
+            "response": result_holder["response"] or "",
+            "error": result_holder["error"],
+        })
+        try:
+            self.wfile.write(f"event: done\ndata: {final}\n\n".encode("utf-8"))
+            self.wfile.flush()
+        except (ConnectionAbortedError, ConnectionResetError, BrokenPipeError, OSError):
+            pass
+
+        self.store.update_meta(
+            sid,
+            messages=len(agent._state.messages),
+            tool_calls=agent._state.tool_call_count,
+        )
+
+    # ── SSE event builder (shared across stream handlers) ─────────────────
+
+    @staticmethod
+    def _sanitize_log(text: str) -> str:
+        """Strip common secret patterns from text before logging."""
+        import re as _re
+        # API key patterns (sk-..., rk-, etc.)
+        text = _re.sub(r'sk-[a-zA-Z0-9_-]{20,}', 'sk-***', text)
+        text = _re.sub(r'rk-[a-zA-Z0-9_-]{20,}', 'rk-***', text)
+        # Bearer tokens
+        text = _re.sub(r'Bearer\s+[a-zA-Z0-9._\-]+', 'Bearer ***', text)
+        # AWS-style keys
+        text = _re.sub(r'AKIA[0-9A-Z]{16}', 'AKIA***', text)
+        text = _re.sub(r'AIza[0-9A-Za-z\-_]{35}', 'AIza***', text)
+        return text
+
+    @staticmethod
+    def _sse_event_tuple(event: Any):
+        """Convert an AgentEvent into an (event_type, payload) tuple, or None if skipped."""
+        from .core import (TextDeltaEvent, ToolCallEvent, ToolResultEvent,
+                            ToolStreamEvent, CompleteEvent, ErrorEvent, ReasoningEvent, ThinkingEvent)
+
+        if isinstance(event, TextDeltaEvent):
+            logger.debug("📤 text: %s", AgentAPIHandler._sanitize_log(event.text[:120]))
+            return ("text", event.text)
+        elif isinstance(event, ReasoningEvent):
+            logger.debug("🧠 thinking: %.100s", AgentAPIHandler._sanitize_log(event.text))
+            return ("thinking", event.text[:200])
+        elif isinstance(event, ThinkingEvent):
+            return None
+        elif isinstance(event, ToolStreamEvent):
+            # Real-time shell output — stream immediately to frontend
+            return ("tool_stream", {"tool": event.tool_name, "chunk": event.chunk})
+        elif isinstance(event, ToolCallEvent):
+            logger.debug("🔧 %s %s", event.tool_name, brief_args(event.arguments))
+            return ("tool_call", {"name": event.tool_name, "arguments": event.arguments, "source": event.source})
+        elif isinstance(event, ToolResultEvent):
+            if event.result.success:
+                logger.debug("  ✅ %s", AgentAPIHandler._sanitize_log((event.result.output or "")[:100].replace("\n"," ")))
+            else:
+                logger.debug("  ❌ %s", AgentAPIHandler._sanitize_log((event.result.error or "?")[:100]))
+            return ("tool_result", {"name": event.tool_name, "success": event.result.success,
+                                    "output": (event.result.output or "")[:4000], "error": event.result.error})
+        elif isinstance(event, ErrorEvent):
+            logger.info("💥 ERROR: %s", AgentAPIHandler._sanitize_log(event.error))
+            return ("error", {"error": event.error})
+        elif isinstance(event, CompleteEvent):
+            logger.info("🏁 Complete — %d tools, %.1fs", event.total_tool_calls, event.total_time)
+            return ("complete", {"tool_calls": event.total_tool_calls, "time": event.total_time})
+        return None
+
+
+def _format_sse_data(evt_type: str, payload: Any) -> str | None:
+    """Format an (event_type, payload) tuple into a JSON string for SSE output."""
+    if evt_type == "text":
+        return json.dumps({"type": "text", "text": payload}, ensure_ascii=False)
+    elif evt_type == "tool_stream":
+        return json.dumps({
+            "type": "tool_stream",
+            "tool": payload.get("tool", ""),
+            "chunk": payload.get("chunk", ""),
+        }, ensure_ascii=False)
+    elif evt_type == "thinking":
+        return json.dumps({"type": "thinking", "text": payload}, ensure_ascii=False)
+    elif evt_type == "tool_call":
+        # Send full arguments to the frontend — never truncate.
+        # brief_args() is only for server-side logging (line 677).
+        args = payload.get("arguments", {})
+        # Sanitize surrogates in argument values (defense against UTF-8 crashes)
+        from .utils import sanitize_surrogates
+        args = sanitize_surrogates(args)
+        return json.dumps({
+            "type": "tool_call",
+            "tool": payload["name"],
+            "args_summary": brief_args(args),
+            "args": args,
+        }, ensure_ascii=False)
+    elif evt_type == "tool_result":
+        return json.dumps({
+            "type": "tool_result",
+            "tool": payload["name"],
+            "ok": payload["success"],
+            "output": payload.get("output", ""),
+        }, ensure_ascii=False)
+    elif evt_type == "error":
+        return json.dumps({"type": "error", "error": payload.get("error", "")}, ensure_ascii=False)
+    elif evt_type == "complete":
+        return json.dumps({
+            "type": "complete",
+            "tools": payload["tool_calls"],
+            "time": payload["time"],
+        }, ensure_ascii=False)
+    return json.dumps(payload, ensure_ascii=False)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Server factory
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Shell management → server_shell.py
+
+def create_server(
+    config: AppConfig | None = None,
+    host: str = "127.0.0.1",
+    port: int = 8000,
+) -> HTTPServer:
+    """Create and configure the HTTP API server."""
+
+    # Common mistakes: URLs, port numbers
+    if host.startswith("http://") or host.startswith("https://"):
+        host = host.split("://", 1)[1].rstrip("/")
+    if host.isdigit():
+        port = int(host)
+        host = "127.0.0.1"
+
+    config = config or get_config()
+
+    AgentAPIHandler.config = config
+    AgentAPIHandler.store = SessionStore()
+
+    try:
+        server = HTTPServer((host, port), AgentAPIHandler)
+    except OSError as e:
+        if "10048" in str(e) or "98" in str(e) or "Address already in use" in str(e):
+            logger.error("Port %d is already in use. Use --port to pick another, "
+                        "or check: netstat -ano | findstr :%d", port, port)
+            raise SystemExit(1)
+        raise
+
+    # Close idle connections after 30s to prevent file descriptor exhaustion
+    server.socket.settimeout(30.0)
+    server.timeout = 30
+
+    logger.info("Server created: %s:%d", host, port)
+    return server
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Entry point
+def _detect_lan_ip() -> str | None:
+    """Detect the LAN IP address for mobile/tablet access."""
+    try:
+        import socket
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        s.settimeout(0.1)
+        s.connect(("8.8.8.8", 80))
+        ip = s.getsockname()[0]
+        s.close()
+        return ip
+    except Exception:
+        pass
+    # Fallback: iterate network interfaces
+    try:
+        import socket
+        hostname = socket.gethostname()
+        ip = socket.gethostbyname(hostname)
+        if ip and not ip.startswith("127."):
+            return ip
+    except Exception:
+        pass
+    return None
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def main():
+    import argparse
+    parser = argparse.ArgumentParser(description="ATA Coder API Server")
+    parser.add_argument("--host", default="127.0.0.1", help="Bind host (127.0.0.1 = local only, 0.0.0.0 = LAN accessible)")
+    parser.add_argument("--port", "-p", type=int, default=8000, help="Bind port")
+    parser.add_argument("--local-only", action="store_true", help="Bind to 127.0.0.1 only (no LAN)")
+    parser.add_argument("--allow-all", "-A", action="store_true", help="Skip all permission prompts")
+    parser.add_argument("--model", "-m", help="Model name")
+    parser.add_argument("--verbose", "-v", action="store_true")
+    args = parser.parse_args()
+
+    # Server mode: verbose by default so you can see what the agent is doing
+    log_level = logging.DEBUG if args.verbose else logging.INFO
+    logging.basicConfig(
+        level=log_level,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+
+    if args.allow_all:
+        os.environ["ATA_CODER_ALLOW_ALL"] = "1"
+
+    config = get_config()
+    if args.model:
+        config.llm.model = args.model
+
+    if args.local_only:
+        args.host = "127.0.0.1"
+
+    # Security: warn if binding to all interfaces without authentication
+    if args.host == "0.0.0.0" and not os.environ.get("ATA_CODER_API_TOKEN"):
+        logger.warning(
+            "⚠️  Binding to 0.0.0.0 WITHOUT an API token — "
+            "anyone on the network can access the agent. "
+            "Set ATA_CODER_API_TOKEN env var or use --local-only."
+        )
+
+    server = create_server(config, args.host, args.port)
+
+    # Detect LAN IP for mobile access
+    lan_ip = _detect_lan_ip() if args.host == "0.0.0.0" else None
+
+    print("""
+╔══════════════════════════════════════════════════╗
+║         ATA Coder  —  Web UI              ║
+╠══════════════════════════════════════════════════╣""")
+    print(f"║  Local:   http://127.0.0.1:{args.port:<29}║")
+    if lan_ip:
+        print(f"║  LAN:     http://{lan_ip}:{args.port:<29}║")
+    else:
+        print("║  LAN:     (use --host 0.0.0.0 for LAN access) ║")
+    print(f"""║  Model:   {config.llm.model:<34}║
+║  Tools:   {len(TOOL_DEFINITIONS):<34}║
+╚══════════════════════════════════════════════════╝
+""")
+
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\nShutting down...")
+        shell_close_all()
+        server.shutdown()
+
+
+if __name__ == "__main__":
+    main()