connectonion 0.6.2__py3-none-any.whl → 0.6.4__py3-none-any.whl

connectonion/console.py

@@ -101,7 +101,8 @@ class Console:
         model: str = "",
         tools: Union[List[str], int] = 0,
         log_dir: Optional[str] = None,
-        llm: Any = None
+        llm: Any = None,
+        balance: Optional[float] = None
     ) -> None:
         """Print the ConnectOnion banner (Onion Stack style).
 
@@ -110,6 +111,7 @@ class Console:
         ●     ─────────────────────
               connectonion v0.5.1
               o4-mini · 3 tools
+              balance: $4.22
               .co/logs/ · .co/evals/
 
         Args:
@@ -118,6 +120,7 @@ class Console:
             tools: List of tool names or count of tools
             log_dir: Log directory path (e.g., ".co/")
             llm: LLM instance to check for free tier
+            balance: Optional account balance in USD (only for co/ models)
         """
         version = _get_version()
 
@@ -138,6 +141,11 @@ class Console:
             is_free_tier = type(llm).__name__ == "OpenOnionLLM"
         aaron_message = "credits on me, go build —aaron" if is_free_tier else None
 
+        # Fetch balance for OpenOnion managed keys if not already provided
+        # This adds ~200ms latency on startup but provides useful account info
+        if balance is None and is_free_tier and hasattr(llm, 'get_balance'):
+            balance = llm.get_balance()
+
         # Calculate separator length (at least as long as agent name, min 20)
         separator_len = max(len(agent_name), 20)
         separator = "─" * separator_len
@@ -154,6 +162,10 @@ class Console:
         if meta_line:
             lines.append(f"      [{DIM_COLOR}]{meta_line}[/{DIM_COLOR}]")
 
+        # Add balance if available (only for co/ models)
+        if balance is not None:
+            lines.append(f"      [{DIM_COLOR}]balance: ${balance:.2f}[/{DIM_COLOR}]")
+
         # Add log paths if logging is enabled
         if log_dir:
             lines.append(f"      [{DIM_COLOR}]{log_dir}logs/ · {log_dir}evals/[/{DIM_COLOR}]")
@@ -181,6 +193,8 @@ class Console:
             ]
             if meta_line:
                 plain_lines.append(f"      {meta_line}")
+            if balance is not None:
+                plain_lines.append(f"      balance: ${balance:.2f}")
             if log_dir:
                 plain_lines.append(f"      {log_dir}logs/ · {log_dir}evals/")
             if aaron_message:

connectonion/core/__init__.py

@@ -1,4 +1,13 @@
-"""Core agent execution engine.
+"""
+Purpose: Core agent execution engine - minimal components for running an agent
+LLM-Note:
+  Dependencies: imports from [agent.py, llm.py, events.py, tool_factory.py, tool_registry.py, tool_executor.py, usage.py] | imported by [connectonion/__init__.py, network/, debug/, useful_tools/] | tested indirectly via component tests
+  Data flow: bundles all core components → exports via __all__ → imported as `from connectonion.core import Agent, LLM, ...`
+  State/Effects: none (pure re-export module)
+  Integration: exposes core API: Agent (orchestrator), LLM (multi-provider abstraction), event decorators (lifecycle hooks), tool utilities (factory, registry, executor), usage tracking (TokenUsage, calculate_cost, get_context_limit)
+  Performance: no overhead (just imports)
+  Errors: import errors bubble from submodules
+Core agent execution engine.
 
 This module contains the minimal set of components needed to run an agent:
 - Agent: Main orchestrator

connectonion/core/agent.py

@@ -51,8 +51,8 @@ class Agent:
         # Current session context (runtime only)
         self.current_session = None
 
-        # Connection to client (None locally, injected by host() for WebSocket)
-        self.connection = None
+        # I/O to client (None locally, injected by host() for WebSocket)
+        self.io = None
 
         # Token usage tracking
         self.total_cost: float = 0.0  # Cumulative cost in USD
@@ -144,6 +144,27 @@ class Agent:
                 llm=self.llm
             )
 
+    def _next_trace_id(self) -> str:
+        """Generate unique trace entry ID (UUID)."""
+        import uuid
+        return str(uuid.uuid4())
+
+    def _record_trace(self, entry: dict) -> None:
+        """Record trace entry and stream to io if connected.
+
+        This is the single place where trace entries are recorded.
+        Ensures both local trace and remote streaming stay in sync.
+        """
+        if 'id' not in entry:
+            entry['id'] = self._next_trace_id()
+        if 'ts' not in entry:
+            entry['ts'] = time.time()
+
+        self.current_session['trace'].append(entry)
+
+        if self.io:
+            self.io.send(entry)
+
     def _invoke_events(self, event_type: str):
         """Invoke all event handlers for given type. Exceptions propagate (fail fast)."""
         for handler in self.events.get(event_type, []):
@@ -231,12 +252,12 @@ class Agent:
         self.current_session['user_prompt'] = prompt  # Store user prompt for xray/debugging
         turn_start = time.time()
 
-        # Add trace entry for this input
-        self.current_session['trace'].append({
+        # Record trace entry (also streams to io if connected)
+        self._record_trace({
             'type': 'user_input',
+            'content': prompt,
             'turn': self.current_session['turn'],
-            'prompt': prompt,  # Keep 'prompt' in trace for backward compatibility
-            'timestamp': turn_start
+            'ts': turn_start,
         })
 
         # Invoke after_user_input events
@@ -316,11 +337,11 @@ class Agent:
 
         # Return simplified result (omit internal fields)
         return {
-            "name": trace_entry["tool_name"],
-            "arguments": trace_entry["arguments"],
+            "name": trace_entry["name"],
+            "args": trace_entry.get("args", {}),
             "result": trace_entry["result"],
             "status": trace_entry["status"],
-            "timing": trace_entry["timing"]
+            "timing_ms": trace_entry.get("timing_ms")
         }
 
     def _create_initial_messages(self, prompt: str) -> List[Dict[str, Any]]:
@@ -338,9 +359,11 @@ class Agent:
             # Get LLM response
             response = self._get_llm_decision()
 
-            # If no tool calls, we're done
+            # If no tool calls, we're done - return the response
+            # Note: Don't send 'assistant' trace here - OUTPUT message will carry the result
             if not response.tool_calls:
-                return response.content if response.content else "Task completed."
+                content = response.content if response.content else "Task completed."
+                return content
 
             # Process tool calls
             self._execute_and_record_tools(response.tool_calls)
@@ -372,11 +395,10 @@ class Agent:
             self.last_usage = response.usage
             self.total_cost += response.usage.cost
 
-        # Add to trace
-        self.current_session['trace'].append({
+        # Record trace (also streams to io if connected)
+        self._record_trace({
             'type': 'llm_call',
             'model': self.llm.model,
-            'timestamp': start,
             'duration_ms': duration,
             'tool_calls_count': len(response.tool_calls) if response.tool_calls else 0,
             'iteration': self.current_session['iteration'],
@@ -447,7 +469,6 @@ class Agent:
             # Single prompt mode
             agent.auto_debug("Find information about Python")
         """
-        from .debug import AutoDebugger
+        from ..debug.auto_debug import AutoDebugger
         debugger = AutoDebugger(self)
         debugger.start_debug_session(prompt)
-

connectonion/core/exceptions.py

@@ -0,0 +1,74 @@
+"""
+ConnectOnion exceptions.
+
+Purpose: Custom exceptions for ConnectOnion framework with formatted, actionable error messages
+LLM-Note:
+  Dependencies: none | imported by [llm.py] | tested by [tests/test_billing_error_agent.py]
+  Data flow: OpenOnionLLM catches openai.APIStatusError(402) → transforms to InsufficientCreditsError → raises with formatted message
+  State/Effects: parses error detail from API response | formats beautiful error message with account, balance, cost, shortfall | preserves original error in __cause__
+  Integration: exposes InsufficientCreditsError exception class | raised by OpenOnionLLM when insufficient credits
+  Performance: lightweight exception creation | formats string message once on init
+  Errors: none (this module defines error types)
+"""
+
+
+class InsufficientCreditsError(Exception):
+    """
+    Raised when an LLM request fails due to insufficient ConnectOnion credits.
+
+    This indicates your ConnectOnion managed keys account needs more credits.
+    Join Discord to add credits or ask Aaron for free credits to get started.
+
+    Attributes:
+        balance (float): Current account balance in USD
+        required (float): Cost of the failed request in USD
+        shortfall (float): Additional credits needed in USD
+        address (str): Your ConnectOnion account address
+    """
+
+    def __init__(self, original_error):
+        """
+        Create InsufficientCreditsError from OpenAI API error.
+
+        Args:
+            original_error: The original openai.APIStatusError from the API
+        """
+        # Parse error details from API response
+        body = getattr(original_error, 'body', {}) or {}
+        detail = body.get('detail', {})
+
+        # Extract billing information
+        self.balance = detail.get('balance', 0)
+        self.required = detail.get('required', 0)
+        self.shortfall = detail.get('shortfall', 0)
+        self.address = detail.get('address', 'unknown')  # Server provides formatted address
+        self.public_key = detail.get('public_key', 'unknown')  # Full public key
+        self.original_message = detail.get('message', '')
+
+        # Create clear, beautiful error message
+        message = self._format_message()
+        super().__init__(message)
+
+        # Keep original error for debugging
+        self.__cause__ = original_error
+
+    def _format_message(self):
+        """Format a clear, actionable error message."""
+        return (
+            f"\n"
+            f"{'='*70}\n"
+            f"❌ Insufficient ConnectOnion Credits\n"
+            f"{'='*70}\n"
+            f"\n"
+            f"Account:     {self.address}\n"
+            f"Balance:     ${self.balance:.4f}\n"
+            f"Required:    ${self.required:.4f}\n"
+            f"Shortfall:   ${self.shortfall:.4f}\n"
+            f"\n"
+            f"💡 How to add credits:\n"
+            f"   • Join Discord: https://discord.gg/4xfD9k8AUF\n"
+            f"   • Ask Aaron for free credits to get started\n"
+            f"   • Check balance: Run 'co status' in terminal\n"
+            f"\n"
+            f"{'='*70}\n"
+        )

connectonion/core/llm.py

@@ -1,12 +1,12 @@
 """
 Purpose: Unified LLM provider abstraction with factory pattern for OpenAI, Anthropic, Gemini, and OpenOnion
 LLM-Note:
-  Dependencies: imports from [abc, typing, dataclasses, json, os, openai, anthropic, google.generativeai, requests, pathlib, toml, pydantic] | imported by [agent.py, llm_do.py, conftest.py] | tested by [tests/test_llm.py, tests/test_llm_do.py, tests/test_real_*.py]
+  Dependencies: imports from [abc, typing, dataclasses, json, os, base64, openai, anthropic, requests, pathlib, toml, pydantic, .usage, .exceptions] | imported by [agent.py, llm_do.py, conftest.py] | tested by [tests/test_llm.py, tests/test_llm_do.py, tests/test_real_*.py, tests/test_billing_error_agent.py]
   Data flow: Agent/llm_do calls create_llm(model, api_key) → factory routes to provider class → Provider.__init__() validates API key → Agent calls complete(messages, tools) OR structured_complete(messages, output_schema) → provider converts to native format → calls API → parses response → returns LLMResponse(content, tool_calls, raw_response) OR Pydantic model instance
   State/Effects: reads environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENONION_API_KEY) | reads ~/.connectonion/.co/config.toml for OpenOnion auth | makes HTTP requests to LLM APIs | no caching or persistence
   Integration: exposes create_llm(model, api_key), LLM abstract base class, OpenAILLM, AnthropicLLM, GeminiLLM, OpenOnionLLM, LLMResponse, ToolCall dataclasses | providers implement complete() and structured_complete() | OpenAI message format is lingua franca | tool calling uses OpenAI schema converted per-provider
   Performance: stateless (no caching) | synchronous (no streaming) | default max_tokens=8192 for Anthropic (required) | each call hits API
-  Errors: raises ValueError for missing API keys, unknown models, invalid parameters | provider-specific errors bubble up (openai.APIError, anthropic.APIError, etc.) | Pydantic ValidationError for invalid structured output
+  Errors: raises ValueError for missing API keys, unknown models, invalid parameters | provider-specific errors bubble up (openai.APIError, anthropic.APIError, etc.) | OpenOnionLLM transforms 402 errors to InsufficientCreditsError with formatted message and typed attributes | Pydantic ValidationError for invalid structured output
 
 Unified LLM provider abstraction layer for ConnectOnion framework.
 
@@ -146,6 +146,10 @@ from typing import List, Dict, Any, Optional, Type
 from dataclasses import dataclass
 import json
 import os
+import base64
+import logging
+
+logger = logging.getLogger(__name__)
 import openai
 import anthropic
 # google-genai not needed - using OpenAI-compatible endpoint instead
@@ -175,6 +179,7 @@ class ToolCall:
 
 # Import TokenUsage from usage module
 from .usage import TokenUsage, calculate_cost
+from .exceptions import InsufficientCreditsError
 
 
 @dataclass
@@ -670,13 +675,13 @@ class OpenOnionLLM(LLM):
 
         # Determine base URL for OpenAI-compatible endpoint
         if os.getenv("OPENONION_DEV") or os.getenv("ENVIRONMENT") == "development":
-            base_url = "http://localhost:8000/v1"
+            self.base_url = "http://localhost:8000/v1"
         else:
-            base_url = "https://oo.openonion.ai/v1"
+            self.base_url = "https://oo.openonion.ai/v1"
 
         # Use OpenAI client with OpenOnion endpoint
         self.client = openai.OpenAI(
-            base_url=base_url,
+            base_url=self.base_url,
             api_key=self.auth_token
         )
 
@@ -693,7 +698,17 @@ class OpenOnionLLM(LLM):
             api_kwargs["tools"] = [{"type": "function", "function": tool} for tool in tools]
             api_kwargs["tool_choice"] = "auto"
 
-        response = self.client.chat.completions.create(**api_kwargs)
+        try:
+            response = self.client.chat.completions.create(**api_kwargs)
+        except openai.APIStatusError as e:
+            if e.status_code == 402:
+                raise InsufficientCreditsError(e) from e
+            logger.error(f"APIStatusError: status={e.status_code}, message={e.message}, body={getattr(e, 'body', None)}")
+            raise
+        except Exception as e:
+            logger.error(f"LLM error: {type(e).__name__}: {e}")
+            raise
+
         message = response.choices[0].message
 
         # Parse tool calls if present
@@ -747,6 +762,39 @@ class OpenOnionLLM(LLM):
         )
         return completion.choices[0].message.parsed
 
+    def get_balance(self) -> Optional[float]:
+        """Fetch current account balance from OpenOnion API.
+
+        Makes a GET request to /api/v1/auth/me endpoint to retrieve the user's
+        current balance. This is called once at agent startup to display balance
+        in the banner.
+
+        Returns:
+            Balance in USD (e.g., 4.22 for $4.22), or None if request fails
+
+        Note:
+            - Fast timeout (2s) to avoid hanging on network issues
+            - Only called for co/ models (OpenOnion managed keys)
+            - Returns None on any error (network, auth, etc.)
+            - ~200ms typical latency, acceptable for startup
+        """
+        import requests
+
+        # Build auth endpoint URL (strip /v1 suffix)
+        auth_url = f"{self.base_url.rstrip('/v1')}/api/v1/auth/me"
+
+        response = requests.get(
+            auth_url,
+            headers={"Authorization": f"Bearer {self.auth_token}"},
+            timeout=2
+        )
+
+        if response.status_code == 200:
+            data = response.json()
+            return data.get("balance_usd")
+
+        return None
+
 
 def create_llm(model: str, api_key: Optional[str] = None, **kwargs) -> LLM:
     """Factory function to create the appropriate LLM based on model name.

connectonion/core/tool_executor.py

@@ -106,17 +106,14 @@ def execute_single_tool(
     # Log tool call before execution
     logger.log_tool_call(tool_name, tool_args)
 
-    # Create single trace entry
     trace_entry = {
-        "type": "tool_execution",
-        "tool_name": tool_name,
-        "arguments": tool_args,
-        "call_id": tool_id,
-        "timing": 0,
+        "type": "tool_result",
+        "tool_id": tool_id,  # LLM's tool call ID for client-side matching
+        "name": tool_name,
+        "args": tool_args,
         "status": "pending",
         "result": None,
-        "iteration": agent.current_session['iteration'],
-        "timestamp": time.time()
+        "timing_ms": 0,
     }
 
     # Check if tool exists
@@ -124,30 +121,31 @@ def execute_single_tool(
     if tool_func is None:
         error_msg = f"Tool '{tool_name}' not found"
 
-        # Update trace entry
         trace_entry["result"] = error_msg
         trace_entry["status"] = "not_found"
         trace_entry["error"] = error_msg
 
-        # Add trace entry to session (so on_error handlers can see it)
-        agent.current_session['trace'].append(trace_entry)
-
-        # Logger output
+        agent._record_trace(trace_entry)
         logger.print(f"[red]✗[/red] {error_msg}")
 
-        # Note: on_error event will fire in execute_and_record_tools after result message added
-
         return trace_entry
 
     # Check if tool has @xray decorator
     xray_enabled = is_xray_enabled(tool_func)
 
-    # Prepare context data for xray
     previous_tools = [
-        entry.get("tool_name") for entry in agent.current_session['trace']
-        if entry.get("type") == "tool_execution"
+        entry.get("name") for entry in agent.current_session['trace']
+        if entry.get("type") == "tool_result"
     ]
 
+    # Record tool_call event BEFORE execution (for real-time UI updates)
+    agent._record_trace({
+        "type": "tool_call",
+        "tool_id": tool_id,  # LLM's tool call ID
+        "name": tool_name,
+        "args": tool_args,
+    })
+
     # Inject xray context before tool execution
     inject_xray_context(
         agent=agent,
@@ -177,19 +175,19 @@ def execute_single_tool(
 
         # Execute the tool with timing (restart timer AFTER events for accurate tool timing)
         tool_start = time.time()
+
+        # Inject agent for ask_user tool (YAGNI - only generalize when needed)
+        if tool_name == 'ask_user':
+            tool_args['agent'] = agent
+
         result = tool_func(**tool_args)
         tool_duration = (time.time() - tool_start) * 1000  # milliseconds
 
-        # Update trace entry
-        trace_entry["timing"] = tool_duration
+        trace_entry["timing_ms"] = tool_duration
         trace_entry["result"] = str(result)
         trace_entry["status"] = "success"
 
-        # Add trace entry to session BEFORE auto-trace
-        # (so it shows up in xray.trace() output)
-        agent.current_session['trace'].append(trace_entry)
-
-        # Logger output - result on separate line
+        agent._record_trace(trace_entry)
         logger.log_tool_result(str(result), tool_duration)
 
         # Auto-print Rich table if @xray enabled
@@ -208,19 +206,22 @@ def execute_single_tool(
         # Calculate timing from initial start (includes before_tool if it succeeded)
         tool_duration = (time.time() - tool_start) * 1000
 
-        # Update trace entry
-        trace_entry["timing"] = tool_duration
+        trace_entry["timing_ms"] = tool_duration
         trace_entry["status"] = "error"
         trace_entry["error"] = str(e)
         trace_entry["error_type"] = type(e).__name__
 
-        error_msg = f"Error executing tool: {str(e)}"
+        # Always include schema info so LLM knows how to fix the call
+        schema = getattr(tool_func, 'get_parameters_schema', lambda: {})()
+        required = schema.get('required', [])
+        properties = list(schema.get('properties', {}).keys())
+
+        error_msg = f"Error: {str(e)}"
+        error_msg += f"\n\nTool '{tool_name}' schema: required={required}, all_params={properties}, you_provided={list(tool_args.keys())}"
         trace_entry["result"] = error_msg
 
-        # Add error trace entry to session (so on_error handlers can see it)
-        agent.current_session['trace'].append(trace_entry)
+        agent._record_trace(trace_entry)
 
-        # Logger output
         time_str = f"{tool_duration/1000:.4f}s" if tool_duration < 100 else f"{tool_duration/1000:.1f}s"
         logger.print(f"[red]✗[/red] Error ({time_str}): {str(e)}")
 

connectonion/core/tool_factory.py

@@ -1,28 +1,63 @@
 """
 Purpose: Convert Python functions and class methods into agent-compatible tool schemas
 LLM-Note:
-  Dependencies: imports from [inspect, functools, typing] | imported by [agent.py, __init__.py] | tested by [tests/test_tool_factory.py]
-  Data flow: receives func: Callable → inspects signature with inspect.signature() → extracts type hints with get_type_hints() → maps Python types to JSON Schema via TYPE_MAP → creates tool with .name, .description, .to_function_schema(), .run() attributes → returns wrapped Callable
+  Dependencies: imports from [inspect, functools, typing] | imported by [agent.py, __init__.py] | tested by [tests/unit/test_tool_factory.py]
+  Data flow: receives func: Callable → inspects signature with inspect.signature() → extracts type hints with get_type_hints() → maps Python types to JSON Schema via get_json_schema_type() → creates tool with .name, .description, .to_function_schema(), .run() attributes → returns wrapped Callable
   State/Effects: no side effects | pure function transformations | preserves @xray and @replay decorator flags via hasattr checks | creates wrapper functions for bound methods to maintain self reference
-  Integration: exposes create_tool_from_function(func), extract_methods_from_instance(obj), is_class_instance(obj) | used by Agent.__init__ to auto-convert tools | supports both standalone functions and bound methods | skips private methods (starting with _)
+  Integration: exposes get_json_schema_type(param_type), create_tool_from_function(func), extract_methods_from_instance(obj), is_class_instance(obj) | used by Agent.__init__ to auto-convert tools | supports both standalone functions and bound methods | skips private methods (starting with _)
   Performance: uses inspect module (relatively fast) | TYPE_MAP provides O(1) type lookups | caches nothing (recreates on each call)
   Errors: skips methods without type annotations | skips methods without return type hint | handles inspection failures gracefully | wraps functions with functools.wraps to preserve metadata
+  Type Support: handles Optional[X], List[X], Dict[K,V] via get_json_schema_type() | extracts inner types from Union/Optional | generates proper JSON Schema with "items" for arrays
 """
 
 import inspect
 import functools
-from typing import Callable, Dict, Any, get_type_hints, List
+from typing import Callable, Dict, Any, get_type_hints, List, get_origin, get_args, Union
 
 # Map Python types to JSON Schema types
 TYPE_MAP = {
     str: "string",
-    int: "integer", 
+    int: "integer",
     float: "number",
     bool: "boolean",
     list: "array",
     dict: "object",
 }
 
+
+def get_json_schema_type(param_type) -> dict:
+    """Convert a Python type hint to JSON Schema type, handling generics."""
+    origin = get_origin(param_type)
+
+    # Handle Optional[X] which is Union[X, None]
+    if origin is Union:
+        args = get_args(param_type)
+        # Filter out NoneType to get the actual type
+        non_none_args = [a for a in args if a is not type(None)]
+        if non_none_args:
+            return get_json_schema_type(non_none_args[0])
+        return {"type": "string"}
+
+    # Handle List[X]
+    if origin is list:
+        args = get_args(param_type)
+        schema = {"type": "array"}
+        if args:
+            item_schema = get_json_schema_type(args[0])
+            schema["items"] = item_schema
+        return schema
+
+    # Handle Dict[K, V]
+    if origin is dict:
+        return {"type": "object"}
+
+    # Handle basic types
+    if param_type in TYPE_MAP:
+        return {"type": TYPE_MAP[param_type]}
+
+    # Default to string
+    return {"type": "string"}
+
 def create_tool_from_function(func: Callable) -> Callable:
     """
     Converts a Python function into a tool that is compatible with the Agent,
@@ -42,16 +77,18 @@ def create_tool_from_function(func: Callable) -> Callable:
 
     for param in sig.parameters.values():
         param_name = param.name
-        
+
         # Skip 'self' parameter for bound methods
         if param_name == 'self':
             continue
-            
+
+        # Skip 'agent' parameter - injected by tool_executor
+        if param_name == 'agent':
+            continue
+
         # Use 'str' as a fallback if no type hint is available
         param_type = type_hints.get(param_name, str)
-        schema_type = TYPE_MAP.get(param_type, "string")
-        
-        properties[param_name] = {"type": schema_type}
+        properties[param_name] = get_json_schema_type(param_type)
 
         if param.default is inspect.Parameter.empty:
             required.append(param_name)

connectonion/debug/__init__.py

@@ -1,4 +1,13 @@
-"""Debug tools for agent development and troubleshooting.
+"""
+Purpose: Debug tools package re-exporting xray, decorators, auto_debug, runtime_inspector, debug_explainer
+LLM-Note:
+  Dependencies: imports from [xray.py, decorators.py, auto_debug.py (lazy), auto_debug_exception.py, runtime_inspector/ (lazy), debug_explainer/ (lazy)] | imported by [__init__.py main package, user code] | tested via submodule tests
+  Data flow: pure re-export module with lazy loading for circular dependency avoidance
+  State/Effects: no state
+  Integration: exposes xray (decorator), replay/xray_replay (decorators), AutoDebugger/AutoDebugUI (lazy), auto_debug_exception, RuntimeInspector (lazy), explain_tool_choice (lazy) | lazy imports via __getattr__ to avoid circular deps with agent.py
+  Performance: lazy loading delays imports until accessed
+  Errors: none
+Debug tools for agent development and troubleshooting.
 
 This module contains:
 - xray: Runtime context injection for tool inspection

connectonion/debug/debug_explainer/__init__.py

@@ -1,4 +1,13 @@
-"""Debug explainer - AI-powered explanation of tool choices during debugging.
+"""
+Purpose: Debug explainer module for AI-powered tool choice explanations
+LLM-Note:
+  Dependencies: imports from [explain_agent.py, explain_context.py] | imported by [debug/__init__.py, user code] | tested by [tests/debug/test_debug_explainer.py]
+  Data flow: re-exports explain_tool_choice function and RuntimeContext dataclass
+  State/Effects: no state
+  Integration: exposes explain_tool_choice(agent, tool_name, tool_args) → str, RuntimeContext dataclass | used for post-hoc analysis of agent decisions
+  Performance: trivial
+  Errors: none
+Debug explainer - AI-powered explanation of tool choices during debugging.
 
 Provides runtime investigation capabilities to explain why an agent
 chose to call a specific tool with specific arguments.

connectonion/debug/execution_analyzer/__init__.py

@@ -1,4 +1,13 @@
-"""Execution analyzer - Post-execution analysis and improvement suggestions.
+"""
+Purpose: Execution analyzer module for post-run analysis and improvement suggestions
+LLM-Note:
+  Dependencies: imports from [execution_analysis.py] | imported by [debug/__init__.py, user code] | tested by [tests/debug/test_execution_analyzer.py]
+  Data flow: re-exports analyze_execution function and ExecutionAnalysis model
+  State/Effects: no state
+  Integration: exposes analyze_execution(session_file) → ExecutionAnalysis with suggestions for prompt improvements | used after agent runs for optimization
+  Performance: trivial
+  Errors: none
+Execution analyzer - Post-execution analysis and improvement suggestions.
 
 Analyzes completed agent runs and provides suggestions for improving
 system prompts and agent behavior.

connectonion/debug/execution_analyzer/execution_analysis.py

@@ -49,16 +49,19 @@ def analyze_execution(
         Structured analysis with improvement suggestions
     """
     # Build execution summary
+    # Filter for tool_result entries (the current trace format)
     tools_called = [
         entry for entry in execution_trace
-        if entry.get('type') == 'tool_execution'
+        if entry.get('type') == 'tool_result'
     ]
 
     tools_summary = []
     for entry in tools_called:
         status = "✓" if entry.get('status') == 'success' else "✗"
+        # Use 'name' field (current format) with fallback to 'tool_name' (legacy)
+        tool_name = entry.get('name') or entry.get('tool_name')
         tools_summary.append(
-            f"{status} {entry.get('tool_name')}({entry.get('args')}) → {entry.get('result')}"
+            f"{status} {tool_name}({entry.get('args')}) → {entry.get('result')}"
         )
 
     # Create analysis input

connectonion/debug/runtime_inspector/__init__.py

@@ -1,4 +1,13 @@
-"""Runtime inspector for AI-powered crash debugging.
+"""
+Purpose: Runtime inspector module for AI-powered crash debugging with experiment validation
+LLM-Note:
+  Dependencies: imports from [agent.py, runtime_inspector.py] | imported by [debug/__init__.py, user code] | tested by [tests/debug/test_runtime_inspector.py]
+  Data flow: re-exports create_debug_agent factory and RuntimeInspector class
+  State/Effects: no state
+  Integration: exposes create_debug_agent() → Agent, RuntimeInspector class for capturing crash context and experimenting with fixes | used for interactive crash debugging
+  Performance: trivial
+  Errors: none
+Runtime inspector for AI-powered crash debugging.
 
 Provides RuntimeInspector class and factory function to create debug agents
 that can experiment, test, and validate fixes using actual crashed program data.