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

connectonion/cli/commands/init.py

@@ -37,7 +37,8 @@ from .project_cmd_lib import (
     interactive_menu,
     generate_custom_template,
     show_progress,
-    configure_env_for_provider
+    configure_env_for_provider,
+    get_docs_source,
 )
 
 console = Console()
@@ -332,30 +333,28 @@ def handle_init(ai: Optional[bool], key: Optional[str], template: Optional[str],
     co_dir = Path(current_dir) / ".co"
     co_dir.mkdir(exist_ok=True)
 
-    # Create docs directory and copy documentation (always overwrite for latest version)
+    # Create docs directory and copy ALL documentation (always overwrite for latest version)
     docs_dir = co_dir / "docs"
     if docs_dir.exists():
         shutil.rmtree(docs_dir)
     docs_dir.mkdir(exist_ok=True)
 
-    # Copy ConnectOnion documentation
-    cli_dir = Path(__file__).parent.parent
-
-    # Always copy the vibe coding doc for all templates - it's the master reference doc
-    master_doc = cli_dir / "docs" / "co-vibecoding-principles-docs-contexts-all-in-one.md"
-
-    if master_doc.exists():
-        # Copy to .co/docs/ (project metadata)
-        target_doc = docs_dir / "co-vibecoding-principles-docs-contexts-all-in-one.md"
-        shutil.copy2(master_doc, target_doc)
-        files_created.append(".co/docs/co-vibecoding-principles-docs-contexts-all-in-one.md")
+    # Get docs source (works in both dev and installed package)
+    docs_source = get_docs_source()
 
-        # ALSO copy to project root (always visible, easier to find)
-        root_doc = Path(current_dir) / "co-vibecoding-principles-docs-contexts-all-in-one.md"
-        shutil.copy2(master_doc, root_doc)
-        files_created.append("co-vibecoding-principles-docs-contexts-all-in-one.md")
+    # Copy ALL docs to .co/docs/
+    if docs_source.exists() and docs_source.is_dir():
+        for item in docs_source.iterdir():
+            if item.name.startswith('.') or item.name == 'archive':
+                continue
+            dest = docs_dir / item.name
+            if item.is_dir():
+                shutil.copytree(item, dest, dirs_exist_ok=True)
+            else:
+                shutil.copy2(item, dest)
+        files_created.append(".co/docs/ (full documentation)")
     else:
-        console.print(f"[yellow]⚠️  Warning: Vibe coding documentation not found at {master_doc}[/yellow]")
+        console.print(f"[yellow]⚠️  Warning: Documentation not found at {docs_source}[/yellow]")
 
     # Use global identity instead of generating project keys
     # NO PROJECT KEYS - we use global address/email
@@ -402,7 +401,6 @@ def handle_init(ai: Optional[bool], key: Optional[str], template: Optional[str],
 .co/cache/
 .co/logs/
 .co/history/
-co-vibecoding-principles-docs-contexts-all-in-one.md
 *.py[cod]
 __pycache__/
 todo.md
@@ -437,12 +435,11 @@ todo.md
 
         # Vibe Coding hint - clean formatting with proper spacing
         console.print("[bold yellow]💡 Vibe Coding:[/bold yellow] Use Claude/Cursor/Codex with")
-        console.print(f"   [cyan]co-vibecoding-principles-docs-contexts-all-in-one.md[/cyan]")
+        console.print(f"   [cyan].co/docs/[/cyan] for full documentation")
     else:
         # Vibe Coding hint for building from scratch
         console.print("[bold yellow]💡 Vibe Coding:[/bold yellow] Use Claude/Cursor/Codex with")
-        console.print(f"   [cyan]co-vibecoding-principles-docs-contexts-all-in-one.md[/cyan]")
-        console.print("   to build your agent")
+        console.print(f"   [cyan].co/docs/[/cyan] to build your agent")
 
     # Resources - clean format with arrows for better alignment
     console.print()

connectonion/cli/commands/project_cmd_lib.py

@@ -31,6 +31,20 @@ from ... import address
 console = Console()
 
 
+def get_docs_source() -> Path:
+    """Get the docs directory path - works in both dev and installed package."""
+    # After pip install: connectonion/docs/ exists (via force-include)
+    package_dir = Path(__file__).parent.parent.parent  # connectonion/cli/commands/ → connectonion/
+    docs_source = package_dir / "docs"
+
+    # Fallback for editable install: docs are at project root
+    if not docs_source.exists():
+        project_root = package_dir.parent
+        docs_source = project_root / "docs"
+
+    return docs_source
+
+
 
 
 def validate_project_name(name: str) -> Tuple[bool, str]:
@@ -822,6 +836,7 @@ __all__ = [
     'show_progress',
     'generate_custom_template',
     'generate_custom_template_with_name',
+    'get_docs_source',
 ]
 
 # All the handle_init and handle_create code has been moved to init.py and create.py

connectonion/cli/main.py

@@ -141,6 +141,17 @@ def browser(command: str = typer.Argument(..., help="Browser command")):
     handle_browser(command)
 
 
+@app.command()
+def ai(
+    port: int = typer.Option(8000, "--port", "-p", help="Port for web server"),
+    model: str = typer.Option("co/claude-opus-4-5", "--model", "-m", help="Model to use"),
+    max_iterations: int = typer.Option(20, "--max-iterations", "-i", help="Max iterations"),
+):
+    """Start AI coding agent web server."""
+    from .commands.ai_commands import handle_ai
+    handle_ai(port=port, model=model, max_iterations=max_iterations)
+
+
 @app.command()
 def copy(
     names: List[str] = typer.Argument(None, help="Tool or plugin names to copy"),

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)}")