connectonion 0.5.8__py3-none-any.whl

connectonion/asgi.py

@@ -0,0 +1,287 @@
+"""Raw ASGI utilities for HTTP/WebSocket handling.
+
+This module contains the protocol-level code for handling HTTP and WebSocket
+requests. Separated from host.py for better testing and smaller file size.
+
+Design decision: Raw ASGI instead of Starlette/FastAPI for full protocol control.
+See: docs/design-decisions/022-raw-asgi-implementation.md
+"""
+import hmac
+import json
+import os
+from pathlib import Path
+
+from pydantic import BaseModel
+
+
+def _json_default(obj):
+    """Handle non-serializable objects like Pydantic models.
+
+    This enables native JSON serialization for Pydantic BaseModel instances
+    nested in API response dicts, following FastAPI's pattern.
+    """
+    if isinstance(obj, BaseModel):
+        return obj.model_dump()
+    raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
+
+
+async def read_body(receive) -> bytes:
+    """Read complete request body from ASGI receive."""
+    body = b""
+    while True:
+        m = await receive()
+        body += m.get("body", b"")
+        if not m.get("more_body"):
+            break
+    return body
+
+
+# CORS headers for cross-origin requests (e.g., frontend at o.openonion.ai
+# calling deployed agents at *.agents.openonion.ai)
+CORS_HEADERS = [
+    [b"access-control-allow-origin", b"*"],
+    [b"access-control-allow-methods", b"GET, POST, OPTIONS"],
+    [b"access-control-allow-headers", b"authorization, content-type"],
+]
+
+
+async def send_json(send, data: dict, status: int = 200):
+    """Send JSON response via ASGI send."""
+    body = json.dumps(data, default=_json_default).encode()
+    headers = [[b"content-type", b"application/json"]] + CORS_HEADERS
+    await send({"type": "http.response.start", "status": status, "headers": headers})
+    await send({"type": "http.response.body", "body": body})
+
+
+async def send_html(send, html: bytes, status: int = 200):
+    """Send HTML response via ASGI send."""
+    await send({
+        "type": "http.response.start",
+        "status": status,
+        "headers": [[b"content-type", b"text/html; charset=utf-8"]],
+    })
+    await send({"type": "http.response.body", "body": html})
+
+
+async def send_text(send, text: str, status: int = 200):
+    """Send plain text response via ASGI send."""
+    headers = [[b"content-type", b"text/plain; charset=utf-8"]] + CORS_HEADERS
+    await send({"type": "http.response.start", "status": status, "headers": headers})
+    await send({"type": "http.response.body", "body": text.encode()})
+
+
+async def handle_http(
+    scope,
+    receive,
+    send,
+    *,
+    handlers: dict,
+    storage,
+    trust: str,
+    result_ttl: int,
+    start_time: float,
+    blacklist: list | None = None,
+    whitelist: list | None = None,
+):
+    """Route HTTP requests to handlers.
+
+    Args:
+        scope: ASGI scope dict (method, path, headers, etc.)
+        receive: ASGI receive callable
+        send: ASGI send callable
+        handlers: Dict of handler functions (input, session, sessions, health, info, auth)
+        storage: SessionStorage instance
+        trust: Trust level (open/careful/strict)
+        result_ttl: How long to keep results in seconds
+        start_time: Server start time
+        blacklist: Blocked identities
+        whitelist: Allowed identities
+    """
+    method, path = scope["method"], scope["path"]
+
+    # Handle CORS preflight requests
+    if method == "OPTIONS":
+        headers = CORS_HEADERS + [[b"content-length", b"0"]]
+        await send({"type": "http.response.start", "status": 204, "headers": headers})
+        await send({"type": "http.response.body", "body": b""})
+        return
+
+    # Admin endpoints require API key auth
+    if path.startswith("/admin"):
+        headers = dict(scope.get("headers", []))
+        auth = headers.get(b"authorization", b"").decode()
+        expected = os.environ.get("OPENONION_API_KEY", "")
+        if not expected or not auth.startswith("Bearer ") or not hmac.compare_digest(auth[7:], expected):
+            await send_json(send, {"error": "unauthorized"}, 401)
+            return
+
+        if method == "GET" and path == "/admin/logs":
+            result = handlers["admin_logs"]()
+            if "error" in result:
+                await send_json(send, result, 404)
+            else:
+                await send_text(send, result["content"])
+            return
+
+        if method == "GET" and path == "/admin/sessions":
+            await send_json(send, handlers["admin_sessions"]())
+            return
+
+        await send_json(send, {"error": "not found"}, 404)
+        return
+
+    if method == "POST" and path == "/input":
+        body = await read_body(receive)
+        try:
+            data = json.loads(body) if body else {}
+        except json.JSONDecodeError:
+            await send_json(send, {"error": "Invalid JSON"}, 400)
+            return
+
+        prompt, identity, sig_valid, err = handlers["auth"](
+            data, trust, blacklist=blacklist, whitelist=whitelist
+        )
+        if err:
+            status = 401 if err.startswith("unauthorized") else 403 if err.startswith("forbidden") else 400
+            await send_json(send, {"error": err}, status)
+            return
+
+        # Extract session for conversation continuation
+        session = data.get("session")
+        result = handlers["input"](storage, prompt, result_ttl, session)
+        await send_json(send, result)
+
+    elif method == "GET" and path.startswith("/sessions/"):
+        result = handlers["session"](storage, path[10:])
+        await send_json(send, result or {"error": "not found"}, 404 if not result else 200)
+
+    elif method == "GET" and path == "/sessions":
+        await send_json(send, handlers["sessions"](storage))
+
+    elif method == "GET" and path == "/health":
+        await send_json(send, handlers["health"](start_time))
+
+    elif method == "GET" and path == "/info":
+        await send_json(send, handlers["info"](trust))
+
+    elif method == "GET" and path == "/docs":
+        # Serve static docs page
+        try:
+            base = Path(__file__).resolve().parent
+            html_path = base / "static" / "docs.html"
+            html = html_path.read_bytes()
+        except Exception:
+            html = b"<html><body><h1>ConnectOnion Docs</h1><p>Docs not found.</p></body></html>"
+        await send_html(send, html)
+
+    else:
+        await send_json(send, {"error": "not found"}, 404)
+
+
+async def handle_websocket(
+    scope,
+    receive,
+    send,
+    *,
+    handlers: dict,
+    trust: str,
+    blacklist: list | None = None,
+    whitelist: list | None = None,
+):
+    """Handle WebSocket connections at /ws.
+
+    Args:
+        scope: ASGI scope dict
+        receive: ASGI receive callable
+        send: ASGI send callable
+        handlers: Dict with 'ws_input' and 'auth' handlers
+        trust: Trust level
+        blacklist: Blocked identities
+        whitelist: Allowed identities
+    """
+    if scope["path"] != "/ws":
+        await send({"type": "websocket.close", "code": 4004})
+        return
+
+    await send({"type": "websocket.accept"})
+
+    while True:
+        msg = await receive()
+        if msg["type"] == "websocket.disconnect":
+            break
+        if msg["type"] == "websocket.receive":
+            try:
+                data = json.loads(msg.get("text", "{}"))
+            except json.JSONDecodeError:
+                await send({"type": "websocket.send",
+                           "text": json.dumps({"type": "ERROR", "message": "Invalid JSON"})})
+                continue
+
+            if data.get("type") == "INPUT":
+                prompt, identity, sig_valid, err = handlers["auth"](
+                    data, trust, blacklist=blacklist, whitelist=whitelist
+                )
+                if err:
+                    await send({"type": "websocket.send",
+                               "text": json.dumps({"type": "ERROR", "message": err})})
+                    continue
+                if not prompt:
+                    await send({"type": "websocket.send",
+                               "text": json.dumps({"type": "ERROR", "message": "prompt required"})})
+                    continue
+                result = handlers["ws_input"](prompt)
+                await send({"type": "websocket.send",
+                           "text": json.dumps({"type": "OUTPUT", "result": result})})
+
+
+def create_app(
+    *,
+    handlers: dict,
+    storage,
+    trust: str = "careful",
+    result_ttl: int = 86400,
+    blacklist: list | None = None,
+    whitelist: list | None = None,
+):
+    """Create ASGI application.
+
+    Args:
+        handlers: Dict of handler functions
+        storage: SessionStorage instance
+        trust: Trust level (open/careful/strict)
+        result_ttl: How long to keep results in seconds
+        blacklist: Blocked identities
+        whitelist: Allowed identities
+
+    Returns:
+        ASGI application callable
+    """
+    import time
+    start_time = time.time()
+
+    async def app(scope, receive, send):
+        if scope["type"] == "http":
+            await handle_http(
+                scope,
+                receive,
+                send,
+                handlers=handlers,
+                storage=storage,
+                trust=trust,
+                result_ttl=result_ttl,
+                start_time=start_time,
+                blacklist=blacklist,
+                whitelist=whitelist,
+            )
+        elif scope["type"] == "websocket":
+            await handle_websocket(
+                scope,
+                receive,
+                send,
+                handlers=handlers,
+                trust=trust,
+                blacklist=blacklist,
+                whitelist=whitelist,
+            )
+
+    return app

connectonion/auto_debug_exception.py

@@ -0,0 +1,181 @@
+"""
+Purpose: Automatically analyze uncaught Python exceptions using AI with runtime frame inspection
+LLM-Note:
+  Dependencies: imports from [sys, traceback, os, dotenv, console.py, debug_agent/__init__.py] | imported by [__init__.py] | tested by [tests/test_auto_debug_exception.py]
+  Data flow: auto_debug_exception() → installs sys.excepthook → on exception: calls original_hook (shows traceback) → finds relevant frame (last user code, not library) → extracts frame.f_locals → creates debug_agent with actual frame and traceback → sends prompt with exception details → agent uses runtime inspection tools (explore_namespace, execute_in_frame, inspect_object, validate_assumption, test_fix) → displays AI analysis
+  State/Effects: modifies sys.excepthook globally | loads .env for CONNECTONION_AUTO_DEBUG | creates debug Agent instances on exceptions | calls console.print() to display analysis | does not prevent exception from terminating program
+  Integration: exposes auto_debug_exception(model) | checks CONNECTONION_AUTO_DEBUG=false env to disable | creates debug_agent with frame, exception_traceback, model parameters | prompt guides AI to use runtime inspection tools
+  Performance: only activates on exceptions (zero overhead in normal execution) | debug agent creates LLM instance per exception | runtime inspection executes code in crashed frame
+  Errors: wraps AI analysis in try/except to avoid cascading failures | shows "AI analysis failed" message if agent crashes | handles missing frames gracefully | skips analysis if no relevant frame found
+"""
+
+import sys
+import traceback
+import os
+
+
+def auto_debug_exception(model: str = "o4-mini"):
+    """Enable AI debugging for uncaught exceptions ONLY.
+
+    Debugs crashes, raised exceptions, and failed assertions. Does NOT debug
+    logic errors, wrong outputs, or performance issues unless you convert them
+    to exceptions using raise/assert.
+
+    What gets debugged:
+        ✅ Crashes: KeyError, TypeError, ZeroDivisionError, etc.
+        ✅ Raised exceptions: raise ValueError("invalid input")
+        ✅ Failed assertions: assert x > 0, "must be positive"
+        ❌ Logic errors that don't raise exceptions
+
+    Args:
+        model: AI model to use (default: o4-mini for speed)
+
+    Example:
+        from connectonion import auto_debug_exception
+
+        # Enable AI debugging for exceptions
+        auto_debug_exception()
+
+        # Any uncaught exception gets AI analysis with runtime data
+        data = {"items": []}
+        avg = sum(data["items"]) / len(data["items"])  # ZeroDivisionError!
+
+    Environment:
+        Set CONNECTONION_AUTO_DEBUG=false to disable even when called.
+    """
+    # Check if explicitly disabled via environment
+    if os.environ.get('CONNECTONION_AUTO_DEBUG', '').lower() == 'false':
+        return  # User explicitly disabled it
+
+    # Save original hook for use in our handler
+    original_hook = sys.excepthook
+
+    def handle_exception(exc_type, exc_value, exception_traceback):
+        """Handle an uncaught exception with AI runtime analysis."""
+        # First call original hook to show normal traceback
+        # (This ensures compatibility with other tools)
+        original_hook(exc_type, exc_value, exception_traceback)
+
+        # Then add our AI analysis
+        from .console import Console
+        console = Console()
+
+        # Find the most relevant frame (last user code, not library)
+        relevant_frame_info = None
+        actual_frame = None
+        actual_traceback = None
+        current_traceback = exception_traceback
+
+        while current_traceback:
+            frame = current_traceback.tb_frame
+            filename = frame.f_code.co_filename
+
+            # Skip system/library files
+            if not filename.startswith('<') and 'site-packages' not in filename:
+                relevant_frame_info = {
+                    'file': filename,
+                    'line': current_traceback.tb_lineno,
+                    'function': frame.f_code.co_name,
+                    'locals': {}
+                }
+                # Keep the actual frame and traceback for runtime inspection
+                actual_frame = frame
+                actual_traceback = exception_traceback  # Keep the original traceback
+
+                # Capture some local variables (simple types only) for display
+                for name, value in frame.f_locals.items():
+                    # Skip private/internal variables
+                    if name.startswith('_'):
+                        continue
+
+                    # Only capture simple types to avoid huge dumps
+                    if isinstance(value, (str, int, float, bool, type(None))):
+                        relevant_frame_info['locals'][name] = value
+                    elif isinstance(value, (list, dict, tuple)):
+                        # Just show type and size
+                        relevant_frame_info['locals'][name] = f"{type(value).__name__}({len(value)})"
+                    else:
+                        # Just show type
+                        relevant_frame_info['locals'][name] = type(value).__name__
+
+            current_traceback = current_traceback.tb_next
+
+        # If no user code found, use the last frame
+        if not relevant_frame_info and exception_traceback:
+            last_traceback = exception_traceback
+            while last_traceback.tb_next:
+                last_traceback = last_traceback.tb_next
+
+            frame = last_traceback.tb_frame
+            relevant_frame_info = {
+                'file': frame.f_code.co_filename,
+                'line': last_traceback.tb_lineno,
+                'function': frame.f_code.co_name,
+                'locals': {}
+            }
+            actual_frame = frame
+            actual_traceback = exception_traceback
+
+        # Skip if no relevant frame
+        if not relevant_frame_info:
+            return
+
+        # Run AI analysis with runtime inspection
+        console.print("\n[yellow]🤖 Analyzing with AI runtime inspection...[/yellow]")
+
+        try:
+            # Use debug agent with runtime inspection tools
+            from .debug_agent import create_debug_agent
+
+            # Pass the actual frame and traceback for runtime inspection!
+            agent = create_debug_agent(
+                frame=actual_frame,
+                exception_traceback=actual_traceback,
+                model=model
+            )
+
+            # Build prompt that guides tool usage
+            prompt = f"""Debug this Python exception using your runtime inspection tools:
+
+Exception: {exc_type.__name__}: {exc_value}
+File: {relevant_frame_info['file']}
+Line: {relevant_frame_info['line']}
+Function: {relevant_frame_info['function']}()
+
+You have LIVE ACCESS to the crashed program's state! Use your tools to investigate:
+
+1. First explore what variables are available:
+   - Use explore_namespace() to see all variables
+
+2. Then investigate the specific error:
+   - Use execute_in_frame() to check values and types
+   - Use inspect_object() to examine data structures
+   - Use validate_assumption() to test your hypotheses
+
+3. Test potential fixes:
+   - Use test_fix() to verify solutions work with the actual data
+   - Use try_alternative() to explore different approaches
+
+4. Finally, provide your analysis:
+   - **What I found**: Show the actual runtime values you discovered
+   - **Why it failed**: Explain with evidence from the runtime state
+   - **Verified fix**: A solution you tested that works"""
+
+            # Get AI analysis
+            result = agent.input(prompt)
+
+            # Display the analysis
+            console.print("\n[cyan bold]💡 AI Runtime Debug Analysis:[/cyan bold]")
+            console.print(result)
+
+        except Exception as e:
+            # If AI analysis fails, show a simple message
+            console.print(f"[dim]AI analysis failed: {e}[/dim]")
+
+    # Install our exception hook
+    sys.excepthook = handle_exception
+
+    # Simple confirmation
+    from .console import Console
+    console = Console()
+    console.print(f"[green]✅ Exception debugging enabled[/green] - AI will analyze uncaught exceptions with runtime inspection")

connectonion/cli/__init__.py

@@ -0,0 +1,3 @@
+"""ConnectOnion CLI module."""
+
+__version__ = "0.0.1b5"

connectonion/cli/browser_agent/__init__.py

@@ -0,0 +1,5 @@
+"""Browser agent module for ConnectOnion CLI."""
+
+from .browser import execute_browser_command, BrowserAutomation
+
+__all__ = ['execute_browser_command', 'BrowserAutomation']