shadow-debugger 0.1.0__py3-none-any.whl

shadow_debugger/providers/__init__.py

@@ -0,0 +1,23 @@
+"""Built-in LLM providers. SDKs are imported lazily, only when a provider is used."""
+
+from .base import (
+    Provider,
+    ProviderError,
+    available_providers,
+    create_provider,
+    register_provider,
+)
+
+# Importing the modules registers the built-in providers.
+from . import anthropic as _anthropic  # noqa: F401,E402
+from . import gemini as _gemini  # noqa: F401,E402
+from . import ollama as _ollama  # noqa: F401,E402
+from . import openai as _openai  # noqa: F401,E402
+
+__all__ = [
+    "Provider",
+    "ProviderError",
+    "available_providers",
+    "create_provider",
+    "register_provider",
+]

shadow_debugger/providers/anthropic.py

@@ -0,0 +1,54 @@
+"""Anthropic Claude provider (``pip install shadow-debugger[anthropic]``)."""
+
+from __future__ import annotations
+
+import threading
+from typing import Any, Optional
+
+from .base import Provider, ProviderError, register_provider
+
+
+@register_provider("anthropic", "claude")
+class AnthropicProvider(Provider):
+    default_model = "claude-haiku-5-5"
+    env_key = "ANTHROPIC_API_KEY"
+    max_tokens = 2048
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._client: Optional[Any] = None
+        self._client_lock = threading.Lock()
+
+    def _get_client(self) -> Any:
+        with self._client_lock:
+            if self._client is None:
+                try:
+                    import anthropic
+                except ImportError as exc:
+                    raise ProviderError(
+                        "anthropic: package not installed. Run: pip install 'shadow-debugger[anthropic]'"
+                    ) from exc
+                kwargs: dict = {"api_key": self.api_key, "timeout": self.timeout, "max_retries": 2}
+                if self.base_url:
+                    kwargs["base_url"] = self.base_url
+                self._client = anthropic.Anthropic(**kwargs)
+            return self._client
+
+    def complete(self, system: str, prompt: str) -> str:
+        self.check_configuration()
+        client = self._get_client()
+        try:
+            response = client.messages.create(
+                model=self.model,
+                max_tokens=self.max_tokens,
+                system=system,
+                messages=[{"role": "user", "content": prompt}],
+            )
+        except Exception as exc:
+            raise ProviderError(f"anthropic: request to {self.model} failed: {exc}") from exc
+        text = "".join(
+            getattr(block, "text", "") for block in (response.content or []) if getattr(block, "type", "") == "text"
+        )
+        if not text:
+            raise ProviderError(f"anthropic: empty response from {self.model}")
+        return text

shadow_debugger/providers/base.py

@@ -0,0 +1,92 @@
+"""Provider abstraction: one small class per LLM backend, discovered through a registry."""
+
+from __future__ import annotations
+
+import abc
+import os
+from typing import Callable, ClassVar, Dict, List, Optional, Sequence, Type, TypeVar
+
+
+class ProviderError(Exception):
+    """Raised when an LLM backend cannot produce an analysis (config, network, API error)."""
+
+
+class Provider(abc.ABC):
+    """Base class for LLM backends.
+
+    Subclasses implement :meth:`complete`. To add a backend, subclass, decorate with
+    :func:`register_provider` and import the module in ``providers/__init__.py``::
+
+        @register_provider("mistral")
+        class MistralProvider(Provider):
+            default_model = "mistral-small-latest"
+            env_key = "MISTRAL_API_KEY"
+
+            def complete(self, system: str, prompt: str) -> str:
+                ...
+    """
+
+    name: ClassVar[str] = ""
+    default_model: ClassVar[str] = ""
+    env_key: ClassVar[Optional[str]] = None
+    requires_api_key: ClassVar[bool] = True
+
+    def __init__(
+        self,
+        model: Optional[str] = None,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        fallback_models: Sequence[str] = (),
+    ) -> None:
+        self.model = model or self.default_model
+        self.api_key = api_key or (os.getenv(self.env_key) if self.env_key else None)
+        self.base_url = base_url
+        self.timeout = timeout
+        self.fallback_models: List[str] = [m for m in fallback_models if m and m != self.model]
+
+    def check_configuration(self) -> None:
+        """Raise ProviderError early if the provider is obviously misconfigured."""
+        if self.requires_api_key and not self.api_key:
+            hint = f" or set the {self.env_key} environment variable" if self.env_key else ""
+            raise ProviderError(f"{self.name}: missing API key. Pass api_key to init(){hint}.")
+
+    @abc.abstractmethod
+    def complete(self, system: str, prompt: str) -> str:
+        """Return the model's text answer or raise :class:`ProviderError`."""
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(model={self.model!r})"
+
+
+_REGISTRY: Dict[str, Type[Provider]] = {}
+
+P = TypeVar("P", bound=Type[Provider])
+
+
+def register_provider(*names: str) -> Callable[[P], P]:
+    """Class decorator registering a provider under one or more names."""
+
+    def decorator(cls: P) -> P:
+        if not names:
+            raise ValueError("register_provider() needs at least one name")
+        cls.name = cls.name or names[0]
+        for n in names:
+            _REGISTRY[n.lower()] = cls
+        return cls
+
+    return decorator
+
+
+def available_providers() -> List[str]:
+    return sorted(_REGISTRY)
+
+
+def create_provider(name: str, **kwargs) -> Provider:
+    key = name.lower().strip()
+    if key not in _REGISTRY:
+        raise ValueError(
+            f"Unknown provider {name!r}. Available: {', '.join(available_providers())}. "
+            "You can also pass a Provider instance."
+        )
+    return _REGISTRY[key](**kwargs)

shadow_debugger/providers/gemini.py

@@ -0,0 +1,66 @@
+"""Google Gemini provider (``pip install shadow-debugger[gemini]``)."""
+
+from __future__ import annotations
+
+import threading
+from typing import Any, Optional
+
+from .base import Provider, ProviderError, register_provider
+
+# Status codes worth trying the next fallback model for. The SDK already retries
+# transient errors with exponential backoff before raising.
+_FALLBACK_CODES = {404, 429, 500, 502, 503, 504}
+
+
+@register_provider("gemini", "google")
+class GeminiProvider(Provider):
+    default_model = "gemini-3.8-flash"
+    env_key = "GEMINI_API_KEY"
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._client: Optional[Any] = None
+        self._client_lock = threading.Lock()
+
+    def _get_client(self) -> Any:
+        with self._client_lock:
+            if self._client is None:
+                try:
+                    from google import genai
+                except ImportError as exc:
+                    raise ProviderError(
+                        "gemini: google-genai is not installed. Run: pip install 'shadow-debugger[gemini]'"
+                    ) from exc
+                self._client = genai.Client(
+                    api_key=self.api_key,
+                    http_options={"timeout": int(self.timeout * 1000)},  # milliseconds
+                )
+            return self._client
+
+    def complete(self, system: str, prompt: str) -> str:
+        self.check_configuration()
+        client = self._get_client()
+        last_error: Optional[BaseException] = None
+
+        for model in [self.model, *self.fallback_models]:
+            try:
+                interaction = client.interactions.create(
+                    model=model,
+                    system_instruction=system,
+                    input=prompt,
+                    store=False,  # crash data must not be retained server-side
+                )
+                text = getattr(interaction, "output_text", None)
+                if not text:
+                    raise ProviderError(f"gemini: empty response from {model}")
+                return str(text)
+            except ProviderError:
+                raise
+            except Exception as exc:
+                last_error = exc
+                code = getattr(exc, "code", None) or getattr(exc, "status_code", None)
+                if code in _FALLBACK_CODES:
+                    continue
+                raise ProviderError(f"gemini: request to {model} failed: {exc}") from exc
+
+        raise ProviderError(f"gemini: all models failed; last error: {last_error}") from last_error

shadow_debugger/providers/ollama.py

@@ -0,0 +1,65 @@
+"""Ollama provider: fully local, no API key, no extra dependency."""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import Any
+
+from .base import Provider, ProviderError, register_provider
+
+DEFAULT_OLLAMA_HOST = "http://localhost:11434"
+
+
+def normalize_host(host: str) -> str:
+    host = host.strip().rstrip("/")
+    if "://" not in host:
+        # OLLAMA_HOST is often set as "0.0.0.0:11434" or "myhost:11434"
+        host = "http://" + host
+    return host.replace("://0.0.0.0", "://localhost")
+
+
+@register_provider("ollama", "local")
+class OllamaProvider(Provider):
+    default_model = "llama3.2"
+    requires_api_key = False
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.base_url = normalize_host(self.base_url or os.getenv("OLLAMA_HOST") or DEFAULT_OLLAMA_HOST)
+
+    def complete(self, system: str, prompt: str) -> str:
+        payload = {
+            "model": self.model,
+            "messages": [
+                {"role": "system", "content": system},
+                {"role": "user", "content": prompt},
+            ],
+            "stream": False,
+            "options": {"temperature": 0.2},
+        }
+        request = urllib.request.Request(
+            f"{self.base_url}/api/chat",
+            data=json.dumps(payload).encode("utf-8"),
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as resp:
+                data = json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode("utf-8", errors="replace")[:300]
+            raise ProviderError(f"ollama: HTTP {exc.code} from {self.base_url}: {detail}") from exc
+        except urllib.error.URLError as exc:
+            raise ProviderError(
+                f"ollama: cannot reach {self.base_url} (is `ollama serve` running?): {exc.reason}"
+            ) from exc
+        except (TimeoutError, OSError, ValueError) as exc:
+            raise ProviderError(f"ollama: request failed: {exc}") from exc
+
+        content = (data.get("message") or {}).get("content")
+        if not content:
+            raise ProviderError(f"ollama: empty response from model {self.model}")
+        return content

shadow_debugger/providers/openai.py

@@ -0,0 +1,63 @@
+"""OpenAI provider (``pip install shadow-debugger[openai]``).
+
+Also works with any OpenAI-compatible server (Groq, Together, LM Studio, vLLM...) via ``base_url``.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any, Optional
+
+from .base import Provider, ProviderError, register_provider
+
+
+@register_provider("openai")
+class OpenAIProvider(Provider):
+    default_model = "gpt-5.4-nano"
+    env_key = "OPENAI_API_KEY"
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._client: Optional[Any] = None
+        self._client_lock = threading.Lock()
+
+    def check_configuration(self) -> None:
+        # Local OpenAI-compatible servers usually don't need a key.
+        if self.base_url:
+            return
+        super().check_configuration()
+
+    def _get_client(self) -> Any:
+        with self._client_lock:
+            if self._client is None:
+                try:
+                    from openai import OpenAI
+                except ImportError as exc:
+                    raise ProviderError(
+                        "openai: package not installed. Run: pip install 'shadow-debugger[openai]'"
+                    ) from exc
+                self._client = OpenAI(
+                    api_key=self.api_key or "not-needed",
+                    base_url=self.base_url,
+                    timeout=self.timeout,
+                    max_retries=2,
+                )
+            return self._client
+
+    def complete(self, system: str, prompt: str) -> str:
+        self.check_configuration()
+        client = self._get_client()
+        try:
+            response = client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": system},
+                    {"role": "user", "content": prompt},
+                ],
+            )
+        except Exception as exc:
+            raise ProviderError(f"openai: request to {self.model} failed: {exc}") from exc
+        content = response.choices[0].message.content if response.choices else None
+        if not content:
+            raise ProviderError(f"openai: empty response from {self.model}")
+        return content

shadow_debugger/py.typed

@@ -0,0 +1 @@
+# PEP 561 marker file

shadow_debugger/redaction.py

@@ -0,0 +1,190 @@
+"""Secret scrubbing and safe serialization for local variables and request metadata."""
+
+from __future__ import annotations
+
+import datetime as _dt
+import decimal
+import enum
+import fractions
+import itertools
+import pathlib
+import re
+import types
+import uuid
+from typing import Any, Iterable, List, Optional, Pattern
+
+REDACTED = "[REDACTED]"
+
+_DEFAULT_KEY_PATTERN = (
+    r"passw|passwd|pwd|secret|token|api[_-]?key|apikey|access[_-]?key|"
+    r"priv(?:ate)?[_-]?key|credential|bearer|cookie|session[_-]?id|"
+    r"credit[_-]?card|card[_-]?number|cvv|ssn|signature|"
+    # Match 'auth' as a word or 'authorization', so keys like 'author' are left alone
+    r"(?:^|[^a-z])auth(?:$|[^a-z]|orization)"
+)
+
+_DEFAULT_VALUE_PATTERNS: List[str] = [
+    r"-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----",
+    r"\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}",
+    r"\bsk-[A-Za-z0-9_-]{16,}",
+    r"\bAIza[0-9A-Za-z_-]{30,}",
+    r"\b(?:AKIA|ASIA)[0-9A-Z]{16}\b",
+    r"\bgh[pousr]_[A-Za-z0-9]{30,}",
+    r"\bgithub_pat_[A-Za-z0-9_]{30,}",
+    r"\bxox[abprs]-[A-Za-z0-9-]{10,}",
+    r"\b(?:sk|rk|pk)_(?:live|test)_[A-Za-z0-9]{10,}",
+]
+
+_PREFIXED_PATTERNS: List[Pattern[str]] = [
+    re.compile(r"(?i)\b((?:bearer|basic)\s+)[A-Za-z0-9\-._~+/]{16,}=*"),
+    re.compile(
+        r"(?i)([?&;](?:[^=&\s#]*?(?:token|key|secret|passw|pwd|auth|signature|sig|code|session)"
+        r"[^=&\s#]*)=)[^&\s#'\"]+"
+    ),
+    re.compile(r"(?i)(\b[a-z][a-z0-9+.-]*://[^:/\s@]+:)[^@\s/]+(?=@)"),
+    re.compile(
+        r"(?i)((?:passw(?:or)?d|passwd|pwd|secret|token|api[_-]?key|apikey|access[_-]?key)"
+        r"[\"']?\s*[=:]\s*)([\"'])[^\"'\n]{3,}\2"
+    ),
+    re.compile(
+        r"(?i)((?:passw(?:or)?d|passwd|pwd|secret|token|api[_-]?key|apikey|access[_-]?key)"
+        r"\s*[=:]\s*)(?![\"'])[^\s'\",;&()]{8,}(?![(\w])"
+    ),
+]
+
+_SAFE_REPR_TYPES = (
+    _dt.datetime,
+    _dt.date,
+    _dt.time,
+    _dt.timedelta,
+    decimal.Decimal,
+    fractions.Fraction,
+    uuid.UUID,
+    complex,
+    pathlib.PurePath,
+    enum.Enum,
+    range,
+    type,
+    types.ModuleType,
+    types.FunctionType,
+    types.BuiltinFunctionType,
+    types.MethodType,
+    BaseException,
+)
+
+
+class Redactor:
+    """Turns runtime values into JSON-safe structures while stripping secrets."""
+
+    def __init__(
+        self,
+        extra_key_patterns: Iterable[str] = (),
+        extra_value_patterns: Iterable[str] = (),
+        max_depth: int = 4,
+        max_items: int = 30,
+        max_string: int = 300,
+    ) -> None:
+        key_sources = [_DEFAULT_KEY_PATTERN, *extra_key_patterns]
+        self._key_re = re.compile("|".join(f"(?:{p})" for p in key_sources), re.IGNORECASE)
+        self._value_res = [re.compile(p) for p in (*_DEFAULT_VALUE_PATTERNS, *extra_value_patterns)]
+        self.max_depth = max_depth
+        self.max_items = max_items
+        self.max_string = max_string
+
+    def is_sensitive_key(self, key: str) -> bool:
+        return bool(key) and bool(self._key_re.search(key))
+
+    def redact_text(self, text: Optional[str], limit: Optional[int] = None) -> str:
+        if not text:
+            return text or ""
+        for pattern in _PREFIXED_PATTERNS:
+            text = pattern.sub(lambda m: m.group(1) + REDACTED, text)
+        for pattern in self._value_res:
+            text = pattern.sub(REDACTED, text)
+        if limit is not None and len(text) > limit:
+            text = text[:limit] + f"... (truncated, {len(text) - limit} more chars)"
+        return text
+
+    def sanitize(self, key: str, value: Any, _depth: int = 0, _seen: Optional[set] = None) -> Any:
+        if self.is_sensitive_key(str(key)):
+            return REDACTED
+
+        if value is None or isinstance(value, bool):
+            return value
+        if isinstance(value, (int, float)):
+            return value
+        if isinstance(value, str):
+            return self.redact_text(value[: self.max_string * 4], limit=self.max_string)
+        if isinstance(value, (bytes, bytearray, memoryview)):
+            return f"<{type(value).__name__} len={len(value)}>"
+
+        if _depth >= self.max_depth:
+            return f"<{_type_name(value)} ... (max depth)>"
+
+        seen = _seen if _seen is not None else set()
+        if id(value) in seen:
+            return f"<{_type_name(value)} (circular reference)>"
+
+        if isinstance(value, dict):
+            seen.add(id(value))
+            try:
+                result = {}
+                for i, (k, v) in enumerate(value.items()):
+                    if i >= self.max_items:
+                        result["..."] = f"{len(value) - self.max_items} more keys"
+                        break
+                    result[str(k)] = self.sanitize(str(k), v, _depth + 1, seen)
+                return result
+            finally:
+                seen.discard(id(value))
+
+        if isinstance(value, (list, tuple, set, frozenset)):
+            seen.add(id(value))
+            try:
+                out = [
+                    self.sanitize("", item, _depth + 1, seen)
+                    for item in itertools.islice(value, self.max_items)
+                ]
+                if len(value) > self.max_items:
+                    out.append(f"... ({len(value) - self.max_items} more items)")
+                return out
+            finally:
+                seen.discard(id(value))
+
+        if isinstance(value, _SAFE_REPR_TYPES):
+            return self.redact_text(_safe_repr(value), limit=self.max_string)
+
+        # For arbitrary objects (like Django QuerySets), read __dict__ directly
+        # instead of calling repr()/str(), which could trigger lazy DB queries.
+        attrs = _instance_dict(value)
+        if attrs is None:
+            return f"<{_type_name(value)}>"
+        seen.add(id(value))
+        try:
+            public = {k: v for k, v in attrs.items() if not k.startswith("__")}
+            return {"__type__": _type_name(value), **self.sanitize("", public, _depth + 1, seen)}
+        finally:
+            seen.discard(id(value))
+
+
+def _type_name(value: Any) -> str:
+    cls = type(value)
+    module = getattr(cls, "__module__", "")
+    if module in ("builtins", "", None):
+        return cls.__qualname__
+    return f"{module}.{cls.__qualname__}"
+
+
+def _safe_repr(value: Any) -> str:
+    try:
+        return repr(value)
+    except Exception:
+        return f"<{_type_name(value)} (repr failed)>"
+
+
+def _instance_dict(value: Any) -> Optional[dict]:
+    try:
+        d = object.__getattribute__(value, "__dict__")
+    except Exception:
+        return None
+    return d if isinstance(d, dict) else None

shadow_debugger/reporter.py

@@ -0,0 +1,128 @@
+"""Writes diagnoses to Markdown files, the ``shadow_debugger`` logger and (optionally) stderr."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import sys
+import threading
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger("shadow_debugger")
+
+_UNSAFE_FILENAME_CHARS = re.compile(r"[^A-Za-z0-9_.-]+")
+
+
+class ReportManager:
+    def __init__(self, output_dir: Optional[str] = "./shadow_reports", print_to_console: bool = False) -> None:
+        self.output_dir = output_dir
+        self.print_to_console = print_to_console
+        self._dir_lock = threading.Lock()
+        self._dir_ready = False
+
+    def _ensure_dir(self) -> str:
+        assert self.output_dir is not None
+        # Created lazily: importing/initializing the library must not touch the filesystem.
+        with self._dir_lock:
+            if not self._dir_ready:
+                os.makedirs(self.output_dir, exist_ok=True)
+                self._dir_ready = True
+        return self.output_dir
+
+    def _new_report_path(self, error_context: Dict[str, Any], now: datetime) -> str:
+        directory = self._ensure_dir()
+        exc_type = _UNSAFE_FILENAME_CHARS.sub("_", str(error_context.get("exception_type", "Error")))[:60]
+        fingerprint = str(error_context.get("fingerprint", ""))[:8] or "nofp"
+        base = f"incident_{now.strftime('%Y%m%d_%H%M%S')}_{exc_type}_{fingerprint}"
+        for suffix in range(1000):
+            path = os.path.join(directory, f"{base}{'' if suffix == 0 else f'_{suffix}'}.md")
+            try:
+                # 'x' mode fails if the file exists: no silent overwrite between workers.
+                with open(path, "x", encoding="utf-8"):
+                    return path
+            except FileExistsError:
+                continue
+        raise OSError(f"Could not allocate a unique report filename for {base}")
+
+    def render(self, error_context: Dict[str, Any], ai_analysis: str, timestamp: datetime) -> str:
+        exc_type = error_context.get("exception_type", "Error")
+        parts = [
+            "# Shadow Debugger Incident Report",
+            "",
+            f"**Timestamp:** {timestamp.isoformat()}  ",
+            f"**Exception:** `{exc_type}`: {error_context.get('exception_message')}  ",
+            f"**Location:** `{error_context.get('file')}:{error_context.get('line')}`"
+            f" in `{error_context.get('function') or '?'}`  ",
+            f"**Fingerprint:** `{error_context.get('fingerprint')}`"
+            f" (occurrences so far: {error_context.get('occurrence_count', 1)})  ",
+        ]
+        if error_context.get("model"):
+            parts.append(f"**Model:** `{error_context['model']}`  ")
+        parts += ["", "---", "", ai_analysis.strip(), ""]
+
+        check = error_context.get("patch_check")
+        if check and check.get("attempted"):
+            status = "Passed" if check.get("success") else "Failed"
+            parts += ["### Proposed Code Syntax Check", f"**Status:** {status}. {check.get('message')}", ""]
+
+        if error_context.get("extra_metadata"):
+            parts += [
+                "### Request / Application Metadata",
+                "```json",
+                json.dumps(error_context["extra_metadata"], indent=2, ensure_ascii=False, default=str),
+                "```",
+                "",
+            ]
+
+        parts += ["---", "### Raw Traceback (redacted)", "```text", str(error_context.get("traceback", "")).rstrip(), "```", ""]
+        return "\n".join(parts)
+
+    def report(self, error_context: Dict[str, Any], ai_analysis: str) -> Optional[str]:
+        """Persist and announce a diagnosis. Returns the report path (or None)."""
+        now = datetime.now(timezone.utc)
+        exc_type = error_context.get("exception_type", "Error")
+        saved_path: Optional[str] = None
+
+        if self.output_dir:
+            saved_path = self._new_report_path(error_context, now)
+            with open(saved_path, "w", encoding="utf-8") as fh:
+                fh.write(self.render(error_context, ai_analysis, now))
+
+        logger.info(
+            "Incident diagnosed: %s: %s (report: %s)",
+            exc_type,
+            error_context.get("exception_message"),
+            saved_path or "not saved",
+            extra={"shadow_incident": error_context, "shadow_analysis": ai_analysis},
+        )
+
+        if self.print_to_console:
+            self._print(error_context, ai_analysis, saved_path)
+        return saved_path
+
+    @staticmethod
+    def _print(error_context: Dict[str, Any], ai_analysis: str, saved_path: Optional[str]) -> None:
+        bar = "=" * 60
+        lines = [
+            "",
+            bar,
+            "[Shadow Debugger] Incident diagnosed in background",
+            f"Exception: {error_context.get('exception_type')}: {error_context.get('exception_message')}",
+        ]
+        check = error_context.get("patch_check")
+        if check and check.get("attempted"):
+            lines.append(f"Syntax check: {check.get('message')}")
+        if saved_path:
+            lines.append(f"Report written to: {saved_path}")
+        lines += [bar, ai_analysis, bar, ""]
+        text = "\n".join(lines)
+        stream = sys.stderr
+        try:
+            stream.write(text + "\n")
+        except UnicodeEncodeError:
+            encoding = getattr(stream, "encoding", None) or "ascii"
+            stream.write(text.encode(encoding, errors="replace").decode(encoding) + "\n")
+        stream.flush()