fix(agent): propagate fatal LLMError on invalid llm across start/run/chat (#5956)

src/praisonai-agents/praisonaiagents/agent/agent.py

@@ -2449,7 +2449,7 @@ def _any_output_mode_enabled():
                 self.tools = tools
         # Otherwise, fall back to OpenAI environment/name (cached for performance)
         else:
-            model_name = llm or Agent._get_default_model()
+            model_name = Agent._get_default_model() if llm is None else llm
             # Pointing at a non-OpenAI endpoint without naming a model leaves the
             # OpenAI default in place, so the endpoint is asked for a model it
             # has never heard of -- Ollama answers 404 "model 'gpt-4o-mini' not

src/praisonai-agents/praisonaiagents/agent/execution_mixin.py

@@ -328,6 +328,11 @@ def run(self, prompt: str, **kwargs: Any) -> Optional[str]:
         Returns:
             The agent's response as a string, or a ``RunOutcome`` when
             ``return_outcome=True``.
+
+        Raises:
+            LLMError: When the configured ``llm``/model is invalid or the LLM
+                provider returns an unrecoverable error (unless
+                ``return_outcome=True``).
 
         Example:
             ```python
@@ -337,10 +342,11 @@ def run(self, prompt: str, **kwargs: Any) -> Optional[str]:
             ```
 
         Note:
+            Use ``run()`` in automation; ``start()`` is interactive.
             Unlike .start() which enables verbose output in TTY for interactive
             use, .run() is always silent. This makes it suitable for:
             - Production pipelines
-            - Automated scripts
+            - Automated scripts and CI
             - Background processing
             - API endpoints
         """
@@ -814,6 +820,11 @@ def start(self, prompt: Optional[str] = None, **kwargs: Any) -> Union[str, Gener
         Returns:
             - If streaming: Generator yielding response chunks
             - If not streaming: The complete response as a string
+
+        Raises:
+            LLMError: When the configured ``llm``/model is invalid or the LLM
+                provider returns an unrecoverable error. Rich UI displays a
+                sanitized error before propagating the exception to callers.
 
         Example:
             ```python
@@ -827,6 +838,7 @@ def start(self, prompt: Optional[str] = None, **kwargs: Any) -> Union[str, Gener
             ```
 
         Note:
+            Use ``run()`` in automation; ``start()`` is interactive.
             Unlike .run() which is always silent (production use), .start()
             enables verbose output by default when in a TTY for beginner-friendly
             interactive use. Use .run() for programmatic/scripted usage.
@@ -1006,20 +1018,18 @@ def run_chat():
                             current_status[0] = "Sending to LLM..."
 
                             # Check for steering messages before starting chat
+                            steering_msg = None
                             if hasattr(self, '_check_steering_messages'):
                                 try:
                                     steering_msg = self._check_steering_messages()
-                                    if steering_msg:
-                                        # Inject steering message into prompt with clear separator
-                                        prompt_with_steering = f"{prompt}\n\n{steering_msg}"
-                                        current_status[0] = "Processing steering guidance..."
-                                        result_holder[0] = self.chat(prompt_with_steering, **kwargs)
-                                    else:
-                                        result_holder[0] = self.chat(prompt, **kwargs)
                                 except Exception as e:
                                     logger.warning(f"Steering check failed, continuing without steering: {e}")
                                     current_status[0] = "Steering failed, proceeding normally..."
-                                    result_holder[0] = self.chat(prompt, **kwargs)
+
+                            if steering_msg:
+                                prompt_with_steering = f"{prompt}\n\n{steering_msg}"
+                                current_status[0] = "Processing steering guidance..."
+                                result_holder[0] = self.chat(prompt_with_steering, **kwargs)
                             else:
                                 result_holder[0] = self.chat(prompt, **kwargs)
 
@@ -1104,12 +1114,14 @@ def run_chat():
                             if current_status[0] != last_status:
                                 last_status = current_status[0]
                             status.update(f"[bold yellow]Working...[/]  {current_status[0]}")
+
+                    chat_thread.join()
 
                     # Calculate elapsed time
                     elapsed = time_module.time() - start_time
 
                     # Re-raise any error from chat
-                    if error_holder[0]:
+                    if error_holder[0] is not None:
                         raise error_holder[0]
 
                     result = result_holder[0]

src/praisonai-agents/praisonaiagents/errors.py

@@ -9,11 +9,62 @@
 - External integrations
 """
 
-from typing import Literal, Protocol, runtime_checkable, Optional, Dict, Any, get_args
+from typing import Literal, Protocol, runtime_checkable, Optional, Dict, Any, Sequence, get_args
 from dataclasses import dataclass, field
+import os
+import re
 import uuid
 import warnings
 
+_API_KEY_TOKEN_PATTERN = re.compile(r"\bsk-[A-Za-z0-9_\-]{12,}\b")
+_SECRET_ENV_VARS = (
+    "OPENAI_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "GOOGLE_API_KEY",
+    "GEMINI_API_KEY",
+    "GROQ_API_KEY",
+    "MISTRAL_API_KEY",
+    "DEEPSEEK_API_KEY",
+    "OPENROUTER_API_KEY",
+    "XAI_API_KEY",
+    "COHERE_API_KEY",
+    "AZURE_OPENAI_API_KEY",
+)
+
+
+def sanitize_llm_error_message(
+    message: str,
+    *,
+    extra_secrets: Optional[Sequence[Optional[str]]] = None,
+    preserve_tokens: Optional[Sequence[Optional[str]]] = None,
+) -> str:
+    """Redact API keys and credential literals from an LLM error message."""
+    if not message:
+        return message
+    text = str(message)
+    try:
+        from .trace.redact import redact_string
+        text = redact_string(text, enabled=True)
+    except Exception:
+        pass
+    text = _API_KEY_TOKEN_PATTERN.sub("[REDACTED]", text)
+
+    preserved = {t for t in (preserve_tokens or ()) if t}
+    candidates = []
+    if extra_secrets:
+        candidates.extend(extra_secrets)
+    for env_name in _SECRET_ENV_VARS:
+        candidates.append(os.environ.get(env_name))
+    for secret in candidates:
+        if (
+            isinstance(secret, str)
+            and len(secret) >= 6
+            and secret not in preserved
+            and secret in text
+        ):
+            text = text.replace(secret, "[REDACTED]")
+    return text
+
 
 # Closed error taxonomy for typed failure classification
 AgentErrorKind = Literal[
@@ -167,19 +218,34 @@ def __init__(
         run_id: Optional[str] = None,
         error_category: AgentErrorKind = "unknown",
         is_retryable: bool = False,  # Default to non-retryable unless specified
-        context: Optional[Dict[str, Any]] = None
+        context: Optional[Dict[str, Any]] = None,
+        extra_secrets: Optional[Sequence[Optional[str]]] = None,
     ):
+        model_str = str(model_name) if model_name else "unknown"
+        sanitized_message = sanitize_llm_error_message(
+            str(message),
+            extra_secrets=extra_secrets,
+            preserve_tokens=(model_str,),
+        )
         context = context or {}
-        context["model_name"] = model_name
+        context["model_name"] = model_str
         super().__init__(
-            message, 
-            agent_id=agent_id, 
-            run_id=run_id, 
+            sanitized_message,
+            agent_id=agent_id or "unknown",
+            run_id=run_id,
             error_category=error_category,
             is_retryable=is_retryable,
-            context=context
+            context=context,
         )
-        self.model_name = model_name
+        self.model_name = model_str
+
+    def __str__(self) -> str:
+        if self.model_name and self.model_name != "unknown":
+            return (
+                f"[{self.error_category}] {self.message} "
+                f"(model: {self.model_name}, agent: {self.agent_id}, run: {self.run_id})"
+            )
+        return super().__str__()
 
 
 class BudgetExceededError(PraisonAIError):
@@ -471,5 +537,6 @@ def __init__(self, message: str, validation_errors: Optional[list] = None, **kwa
     "HandoffDepthError", 
     "HandoffTimeoutError",
     "HandoffValidationError",
-    "PraisonAIConfigError"
+    "PraisonAIConfigError",
+    "sanitize_llm_error_message",
 ]

src/praisonai-agents/praisonaiagents/llm/llm.py

@@ -4651,7 +4651,13 @@ def _prepare_return_value(text: str) -> Union[str, tuple]:
             return _prepare_return_value(response_text)
 
         except Exception as error:
-            _get_display_functions()['display_error'](f"Error in get_response: {str(error)}")
+            from ..errors import sanitize_llm_error_message
+            _safe_err = sanitize_llm_error_message(
+                str(error),
+                extra_secrets=(getattr(self, "api_key", None),),
+                preserve_tokens=(getattr(self, "model", None),),
+            )
+            _get_display_functions()['display_error'](f"Error in get_response: {_safe_err}")
             raise
 
         # Log completion time if in debug mode
@@ -6528,7 +6534,13 @@ def _prepare_return_value(text: str) -> Union[str, tuple]:
         except Exception as error:
             if LLMContextLengthExceededException(str(error))._is_context_limit_error(str(error)):
                 raise LLMContextLengthExceededException(str(error))
-            _get_display_functions()['display_error'](f"Error in get_response_async: {str(error)}")
+            from ..errors import sanitize_llm_error_message
+            _safe_err = sanitize_llm_error_message(
+                str(error),
+                extra_secrets=(getattr(self, "api_key", None),),
+                preserve_tokens=(getattr(self, "model", None),),
+            )
+            _get_display_functions()['display_error'](f"Error in get_response_async: {_safe_err}")
             raise
 
         # Log completion time if in debug mode

src/praisonai-agents/praisonaiagents/llm/openai_client.py

@@ -1465,8 +1465,12 @@ def process_stream_response(
             status = raw.get("status") if isinstance(raw, dict) else getattr(raw, "status", None)
             if status == "failed":
                 raise
-            self.logger.error(f"Error in stream processing: {e}")
-            return None
+            from ..errors import sanitize_llm_error_message
+            self.logger.error(
+                f"Error in stream processing: "
+                f"{sanitize_llm_error_message(str(e), extra_secrets=(self.api_key,), preserve_tokens=(model,))}"
+            )
+            raise
 
     async def process_stream_response_async(
         self,
@@ -1738,8 +1742,12 @@ async def emit_event(event: 'StreamEvent'):
             status = raw.get("status") if isinstance(raw, dict) else getattr(raw, "status", None)
             if status == "failed":
                 raise
-            self.logger.error(f"Error in async stream processing: {e}")
-            return None
+            from ..errors import sanitize_llm_error_message
+            self.logger.error(
+                f"Error in async stream processing: "
+                f"{sanitize_llm_error_message(str(e), extra_secrets=(self.api_key,), preserve_tokens=(model,))}"
+            )
+            raise
 
     def _track_token_usage(self, response: Any, model: str, agent_name: Optional[str] = None) -> None:
         """Record token usage from a response into the global collector.