feat: improve developer experience — tooltips, validation, prescriptive hints, keyboard shortcuts

Frontend DX:
- Add tooltips explaining technical terms (replay_value, drift, policy_shift, ranking factors)
- Convert LLMViewer and MultiAgentCoordinationPanel empty states to EmptyState component
- Add keyboard shortcuts: Ctrl+1/2/3 for tabs, Ctrl+K or / for search focus
- Add skeleton loading animation to CostPanel

SDK DX:
- Add config validation (endpoint URL, max_payload_kb range, sample_rate range)
- Expand boolean parsing to handle 1/0, yes/no, on/off (case-insensitive)
- Add actionable HTTP error messages (401/403/404/429) in transport
- Add auto-patch console feedback for CLI visibility
- Enhance error messages with actionable suggestions for common failure patterns

Intelligence:
- Add prescriptive action hints in FailureClusterPanel mapped to error types
- Add drift direction indicator and remediation guidance in DriftAlertsPanel
- Add cost efficiency hint when per-token cost is notably high
- Add ranking factor breakdown labels in EventDetail

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: acailic

agent_debugger_sdk/auto_patch/__init__.py

@@ -126,7 +126,10 @@ def activate(config: PatchConfig | None = None) -> None:
     registry.apply(config, names=names)
 
     if registry.patched_names():
-        logger.info("Peaky Peek auto-patch active for: %s", registry.patched_names())
+        patched = registry.patched_names()
+        logger.info("Peaky Peek auto-patch active for: %s", patched)
+        # Also print to console for CLI users
+        print(f"agent_debugger: auto-instrumented {', '.join(patched)}")
     else:
         logger.debug("Peaky Peek auto-patch: no adapters were patched (none available or listed)")
 

agent_debugger_sdk/config.py

@@ -6,6 +6,24 @@
 from dataclasses import dataclass
 
 
+def _parse_bool(value: str | None, default: bool = False) -> bool:
+    """Parse a boolean value from a string.
+
+    Handles: true/false, 1/0, yes/no, on/off (case-insensitive).
+    Returns default if value is None or cannot be parsed.
+    """
+    if value is None:
+        return default
+    normalized = value.strip().lower()
+    true_values = {"true", "1", "yes", "on"}
+    false_values = {"false", "0", "no", "off"}
+    if normalized in true_values:
+        return True
+    if normalized in false_values:
+        return False
+    return default
+
+
 @dataclass
 class Config:
     api_key: str | None = None
@@ -15,7 +33,35 @@ class Config:
     max_payload_kb: int = 100
     mode: str = "local"  # "local" or "cloud"
 
+    def validate(self) -> None:
+        """Validate configuration values.
+
+        Raises:
+            ValueError: If any configuration value is invalid.
+        """
+        if not self.endpoint:
+            raise ValueError("endpoint_url must be non-empty")
+
+        if not self.endpoint.startswith(("http://", "https://")):
+            raise ValueError(
+                f"endpoint_url must start with http:// or https://, got: {self.endpoint}"
+            )
+
+        if not isinstance(self.max_payload_kb, int) or self.max_payload_kb <= 0:
+            raise ValueError(
+                f"max_payload_kb must be a positive integer, got: {self.max_payload_kb}"
+            )
+
+        if self.max_payload_kb > 10000:
+            raise ValueError(
+                f"max_payload_kb must be at most 10000, got: {self.max_payload_kb}"
+            )
+
+        if not isinstance(self.enabled, bool):
+            raise ValueError(f"enabled must be a boolean, got: {type(self.enabled).__name__}")
+
     def __post_init__(self):
+        self.validate()
         if self.api_key:
             self.mode = "cloud"
             if self.endpoint == "http://localhost:8000":
@@ -47,13 +93,13 @@ def init(
         or ("https://api.agentdebugger.dev" if resolved_key else "http://localhost:8000")
     )
 
-    resolved_enabled = enabled and os.environ.get("AGENT_DEBUGGER_ENABLED", "true").lower() != "false"
+    resolved_enabled = enabled and _parse_bool(os.environ.get("AGENT_DEBUGGER_ENABLED"), default=True)
 
     _global_config = Config(
         api_key=resolved_key,
         endpoint=resolved_endpoint,
         enabled=resolved_enabled,
-        redact_prompts=os.environ.get("AGENT_DEBUGGER_REDACT_PROMPTS", str(redact_prompts)).lower() == "true",
+        redact_prompts=_parse_bool(os.environ.get("AGENT_DEBUGGER_REDACT_PROMPTS"), default=redact_prompts),
         max_payload_kb=int(os.environ.get("AGENT_DEBUGGER_MAX_PAYLOAD_KB", max_payload_kb)),
     )
     return _global_config

agent_debugger_sdk/core/recorders.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import re
 from typing import Any
 
 from .events import (
@@ -24,6 +25,43 @@
 )
 
 
+def _enhance_error_message(error_message: str) -> str:
+    """Append helpful suggestions to error messages based on common patterns.
+
+    Args:
+        error_message: The original error message.
+
+    Returns:
+        The enhanced error message with suggestions appended.
+    """
+    suggestions = []
+
+    # Check for common error patterns and provide specific suggestions
+    patterns = [
+        (r"connection refused", "The server may be down. Check that the agent_debugger server is running."),  # noqa: E501
+        (r"connection.*reset", "The connection was unexpectedly closed. This may indicate a network issue or server restart."),  # noqa: E501
+        (r"timeout", "The request took too long. Consider increasing timeout settings or checking network connectivity."),  # noqa: E501
+        (r"401|unauthorized|authentication", "Check your API key configuration in agent_debugger_sdk.config.init()."),  # noqa: E501
+        (r"403|forbidden|access denied", "Your API key may not have permission for this operation. Verify your credentials."),  # noqa: E501
+        (r"404|not found", "The API endpoint was not found. Check that the server URL is correct."),
+        (r"429|rate limit", "You are sending requests too quickly. Implement exponential backoff and retry."),
+        (r"5\d{2}|server error", "The server encountered an error. This is typically a temporary issue. Please retry."),
+        (r"no route to host", "Network connectivity issue. Check your internet connection and firewall settings."),  # noqa: E501
+        (r"certificate|tls|ssl", "SSL/TLS certificate issue. Ensure the server certificate is valid or check system clock."),  # noqa: E501
+        (r"dns.*not.*resolved|nxdomain", "DNS resolution failed. Verify the server hostname and DNS configuration."),  # noqa: E501
+    ]
+
+    message_lower = error_message.lower()
+    for pattern, suggestion in patterns:
+        if re.search(pattern, message_lower):
+            suggestions.append(f" Suggestion: {suggestion}")
+
+    if suggestions:
+        # Deduplicate and join suggestions
+        return error_message + "\n" + "\n".join(set(suggestions))
+    return error_message
+
+
 class RecordingMixin:
     """Mixin that records typed trace events through a shared emitter."""
 
@@ -195,13 +233,16 @@ async def record_error(
     ) -> str:
         self._check_entered()
 
+        # Append helpful suggestions for common error patterns
+        enhanced_message = _enhance_error_message(error_message)
+
         event = ErrorEvent(
             session_id=self.session_id,
             parent_id=self.get_current_parent(),
             event_type=EventType.ERROR,
             name=name or f"error_{error_type}",
             error_type=error_type,
-            error_message=error_message,
+            error_message=enhanced_message,
             stack_trace=stack_trace,
             importance=0.9,
         )

agent_debugger_sdk/transport.py

@@ -36,6 +36,17 @@ class PermanentError(TransportError):
 DeliveryFailureCallback = Callable[[TransportError], None]
 
 
+def _get_error_message(status_code: int) -> str:
+    """Get a specific, actionable error message for a given HTTP status code."""
+    messages = {
+        401: "Authentication failed. Check your API key configuration.",
+        403: "Access denied. Your API key may not have permission for this operation.",
+        404: "API endpoint not found. Check that the server URL is correct.",
+        429: "Rate limited. Please retry after a brief pause.",
+    }
+    return messages.get(status_code, f"Client error (status={status_code})")
+
+
 MAX_RETRIES = 3
 INITIAL_BACKOFF_SECONDS = 0.5
 BACKOFF_MULTIPLIER = 2.0
@@ -130,8 +141,10 @@ async def _execute_request(
                 status_code=response.status_code,
             )
         elif response.status_code >= 400:
+            # Provide specific, actionable error messages for common status codes
+            message = _get_error_message(response.status_code)
             raise PermanentError(
-                f"Client error (status={response.status_code})",
+                message,
                 status_code=response.status_code,
             )