code-muse 0.0.1__py3-none-any.whl

code_muse/agents/_compaction.py

@@ -0,0 +1,506 @@
+"""Message history compaction (truncation + summarization).
+
+Replaces the old ``message_history_processor`` / ``message_history_accumulator``
+pair from ``BaseAgent``. All logic here is free-function; the one stateful
+entry point is ``make_history_processor(agent)`` which returns a closure that
+pydantic-ai wires in as its ``history_processors`` callback.
+
+The delayed-compaction globals and the retry-after-tool-calls plumbing from
+the original god-class are **gone**. If compaction can't run safely right now
+(pending tool calls + summarization strategy), we just skip it this cycle and
+let the next ``history_processor`` invocation handle it.
+"""
+
+import dataclasses
+from collections.abc import Callable
+from typing import Any
+
+from pydantic_ai.messages import (
+    ModelMessage,
+    ModelRequest,
+    ModelResponse,
+    TextPart,
+    ThinkingPart,
+)
+
+from code_muse.agents._history import (
+    CompactionCache,
+    estimate_tokens_for_message,
+    filter_huge_messages,
+    has_pending_tool_calls,
+    hash_message,
+    prune_interrupted_tool_calls,
+)
+from code_muse.callbacks import (
+    on_message_history_processor_end,
+    on_message_history_processor_start,
+)
+from code_muse.config import (
+    get_compaction_strategy,
+    get_compaction_threshold,
+    get_protected_token_count,
+)
+from code_muse.messaging import emit_error, emit_info, emit_warning
+from code_muse.messaging.spinner import SpinnerBase, update_spinner_context
+from code_muse.summarization_agent import SummarizationError, run_summarization_sync
+
+_SUMMARIZATION_INSTRUCTIONS = (
+    "The input will be a log of Agentic AI steps that have been taken"
+    " as well as user queries, etc. Summarize the contents of these steps."
+    " The high level details should remain but the bulk of the content from tool-call"
+    " responses should be compacted and summarized. For example if you see a tool-call"
+    " reading a file, and the file contents are large, then in your summary you might just"
+    " write: * used read_file on space_invaders.cpp - contents removed."
+    "\n Make sure your result is a bulleted list of all steps and interactions."
+    "\n\nNOTE: This summary represents older conversation history. "
+    "Recent messages are preserved separately."
+)
+
+
+def _find_safe_split_index(messages: list[ModelMessage], initial_split_idx: int) -> int:
+    """Adjust split index so we never sever a tool_call from its tool_return."""
+    if initial_split_idx <= 1:
+        return initial_split_idx
+
+    protected_tool_return_ids: set[str] = set()
+    for msg in messages[initial_split_idx:]:
+        for part in getattr(msg, "parts", []) or []:
+            if getattr(part, "part_kind", None) == "tool-return":
+                tcid = getattr(part, "tool_call_id", None)
+                if tcid:
+                    protected_tool_return_ids.add(tcid)
+
+    if not protected_tool_return_ids:
+        return initial_split_idx
+
+    adjusted_idx = initial_split_idx
+    # Walk backwards; never cross the system message at index 0.
+    for i in range(initial_split_idx - 1, 0, -1):
+        msg = messages[i]
+        has_match = False
+        for part in getattr(msg, "parts", []) or []:
+            if getattr(part, "part_kind", None) == "tool-call":
+                tcid = getattr(part, "tool_call_id", None)
+                if tcid and tcid in protected_tool_return_ids:
+                    has_match = True
+                    break
+        if has_match:
+            adjusted_idx = i
+        else:
+            # Tool calls and their returns are adjacent — first miss ends it.
+            break
+
+    return adjusted_idx
+
+
+def split_for_protected_summarization(
+    messages: list[ModelMessage],
+    protected_tokens: int,
+    model_name: str | None = None,
+    cache: CompactionCache | None = None,
+) -> tuple[list[ModelMessage], list[ModelMessage]]:
+    """Split messages into (to_summarize, protected) groups.
+
+    The system message (index 0) is always protected. Starting from the most
+    recent message, we accumulate messages into the protected zone until we
+    hit ``protected_tokens``. Everything in-between becomes summarization
+    fodder. The split point is adjusted to keep tool_call/tool_return pairs
+    together.
+    """
+    if len(messages) <= 1:
+        return [], messages
+
+    _tok = cache.estimate_tokens if cache else estimate_tokens_for_message
+
+    system_message = messages[0]
+    system_tokens = _tok(system_message, model_name)
+
+    protected_messages: list[ModelMessage] = []
+    running_tokens = system_tokens
+
+    for i in range(len(messages) - 1, 0, -1):
+        msg_tokens = _tok(messages[i], model_name)
+        if running_tokens + msg_tokens > protected_tokens:
+            break
+        protected_messages.append(messages[i])
+        running_tokens += msg_tokens
+
+    protected_messages.reverse()
+    protected_messages.insert(0, system_message)
+
+    protected_start_idx = max(1, len(messages) - (len(protected_messages) - 1))
+    protected_start_idx = _find_safe_split_index(messages, protected_start_idx)
+    messages_to_summarize = messages[1:protected_start_idx]
+
+    emit_info(
+        f"🔒 Protecting {len(protected_messages)} recent messages "
+        f"({running_tokens} tokens, limit: {protected_tokens})"
+    )
+    emit_info(f"📝 Summarizing {len(messages_to_summarize)} older messages")
+
+    return messages_to_summarize, protected_messages
+
+
+def truncate(
+    messages: list[ModelMessage],
+    protected_tokens: int,
+    model_name: str | None = None,
+    cache: CompactionCache | None = None,
+) -> list[ModelMessage]:
+    """Drop middle messages, keeping system prompt, optional thinking, and recent tail."""
+    import queue
+
+    if not messages:
+        return messages
+
+    _tok = cache.estimate_tokens if cache else estimate_tokens_for_message
+
+    emit_info("Truncating message history to manage token usage")
+    result: list[ModelMessage] = [messages[0]]
+
+    # Preserve the 2nd message if it's an extended-thinking context.
+    skip_second = False
+    if len(messages) > 1:
+        second_msg = messages[1]
+        if any(isinstance(part, ThinkingPart) for part in second_msg.parts):
+            result.append(second_msg)
+            skip_second = True
+
+    start_idx = 2 if skip_second else 1
+    messages_to_scan = messages[start_idx:]
+
+    num_tokens = 0
+    stack: queue.LifoQueue[ModelMessage] = queue.LifoQueue()
+    for msg in reversed(messages_to_scan):
+        num_tokens += _tok(msg, model_name)
+        if num_tokens > protected_tokens:
+            break
+        stack.put(msg)
+
+    while not stack.empty():
+        result.append(stack.get())
+
+    return prune_interrupted_tool_calls(result)
+
+
+def _run_summarization_core(
+    messages: list[ModelMessage],
+    protected_tokens: int,
+    with_protection: bool,
+    model_name: str | None,
+    cache: CompactionCache | None = None,
+) -> tuple[list[ModelMessage], list[ModelMessage]]:
+    """Inner summarization that propagates exceptions to the caller.
+
+    Returns ``(compacted_messages, summarized_source_messages)`` or raises
+    on summarization-agent failure. Use :func:`summarize` if you want the
+    swallow-and-return-original behavior, or call this directly when you want
+    to handle failure yourself (e.g. fall back to truncation).
+    """
+    if not messages:
+        return [], []
+
+    if with_protection:
+        messages_to_summarize, protected_messages = split_for_protected_summarization(
+            messages, protected_tokens, model_name, cache=cache
+        )
+    else:
+        messages_to_summarize = messages[1:]
+        protected_messages = messages[:1]
+
+    system_message = messages[0]
+
+    if not messages_to_summarize:
+        return prune_interrupted_tool_calls(messages), []
+
+    pruned = prune_interrupted_tool_calls(messages_to_summarize)
+    if not pruned:
+        return prune_interrupted_tool_calls(messages), []
+
+    new_messages = run_summarization_sync(
+        _SUMMARIZATION_INSTRUCTIONS, message_history=pruned
+    )
+
+    if not isinstance(new_messages, list):
+        emit_warning(
+            "Summarization agent returned non-list output; wrapping into message request"
+        )
+        new_messages = [ModelRequest([TextPart(str(new_messages))])]
+
+    compacted: list[ModelMessage] = [system_message] + list(new_messages)
+    compacted.extend(msg for msg in protected_messages if msg is not system_message)
+    return prune_interrupted_tool_calls(compacted), messages_to_summarize
+
+
+def _log_summarization_failure(error: Exception, fallback_note: str = "") -> None:
+    """Single source of truth for summarization-failure user messaging."""
+    error_type = type(error).__name__
+    emit_error(f"Compaction failed: [{error_type}] {error}")
+    if isinstance(error, SummarizationError) and error.original_error:
+        underlying = type(error.original_error).__name__
+        suffix = f" {fallback_note}" if fallback_note else ""
+        emit_warning(f"💡 Underlying error was {underlying}.{suffix}")
+    elif fallback_note:
+        emit_warning(fallback_note)
+
+
+def summarize(
+    messages: list[ModelMessage],
+    protected_tokens: int,
+    with_protection: bool = True,
+    model_name: str | None = None,
+    cache: CompactionCache | None = None,
+) -> tuple[list[ModelMessage], list[ModelMessage]]:
+    """Summarize older messages, preserving the protected recent tail.
+
+    Returns ``(compacted_messages, summarized_source_messages)``. On failure
+    we log a warning and return ``(messages, [])`` so the run continues.
+    """
+    try:
+        return _run_summarization_core(
+            messages, protected_tokens, with_protection, model_name, cache=cache
+        )
+    except Exception as e:
+        _log_summarization_failure(
+            e,
+            "Consider using '/set compaction_strategy=truncation' as a fallback.",
+        )
+        return messages, []
+
+
+def _truncate_with_dropped(
+    filtered: list[ModelMessage],
+    protected_tokens: int,
+    model_name: str | None,
+    cache: CompactionCache | None = None,
+) -> tuple[list[ModelMessage], list[ModelMessage]]:
+    """Truncate ``filtered`` and compute which messages got dropped.
+
+    Shared by the truncation strategy and the summarization-failure fallback
+    so both paths agree on what counts as 'dropped' for hash bookkeeping.
+    """
+    result_messages = truncate(filtered, protected_tokens, model_name, cache=cache)
+    _hash = cache.hash_message if cache else hash_message
+    result_hashes = {_hash(m) for m in result_messages}
+    dropped = [m for m in filtered if _hash(m) not in result_hashes]
+    return result_messages, dropped
+
+
+def compact(
+    agent: Any,
+    messages: list[ModelMessage],
+    model_max: int,
+    context_overhead: int,
+) -> tuple[list[ModelMessage], list[ModelMessage]]:
+    """Unified compaction entrypoint. Replaces ``message_history_processor``.
+
+    Args:
+        agent: The owning agent. Used to resolve the active model name so
+            token estimates can apply per-model calibration multipliers.
+        messages: Current message history (already accumulated by the caller).
+        model_max: Effective model context window in tokens.
+        context_overhead: Estimated overhead for system prompt + tool schemas.
+
+    Returns:
+        ``(new_messages, dropped_messages_for_hash_tracking)``.
+    """
+    # Resolve model name once so all downstream estimators apply the same
+    # per-model calibration multiplier.
+    model_name: str | None = None
+    if agent is not None:
+        try:
+            model_name = agent.get_model_name()
+        except Exception:
+            model_name = None
+
+    # PERF-04: create a per-compaction cache to avoid repeated hash/token
+    # computations on the same message objects within this invocation.
+    cache = CompactionCache()
+
+    message_tokens = cache.sum_tokens(messages, model_name)
+    total_tokens = message_tokens + context_overhead
+    proportion_used = total_tokens / model_max if model_max else 0.0
+
+    context_summary = SpinnerBase.format_context_info(
+        total_tokens, model_max, proportion_used
+    )
+    update_spinner_context(context_summary)
+
+    threshold = get_compaction_threshold()
+    if proportion_used <= threshold:
+        return messages, []
+
+    strategy = get_compaction_strategy()
+
+    protected_tokens = get_protected_token_count()
+    filtered = filter_huge_messages(messages, model_name, cache=cache)
+
+    # filter_huge_messages() already runs prune_interrupted_tool_calls(),
+    # so by this point any orphaned tool_call / tool_return pairs (from
+    # cancelled runs, Ctrl-C interrupts, etc.) have been stripped out. The
+    # check below only trips on a genuine mid-execution state, which
+    # shouldn't happen when the history_processor is invoked — but we keep
+    # it as a defensive safety net.
+    #
+    # Previously this check ran on the raw `messages` list, which meant a
+    # single orphaned tool_call (e.g., from one cancelled command weeks ago)
+    # would defer summarization forever, letting history grow unbounded.
+    if strategy == "summarization" and has_pending_tool_calls(filtered):
+        emit_warning(
+            "⚠️  Summarization deferred: pending tool call(s) detected "
+            "after pruning orphans. Will retry on next invocation.",
+            message_group="token_context_status",
+        )
+        return messages, []
+
+    if strategy == "truncation":
+        result_messages, summarized_messages = _truncate_with_dropped(
+            filtered, protected_tokens, model_name, cache=cache
+        )
+    else:
+        # Route through the public summarize() so error handling, logging,
+        # and any future instrumentation stay in one place (DRY).
+        result_messages, summarized_messages = summarize(
+            filtered, protected_tokens, True, model_name, cache=cache
+        )
+        # If summarization failed gracefully (returned original messages
+        # with nothing dropped), fall back to truncation for this cycle.
+        # The user's strategy preference is preserved for the next cycle.
+        if not summarized_messages:
+            emit_warning(
+                "↪️  Summarization produced no compaction; "
+                "falling back to truncation for this cycle.",
+                message_group="token_context_status",
+            )
+            result_messages, summarized_messages = _truncate_with_dropped(
+                filtered, protected_tokens, model_name, cache=cache
+            )
+
+    final_token_count = cache.sum_tokens(result_messages, model_name)
+    final_summary = SpinnerBase.format_context_info(
+        final_token_count,
+        model_max,
+        final_token_count / model_max if model_max else 0.0,
+    )
+    update_spinner_context(final_summary)
+
+    return result_messages, summarized_messages
+
+
+def _strip_empty_thinking_parts(
+    messages: list[ModelMessage],
+) -> tuple[list[ModelMessage], int]:
+    """Remove empty ThinkingParts; drop messages rendered empty by removal."""
+    cleaned: list[ModelMessage] = []
+    filtered_count = 0
+    for msg in messages:
+        parts = list(msg.parts)
+        if (
+            len(parts) == 1
+            and isinstance(parts[0], ThinkingPart)
+            and not parts[0].content
+        ):
+            filtered_count += 1
+            continue
+        if any(isinstance(p, ThinkingPart) and not p.content for p in parts):
+            msg = dataclasses.replace(
+                msg,
+                parts=[
+                    p
+                    for p in parts
+                    if not (isinstance(p, ThinkingPart) and not p.content)
+                ],
+            )
+            if not msg.parts:
+                filtered_count += 1
+                continue
+        cleaned.append(msg)
+    return cleaned, filtered_count
+
+
+def make_history_processor(agent: Any) -> Callable[..., list[ModelMessage]]:
+    """Build the pydantic-ai ``history_processors`` callback for ``agent``.
+
+    The returned closure:
+      1. Fires ``on_message_history_processor_start``.
+      2. Merges any incoming messages not already in ``agent._message_history``
+         (preserving the last-message regardless of compacted-hash collisions).
+      3. Runs ``compact(...)`` if we're over threshold.
+      4. Records dropped-message hashes in ``agent._compacted_message_hashes``.
+      5. Strips empty ThinkingParts.
+      6. Trims trailing ModelResponse messages so history ends with a ModelRequest.
+      7. Fires ``on_message_history_processor_end``.
+
+    Agent contract (Phase 3 will enforce on ``BaseAgent``):
+      - ``agent._message_history: list``
+      - ``agent._compacted_message_hashes: set``
+      - ``agent._get_model_context_length() -> int``
+      - ``agent._estimate_context_overhead() -> int``
+      - ``agent.name`` / ``agent.session_id`` (optional)
+    """
+
+    def history_processor(messages: list[ModelMessage]) -> list[ModelMessage]:
+        # pydantic-ai picks 1-arg vs 2-arg processor by inspecting the first
+        # parameter's type annotation (must be ``RunContext`` for 2-arg form).
+        # We don't need ctx, so we use the 1-arg form.
+        history: list[ModelMessage] = agent._message_history
+        compacted_hashes: set[int] = agent._compacted_message_hashes
+
+        on_message_history_processor_start(
+            agent_name=getattr(agent, "name", None),
+            session_id=getattr(agent, "session_id", None),
+            message_history=list(history),
+            incoming_messages=list(messages),
+        )
+
+        existing_hashes = {hash_message(m) for m in history}
+        messages_added = 0
+        last_idx = len(messages) - 1
+        for i, msg in enumerate(messages):
+            h = hash_message(msg)
+            if h in existing_hashes:
+                continue
+            # Always keep the last (newest) message, even if its hash collides
+            # with a previously compacted one — short prompts like "yes"/"1"
+            # can collide and get silently dropped otherwise.
+            if i == last_idx or h not in compacted_hashes:
+                history.append(msg)
+                messages_added += 1
+
+        new_history, dropped = compact(
+            agent,
+            history,
+            agent._get_model_context_length(),
+            agent._estimate_context_overhead(),
+        )
+        agent._message_history = new_history
+        for m in dropped:
+            compacted_hashes.add(hash_message(m))
+
+        cleaned, filtered_count = _strip_empty_thinking_parts(agent._message_history)
+
+        # Ensure history ends with a ModelRequest — otherwise Anthropic etc.
+        # reject it with a "prefill" error.
+        while cleaned and isinstance(cleaned[-1], ModelResponse):
+            cleaned.pop()
+
+        # PERF-07: Only re-prune if we actually stripped thinking parts or
+        # popped trailing ModelResponse messages, since those operations can
+        # create orphaned tool_call/tool_return pairs.  If nothing was
+        # stripped or popped, the history is already clean from compact().
+        if filtered_count > 0 or len(cleaned) != len(agent._message_history):
+            cleaned = prune_interrupted_tool_calls(cleaned)
+
+        agent._message_history = cleaned
+
+        on_message_history_processor_end(
+            agent_name=getattr(agent, "name", None),
+            session_id=getattr(agent, "session_id", None),
+            message_history=list(cleaned),
+            messages_added=messages_added,
+            messages_filtered=len(messages) - messages_added + filtered_count,
+        )
+
+        return cleaned
+
+    return history_processor

code_muse/agents/_diagnostics.py

@@ -0,0 +1,171 @@
+"""Terminal-facing diagnostics for agent-run exceptions.
+
+When an agent run blows up, ``str(exc)`` alone loses almost all of the
+actionable signal that pydantic-ai / provider SDKs tuck onto ``__cause__``,
+``__context__``, ``BaseExceptionGroup.exceptions``, or attributes like
+``body`` / ``response`` / ``errors``. This module walks those paths in a
+bounded, defensive way and emits structured diagnostic blocks to the terminal.
+
+File-level logging (``log_error``) is untouched — this module only controls
+what we *surface* in the terminal for the user. All ``getattr`` access is
+guarded; diagnostic emit must never itself raise.
+"""
+
+from typing import Any
+
+from rich.text import Text
+
+from code_muse.error_logging import log_error
+from code_muse.messaging import emit_info
+
+# Python 3.11+ builtin; graceful fallback for 3.10
+try:
+    from builtins import BaseExceptionGroup  # type: ignore[attr-defined]
+except ImportError:  # pragma: no cover - 3.10 only
+    BaseExceptionGroup = Exception  # type: ignore[misc,assignment]
+
+# Only emit deep diagnostics for shapes that actually benefit. The boring 80%
+# of errors get the cheap path (one-line emit + log-file pointer).
+DIAGNOSTIC_TRIGGERS = ("output validation", "retries", "exceptiongroup")
+
+# Attributes commonly carrying the "real" story on provider/pydantic-ai errors.
+USEFUL_ATTRS = ("response", "body", "message", "detail", "errors")
+
+# Hard caps so a pathological exception tree can't flood the terminal.
+_MAX_CHAIN_DEPTH = 5
+_MAX_GROUP_LEAVES = 10
+
+
+def _safe_getattr(obj: Any, name: str) -> Any:
+    """``getattr`` that never raises, even on hostile descriptors."""
+    try:
+        return getattr(obj, name, None)
+    except Exception:  # pragma: no cover - defensive
+        return None
+
+
+def _emit_useful_attrs(exc: BaseException, group_id: str, indent: str) -> None:
+    """Emit any ``USEFUL_ATTRS`` present on ``exc`` as dim lines."""
+    for attr in USEFUL_ATTRS:
+        val = _safe_getattr(exc, attr)
+        if not val:
+            continue
+        try:
+            rendered = str(val)
+        except Exception:  # pragma: no cover - hostile __str__
+            rendered = f"<unrenderable {type(val).__name__}>"
+        emit_info(
+            Text.from_markup(f"[dim]{indent}{attr}: {rendered}[/dim]"),
+            group_id=group_id,
+        )
+
+
+def _emit_exception_chain(
+    exc: BaseException,
+    group_id: str,
+    depth: int = 0,
+    max_depth: int = _MAX_CHAIN_DEPTH,
+) -> None:
+    """Walk ``__cause__`` / ``__context__`` chains with a bounded depth."""
+    # Guard against cycles (rare but possible when users re-raise chains).
+    seen: set[int] = set()
+    current: BaseException | None = exc
+    current_depth = depth
+    while current is not None and current_depth < max_depth:
+        cause = _safe_getattr(current, "__cause__")
+        context = _safe_getattr(current, "__context__")
+        nxt = cause if cause is not None else context
+        if nxt is None or id(nxt) in seen:
+            return
+        seen.add(id(nxt))
+        label = "cause" if cause is not None else "context"
+        emit_info(
+            Text.from_markup(
+                f"[dim]  {'  ' * current_depth}{label}: "
+                f"{type(nxt).__name__}: {nxt}[/dim]"
+            ),
+            group_id=group_id,
+        )
+        _emit_useful_attrs(nxt, group_id, indent="    " + "  " * current_depth)
+        current = nxt
+        current_depth += 1
+
+
+def _needs_deep_diagnostics(exc: BaseException) -> bool:
+    """Return True when the cheap path would hide important detail."""
+    if isinstance(exc, BaseExceptionGroup):
+        return True
+    try:
+        msg = str(exc).lower()
+    except Exception:  # pragma: no cover - hostile __str__
+        return False
+    return any(trigger in msg for trigger in DIAGNOSTIC_TRIGGERS)
+
+
+def emit_exception_diagnostics(exc: BaseException, group_id: str) -> None:
+    """Emit terminal diagnostics for ``exc``, bounded and defensive.
+
+    Cheap path (always): one-line summary + log file write.
+    Deep path (only for ``ExceptionGroup``s or trigger-phrase messages):
+    cause/context chain + group leaves + useful attributes.
+
+    Never raises. Worst-case failure is a slightly noisier terminal during an
+    already-failed run.
+    """
+    try:
+        emit_info(f"Unexpected error: {exc}", group_id=group_id)
+    except Exception:  # pragma: no cover - emit should never fail
+        pass
+
+    # File logging is independent of terminal output and stays on the cheap path.
+    try:
+        log_error(
+            exc,
+            context=f"Agent run (group_id={group_id})",
+            include_traceback=True,
+        )
+    except Exception:  # pragma: no cover - logging failure must not cascade
+        pass
+
+    try:
+        if not _needs_deep_diagnostics(exc):
+            return
+
+        emit_info(
+            Text.from_markup("[yellow]Diagnostic detail:[/yellow]"),
+            group_id=group_id,
+        )
+        emit_info(
+            Text.from_markup(f"[dim]  Exception type: {type(exc).__name__}[/dim]"),
+            group_id=group_id,
+        )
+
+        _emit_exception_chain(exc, group_id)
+
+        if isinstance(exc, BaseExceptionGroup):
+            for i, sub in enumerate(exc.exceptions[:_MAX_GROUP_LEAVES], start=1):
+                emit_info(
+                    Text.from_markup(
+                        f"[yellow]  Sub-exception {i}: "
+                        f"{type(sub).__name__}: {sub}[/yellow]"
+                    ),
+                    group_id=group_id,
+                )
+                _emit_useful_attrs(sub, group_id, indent="    ")
+                # One level of nested cause on each leaf is usually enough.
+                _emit_exception_chain(sub, group_id, depth=1, max_depth=3)
+            extra = len(exc.exceptions) - _MAX_GROUP_LEAVES
+            if extra > 0:
+                emit_info(
+                    Text.from_markup(
+                        f"[dim]  ... and {extra} more sub-exception(s) omitted[/dim]"
+                    ),
+                    group_id=group_id,
+                )
+
+        _emit_useful_attrs(exc, group_id, indent="  ")
+    except Exception:  # pragma: no cover - diagnostics must never raise
+        pass
+
+
+__all__ = ["emit_exception_diagnostics"]