debug-agent-py 0.2.1__py3-none-any.whl

debug_agent/inspectors/runtime.py

@@ -0,0 +1,132 @@
+"""Runtime inspector: GC, memory, threads, process info."""
+
+from __future__ import annotations
+
+import gc
+import os
+import sys
+import threading
+import time
+import tracemalloc
+from typing import Any
+
+from debug_agent.tool_registry import debug_tool, ToolParam
+
+
+@debug_tool("get_gc_stats", "Get garbage collector statistics: collection counts per generation")
+def get_gc_stats() -> dict:
+    counts = gc.get_count()  # (gen0, gen1, gen2) counts
+    return {
+        "generation_counts": {"gen0": counts[0], "gen1": counts[1], "gen2": counts[2]},
+        "garbage_count": len(gc.garbage),
+        "total_objects": len(gc.get_objects()),
+    }
+
+
+@debug_tool("get_memory_summary", "Get process memory usage: RSS, VMS, and Python heap info")
+def get_memory_summary() -> dict:
+    try:
+        import resource
+        rss = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+        # macOS reports in bytes, Linux in KB
+        if sys.platform == "darwin":
+            rss_mb = rss / 1024 / 1024
+        else:
+            rss_mb = rss / 1024
+    except ImportError:
+        rss_mb = 0
+
+    import ctypes
+    info = {"rss_mb": round(rss_mb, 2)}
+
+    # Python object counts
+    counts = {}
+    for obj in gc.get_objects():
+        t = type(obj).__name__
+        counts[t] = counts.get(t, 0) + 1
+    top_types = sorted(counts.items(), key=lambda x: -x[1])[:15]
+    info["top_object_types"] = {t: c for t, c in top_types}
+    info["total_objects"] = sum(counts.values())
+
+    return info
+
+
+@debug_tool("trigger_gc", "Trigger garbage collection and show before/after comparison")
+def trigger_gc() -> dict:
+    before = len(gc.get_objects())
+    collected = gc.collect()
+    after = len(gc.get_objects())
+    return {
+        "objects_before": before,
+        "objects_collected": collected,
+        "objects_after": after,
+        "freed": before - after,
+    }
+
+
+@debug_tool("get_thread_summary", "Get thread state overview: count, names, daemon status")
+def get_thread_summary() -> dict:
+    threads = threading.enumerate()
+    return {
+        "total_threads": len(threads),
+        "threads": [
+            {"name": t.name, "ident": t.ident, "daemon": t.daemon, "alive": t.is_alive()}
+            for t in threads
+        ],
+    }
+
+
+@debug_tool("get_thread_dump", "Get stack traces for all threads")
+def get_thread_dump() -> dict:
+    frames = sys._current_frames()
+    result = {}
+    for tid, frame in frames.items():
+        stack = []
+        f = frame
+        while f:
+            stack.append({"file": f.f_code.co_filename, "line": f.f_lineno, "function": f.f_code.co_name})
+            f = f.f_back
+        # Find thread name
+        tname = "unknown"
+        for t in threading.enumerate():
+            if t.ident == tid:
+                tname = t.name
+                break
+        result[tname] = stack[:20]
+    return result
+
+
+@debug_tool("get_runtime_info", "Get Python runtime info: version, platform, uptime")
+def get_runtime_info() -> dict:
+    return {
+        "python_version": sys.version,
+        "platform": sys.platform,
+        "executable": sys.executable,
+        "pid": os.getpid(),
+        "argv": sys.argv,
+        "path_count": len(sys.path),
+    }
+
+
+@debug_tool("get_memory_allocations", "Get top memory allocations using tracemalloc (if enabled)")
+def get_memory_allocations() -> dict:
+    if not tracemalloc.is_tracing():
+        return {"error": "tracemalloc is not enabled. Call tracemalloc.start() to enable."}
+    snapshot = tracemalloc.take_snapshot()
+    top = snapshot.statistics("lineno")
+    return {
+        "top_allocations": [
+            {"file": str(s.traceback), "size_kb": round(s.size / 1024, 2), "count": s.count}
+            for s in top[:20]
+        ],
+    }
+
+
+@debug_tool("get_tracemalloc_status", "Check if tracemalloc is enabled and its configuration")
+def get_tracemalloc_status() -> dict:
+    return {
+        "enabled": tracemalloc.is_tracing(),
+        "traced_memory_mb": round(sum((c.size for c in tracemalloc.get_traced_memory())) / 1024 / 1024, 2)
+        if tracemalloc.is_tracing()
+        else 0,
+    }

debug_agent/inspectors/system.py

@@ -0,0 +1,79 @@
+"""System inspector: process info, CPU, disk, network."""
+
+from __future__ import annotations
+
+import os
+import platform
+import socket
+import sys
+import time
+
+from debug_agent.tool_registry import debug_tool, ToolParam
+
+
+@debug_tool("get_process_info", "Get process info: PID, CPU usage, memory limits, container detection")
+def get_process_info() -> dict:
+    try:
+        import resource
+        cpu_time = resource.getrusage(resource.RUSAGE_SELF)
+        cpu_user = cpu_time.ru_utime
+        cpu_sys = cpu_time.ru_stime
+    except ImportError:
+        cpu_user = cpu_sys = 0
+
+    # Container detection
+    in_container = os.path.exists("/.dockerenv") or os.path.exists("/run/.containerenv")
+    try:
+        with open("/proc/1/cgroup", "t") as f:
+            if "docker" in f.read() or "kubepods" in f.read():
+                in_container = True
+    except (FileNotFoundError, IOError):
+        pass
+
+    return {
+        "pid": os.getpid(),
+        "ppid": os.getppid(),
+        "cpu_time": {"user_seconds": round(cpu_user, 2), "system_seconds": round(cpu_sys, 2)},
+        "platform": platform.platform(),
+        "hostname": socket.gethostname(),
+        "in_container": in_container,
+    }
+
+
+@debug_tool("get_system_info", "Get system information: OS, CPU cores, load average")
+def get_system_info() -> dict:
+    return {
+        "os": platform.platform(),
+        "python_version": sys.version.split()[0],
+        "cpu_count": os.cpu_count(),
+        "load_average": _get_loadavg(),
+    }
+
+
+def _get_loadavg() -> dict | None:
+    try:
+        avg = os.getloadavg()
+        return {"1min": avg[0], "5min": avg[1], "15min": avg[2]}
+    except (AttributeError, OSError):
+        return None
+
+
+@debug_tool("get_disk_usage", "Get disk usage for current working directory")
+def get_disk_usage() -> dict:
+    stat = os.statvfs(".")
+    total = stat.f_blocks * stat.f_frsize
+    free = stat.f_bavail * stat.f_frsize
+    return {
+        "total_gb": round(total / 1024**3, 2),
+        "free_gb": round(free / 1024**3, 2),
+        "used_pct": round((1 - free / total) * 100, 1),
+    }
+
+
+@debug_tool("get_python_path", "Get Python module search paths")
+def get_python_path() -> dict:
+    return {
+        "paths": sys.path,
+        "count": len(sys.path),
+        "site_packages": [p for p in sys.path if "site-packages" in p],
+    }

debug_agent/inspectors/threads.py

@@ -0,0 +1,97 @@
+"""Thread inspector: live thread info, counts, and per-thread tracebacks."""
+
+from __future__ import annotations
+
+import sys
+import threading
+from typing import Any
+
+from debug_agent.tool_registry import debug_tool, ToolParam
+
+
+@debug_tool(
+    "get_thread_info",
+    "List all threads with name, daemon status, and alive status",
+)
+def get_thread_info() -> dict:
+    threads = threading.enumerate()
+    return {
+        "total_threads": len(threads),
+        "active_count": threading.active_count(),
+        "current_thread": threading.current_thread().name,
+        "threads": [
+            {
+                "name": t.name,
+                "ident": t.ident,
+                "daemon": t.daemon,
+                "alive": t.is_alive(),
+                "native_id": getattr(t, "native_id", None),
+            }
+            for t in threads
+        ],
+    }
+
+
+@debug_tool(
+    "get_thread_count",
+    "Get the number of active threads in the process",
+)
+def get_thread_count() -> dict:
+    return {
+        "active_count": threading.active_count(),
+        "enumerated_count": len(threading.enumerate()),
+        "main_thread_alive": threading.main_thread().is_alive(),
+    }
+
+
+@debug_tool(
+    "get_thread_traceback",
+    "Get the Python traceback (stack frames) for a specific thread by name or ID",
+)
+def get_thread_traceback(
+    thread_name: str = ToolParam("Thread name to look up (use 'MainThread' for main thread)", required=False),
+    thread_id: int = ToolParam("Thread identifier (OS-level TID) to look up", required=False),
+) -> dict:
+    frames = sys._current_frames()
+    thread_map = {t.ident: t for t in threading.enumerate()}
+
+    target_tid = None
+    matched_name = None
+
+    if thread_id is not None:
+        target_tid = thread_id
+        t = thread_map.get(thread_id)
+        matched_name = t.name if t else f"tid-{thread_id}"
+    elif thread_name:
+        for t in threading.enumerate():
+            if t.name == thread_name:
+                target_tid = t.ident
+                matched_name = t.name
+                break
+        if target_tid is None:
+            return {"error": f"No thread found with name '{thread_name}'"}
+    else:
+        # Default to current thread
+        target_tid = threading.current_thread().ident
+        matched_name = threading.current_thread().name
+
+    frame = frames.get(target_tid)
+    if not frame:
+        return {"error": f"No frame found for thread '{matched_name}' (tid={target_tid})"}
+
+    stack = []
+    f = frame
+    while f:
+        stack.append({
+            "file": f.f_code.co_filename,
+            "line": f.f_lineno,
+            "function": f.f_code.co_name,
+        })
+        f = f.f_back
+
+    return {
+        "thread_name": matched_name,
+        "thread_id": target_tid,
+        "stack_depth": len(stack),
+        "frames": stack[:30],
+    }

debug_agent/llm_client.py

@@ -0,0 +1,195 @@
+"""OpenAI-compatible LLM client with real streaming, retry, and token usage tracking."""
+
+from __future__ import annotations
+
+import json
+import logging
+import random
+import time
+from typing import Any, Callable
+
+import httpx
+
+from debug_agent.config import LLMConfig
+
+logger = logging.getLogger("debug_agent")
+
+
+class StreamHandler:
+    """Low-level stream callback interface (engine implements this)."""
+
+    def on_content(self, chunk: str): ...
+    def on_complete(self, tool_calls: list[dict], finish_reason: str | None, usage: dict | None): ...
+    def on_error(self, error: Exception): ...
+
+
+class LLMClient:
+    """OpenAI-compatible chat client with real streaming and retry."""
+
+    def __init__(self, config: LLMConfig):
+        self.cfg = config
+        self.client = httpx.Client(timeout=config.timeout_seconds)
+
+    # ==================== Non-Streaming ====================
+
+    def chat(self, messages: list[dict], tools: list[dict] | None = None) -> dict:
+        """Non-streaming chat completion with retry."""
+        body: dict = {
+            "model": self.cfg.model,
+            "messages": messages,
+            "temperature": 0,
+            "max_tokens": 1024,
+        }
+        if tools:
+            body["tools"] = tools
+
+        return self._post_with_retry("/chat/completions", body)
+
+    # ==================== Streaming ====================
+
+    def chat_stream_raw(self, messages: list[dict], tools: list[dict] | None, tool_choice: Any, handler: StreamHandler):
+        """Streaming chat completion with retry. Calls handler callbacks."""
+        body: dict = {
+            "model": self.cfg.model,
+            "messages": messages,
+            "temperature": self.cfg.temperature,
+            "max_tokens": self.cfg.max_tokens,
+            "stream": True,
+            "stream_options": {"include_usage": True},
+        }
+        if tools:
+            body["tools"] = tools
+        if tool_choice:
+            body["tool_choice"] = tool_choice
+
+        max_retries = self.cfg.max_retries
+        last_error = None
+
+        for attempt in range(max_retries + 1):
+            try:
+                self._stream_request("/chat/completions", body, handler)
+                return
+            except Exception as e:
+                last_error = e
+                if self._is_retriable(e) and attempt < max_retries:
+                    delay = self._calculate_delay(attempt)
+                    time.sleep(delay / 1000.0)
+                    continue
+                handler.on_error(e)
+                return
+
+        handler.on_error(Exception(f"Exhausted retries after {max_retries} attempts: {last_error}"))
+
+    # ==================== Stream Processing ====================
+
+    def _stream_request(self, path: str, body: dict, handler: StreamHandler):
+        url = f"{self.cfg.base_url}{path}"
+
+        with self.client.stream("POST", url, headers=self._headers(), json=body) as resp:
+            if resp.status_code >= 400:
+                error_body = resp.read().decode()
+                raise RetriableError(resp.status_code, f"HTTP {resp.status_code}: {error_body}")
+
+            tool_call_map: dict[int, dict] = {}
+            finish_reason = None
+            usage = None
+
+            for line in resp.iter_lines():
+                if not line or not line.startswith("data: "):
+                    continue
+                data_str = line[6:]
+                if data_str.strip() == "[DONE]":
+                    continue
+
+                try:
+                    chunk = json.loads(data_str)
+                except json.JSONDecodeError:
+                    continue
+
+                if chunk.get("usage") and chunk["usage"].get("prompt_tokens"):
+                    usage = chunk["usage"]
+
+                choices = chunk.get("choices", [])
+                if not choices:
+                    continue
+
+                choice = choices[0]
+                delta = choice.get("delta", {})
+
+                if delta.get("content"):
+                    handler.on_content(delta["content"])
+
+                if delta.get("tool_calls"):
+                    for tc in delta["tool_calls"]:
+                        idx = tc.get("index", 0)
+                        if idx not in tool_call_map:
+                            tool_call_map[idx] = {"id": "", "type": "function", "function": {"name": "", "arguments": ""}}
+                        entry = tool_call_map[idx]
+                        if tc.get("id"):
+                            entry["id"] = tc["id"]
+                        if tc.get("type"):
+                            entry["type"] = tc["type"]
+                        fn = tc.get("function", {})
+                        if fn.get("name"):
+                            entry["function"]["name"] += fn["name"]
+                        if fn.get("arguments") is not None:
+                            entry["function"]["arguments"] += fn["arguments"]
+
+                if choice.get("finish_reason"):
+                    finish_reason = choice["finish_reason"]
+
+            tool_calls = [tool_call_map[k] for k in sorted(tool_call_map.keys()) if tool_call_map[k]["function"]["name"]]
+            handler.on_complete(tool_calls, finish_reason, usage)
+
+    # ==================== Non-Streaming POST with retry ====================
+
+    def _post_with_retry(self, path: str, body: dict) -> dict:
+        max_retries = self.cfg.max_retries
+        last_error = None
+
+        for attempt in range(max_retries + 1):
+            try:
+                url = f"{self.cfg.base_url}{path}"
+                resp = self.client.post(url, headers=self._headers(), json=body)
+                if resp.status_code >= 400:
+                    raise RetriableError(resp.status_code, f"HTTP {resp.status_code}: {resp.text}")
+                return resp.json()
+            except Exception as e:
+                last_error = e
+                if self._is_retriable(e) and attempt < max_retries:
+                    delay = self._calculate_delay(attempt)
+                    time.sleep(delay / 1000.0)
+                    continue
+                raise
+
+        raise last_error
+
+    # ==================== Helpers ====================
+
+    def _headers(self) -> dict:
+        return {"Authorization": f"Bearer {self.cfg.api_key}", "Content-Type": "application/json"}
+
+    def _is_retriable(self, error: Exception) -> bool:
+        if isinstance(error, RetriableError):
+            return error.is_retriable()
+        return True  # Network errors
+
+    def _calculate_delay(self, attempt: int) -> int:
+        base = self.cfg.retry_base_delay_ms * (2 ** attempt)
+        jitter = random.randint(0, base // 2)
+        delay = base + jitter
+        return min(delay, self.cfg.retry_max_delay_ms)
+
+    def close(self):
+        self.client.close()
+
+
+class RetriableError(Exception):
+    """HTTP error that can be retried."""
+
+    def __init__(self, status_code: int, message: str):
+        super().__init__(message)
+        self.status_code = status_code
+
+    def is_retriable(self) -> bool:
+        return self.status_code in (429, 500, 502, 503, 504)

debug_agent/middleware.py

@@ -0,0 +1,199 @@
+"""Framework integration: FastAPI, Starlette, Flask middleware.
+
+SSE events (Spring-aligned):
+    content, tool_start, tool_result, done, error, context_compressed
+
+Endpoints:
+    GET  /agent           — Chat UI
+    POST /agent/api/chat  — SSE streaming chat
+    POST /agent/api/clear — Clear conversation
+    GET  /agent/api/health — Health check
+    GET  /agent/api/tools — List available tools
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from debug_agent.config import AgentConfig
+from debug_agent.engine import DebugEngine, ChatCallback
+from debug_agent.web.chat_page import render as render_chat_page
+
+
+# ==================== SSE Callback ====================
+
+class SseCallback(ChatCallback):
+    """Bridges engine callbacks to SSE event lines."""
+
+    def __init__(self):
+        self.events: list[tuple[str, str]] = []
+
+    def on_content(self, chunk: str):
+        self.events.append(("content", json.dumps(chunk)))
+
+    def on_tool_start(self, tool_name: str, args: str):
+        self.events.append(("tool_start", tool_name))
+
+    def on_tool_result(self, tool_name: str, result: str):
+        self.events.append(("tool_result", f"{tool_name}: {result}"))
+
+    def on_complete(self):
+        self.events.append(("done", ""))
+
+    def on_error(self, message: str):
+        self.events.append(("error", message))
+
+    def on_context_compressed(self, original_tokens: int, compressed_tokens: int, removed_rounds: int):
+        info = json.dumps({"originalTokens": original_tokens, "compressedTokens": compressed_tokens, "removedRounds": removed_rounds})
+        self.events.append(("context_compressed", info))
+
+
+# ==================== FastAPI ====================
+
+def create_fastapi_router(config: AgentConfig | None = None):
+    """Create a FastAPI APIRouter with all debug agent endpoints."""
+    from fastapi import APIRouter, Request
+    from fastapi.responses import HTMLResponse, StreamingResponse
+    from debug_agent import inspectors  # noqa: F401
+
+    cfg = config or AgentConfig.from_env()
+    engine = DebugEngine(cfg)
+    router = APIRouter(prefix=cfg.base_path, tags=["Debug Agent"])
+
+    @router.get("", response_class=HTMLResponse)
+    async def chat_page():
+        return render_chat_page(cfg.base_path)
+
+    @router.get("/")
+    async def chat_page_slash():
+        return render_chat_page(cfg.base_path)
+
+    @router.post("/api/chat")
+    async def chat(request: Request):
+        body = await request.json()
+        message = body.get("message", "")
+        session_id = body.get("sessionId", f"session-{id(request)}")
+
+        def event_stream():
+            cb = SseCallback()
+            engine.chat(message, session_id, cb)
+            for event_type, data in cb.events:
+                yield f"event: {event_type}\ndata: {data}\n\n"
+
+        return StreamingResponse(event_stream(), media_type="text/event-stream")
+
+    @router.post("/api/clear")
+    async def clear_conversation(request: Request):
+        body = await request.json()
+        session_id = body.get("sessionId", "")
+        if session_id:
+            engine.clear_session(session_id)
+        return {"status": "cleared"}
+
+    @router.get("/api/health")
+    async def health():
+        return {"status": "ok", "agent": "python-debug-agent"}
+
+    @router.get("/api/tools")
+    async def list_tools():
+        return {"tools": engine.tools.all_schemas()}
+
+    return router
+
+
+# ==================== Starlette ====================
+
+def create_starlette_app(config: AgentConfig | None = None):
+    from starlette.applications import Starlette
+    from starlette.responses import HTMLResponse, StreamingResponse, JSONResponse
+    from starlette.routing import Route
+    from debug_agent import inspectors  # noqa: F401
+
+    cfg = config or AgentConfig.from_env()
+    engine = DebugEngine(cfg)
+
+    async def chat_page(request):
+        return HTMLResponse(render_chat_page(cfg.base_path))
+
+    async def chat(request):
+        body = await request.json()
+        message = body.get("message", "")
+        session_id = body.get("sessionId", f"session-{id(request)}")
+
+        def event_stream():
+            cb = SseCallback()
+            engine.chat(message, session_id, cb)
+            for event_type, data in cb.events:
+                yield f"event: {event_type}\ndata: {data}\n\n"
+
+        return StreamingResponse(event_stream(), media_type="text/event-stream")
+
+    async def clear(request):
+        body = await request.json()
+        session_id = body.get("sessionId", "")
+        if session_id:
+            engine.clear_session(session_id)
+        return JSONResponse({"status": "cleared"})
+
+    async def health(request):
+        return JSONResponse({"status": "ok", "agent": "python-debug-agent"})
+
+    async def tools(request):
+        return JSONResponse({"tools": engine.tools.all_schemas()})
+
+    routes = [
+        Route("/", chat_page),
+        Route("/api/chat", chat, methods=["POST"]),
+        Route("/api/clear", clear, methods=["POST"]),
+        Route("/api/health", health),
+        Route("/api/tools", tools),
+    ]
+    return Starlette(routes=routes)
+
+
+# ==================== Flask ====================
+
+def create_flask_blueprint(config: AgentConfig | None = None):
+    from flask import Blueprint, Response, request, jsonify
+    from debug_agent import inspectors  # noqa: F401
+
+    cfg = config or AgentConfig.from_env()
+    engine = DebugEngine(cfg)
+
+    bp = Blueprint("debug_agent", __name__, url_prefix=cfg.base_path)
+
+    @bp.route("", methods=["GET"])
+    @bp.route("/", methods=["GET"])
+    def chat_page():
+        return render_chat_page(cfg.base_path)
+
+    @bp.route("/api/chat", methods=["POST"])
+    def chat():
+        message = request.json.get("message", "")
+        session_id = request.json.get("sessionId", f"session-{id(request)}")
+
+        def generate():
+            cb = SseCallback()
+            engine.chat(message, session_id, cb)
+            for event_type, data in cb.events:
+                yield f"event: {event_type}\ndata: {data}\n\n"
+
+        return Response(generate(), mimetype="text/event-stream")
+
+    @bp.route("/api/clear", methods=["POST"])
+    def clear():
+        session_id = request.json.get("sessionId", "")
+        if session_id:
+            engine.clear_session(session_id)
+        return jsonify({"status": "cleared"})
+
+    @bp.route("/api/health", methods=["GET"])
+    def health():
+        return jsonify({"status": "ok", "agent": "python-debug-agent"})
+
+    @bp.route("/api/tools", methods=["GET"])
+    def tools():
+        return jsonify({"tools": engine.tools.all_schemas()})
+
+    return bp