iCode-TUI 0.29.1__py3-none-any.whl

chrys/foundation/errors/_walk.py

@@ -0,0 +1,85 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Exception-graph walks shared by the error classifier and formatter.
+
+Two walks with different trust:
+
+* :func:`iter_full_chain` follows ``__cause__`` and unsuppressed
+  ``__context__``.  Implicit context can be stale — an exception that was
+  being handled when a fresh request failed — so only the legacy retry layers
+  and the owner-terminal veto read it.
+* :func:`iter_explicit_graph` follows only edges a raiser set on purpose:
+  ``__cause__``, exceptions held in ``args`` (httpcore keeps its root cause in
+  ``args[0]`` after ``raise ... from None``; ``ChatClientException`` keeps its
+  inner exception in ``args[1]``) and exception-group members.  It never
+  follows ``__context__`` and does not descend below a node whose request got
+  an HTTP response: anything deeper belongs to response processing, not to
+  this request's failure.  Every classification rule other than the legacy
+  layers reads this walk.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+
+def iter_full_chain(exc: BaseException, *, unwrap_single_groups: bool = False) -> Iterator[BaseException]:
+    """Yield an exception and its explicit/implicit cause chain."""
+    seen: set[int] = set()
+    cur: BaseException | None = exc
+    while cur is not None and id(cur) not in seen:
+        yield cur
+        seen.add(id(cur))
+        if unwrap_single_groups and isinstance(cur, BaseExceptionGroup) and len(cur.exceptions) == 1:
+            cur = cur.exceptions[0]
+        else:
+            cur = (
+                cur.__cause__ if cur.__cause__ is not None else (None if cur.__suppress_context__ else cur.__context__)
+            )
+
+
+def has_response_status(exc: BaseException) -> bool:
+    """Return whether *exc* proves that its request received an HTTP response."""
+    if getattr(exc, "status_code", None) is not None:
+        return True
+    response = getattr(exc, "response", None)
+    return response is not None and getattr(response, "status_code", None) is not None
+
+
+def explicit_children(exc: BaseException) -> list[BaseException]:
+    """Return *exc*'s explicit children: cause, exceptions in ``args``, group members."""
+    children: list[BaseException] = []
+    if exc.__cause__ is not None:
+        children.append(exc.__cause__)
+    children.extend(arg for arg in exc.args if isinstance(arg, BaseException))
+    if isinstance(exc, BaseExceptionGroup):
+        children.extend(exc.exceptions)
+    return children
+
+
+def iter_explicit_graph(exc: BaseException) -> Iterator[BaseException]:
+    """Yield *exc* and its explicit causes depth-first, pre-order.
+
+    Children are visited cause first, then exceptions in ``args``, then group
+    members.  Each exception is yielded once, so cycles terminate.
+    """
+    seen: set[int] = set()
+    stack: list[BaseException] = [exc]
+    while stack:
+        node = stack.pop()
+        if id(node) in seen:
+            continue
+        seen.add(id(node))
+        yield node
+        if has_response_status(node):
+            continue
+        stack.extend(reversed(explicit_children(node)))
+
+
+def request_of(exc: BaseException) -> object | None:
+    """Return the HTTP request an SDK or httpx exception carries, if any."""
+    try:
+        # httpx raises RuntimeError from ``.request`` when none was attached.
+        return getattr(exc, "request", None)
+    except RuntimeError:
+        return None

chrys/foundation/errors/classify.py

@@ -0,0 +1,278 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""The one error classifier: kind and retry decision from one pass.
+
+Invariant: apart from the two legacy rules (the owner-terminal veto and the
+transient layers), everything that sets ``kind`` or overrides ``retryable``
+reads only the explicit graph (:func:`iter_explicit_graph`).  An exception
+left in ``__context__`` from an earlier request — a stale 413 or quota error
+being handled when a fresh request failed — can neither steer the retry
+decision nor the kind shown to the user.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from . import _legacy
+from ._text import _clean_exception_text
+from ._walk import iter_explicit_graph, iter_full_chain
+from .kinds import ErrorKind, TimeoutPhase
+from .network import NetworkFailure, classify_connection_failure
+from .provider import (
+    ContinuationVerdictError,
+    ProviderResponseError,
+    ProviderSignal,
+    in_band_failure_retryable,
+    is_2xx,
+    named_context_limit,
+    names_context_overflow,
+    names_server_error_overflow,
+    provider_signal,
+    signal_kind,
+    status_kind,
+    stream_error_retryable,
+)
+from .route import RouteFacts, route_of
+
+
+@dataclass(frozen=True, slots=True)
+class ErrorClassification:
+    """What an exception means for retry policy and for the user."""
+
+    kind: ErrorKind
+    retryable: bool
+    signal: ProviderSignal | None = None
+    timeout_phase: TimeoutPhase | None = None
+    # The failed request's route snapshot, when its client stamped one.
+    route: RouteFacts | None = None
+    # A TCP or DNS answer shows the first hop (the proxy, or the target when
+    # direct) itself failed.
+    failed_at_first_hop: bool = False
+    # The model service itself answered: only the LLM client stamps a route,
+    # and model-response types are raised only for its responses.  Another
+    # client's HTTP status (an MCP server's 401) classifies the same way but
+    # says nothing about the model service.
+    from_model_service: bool = False
+    invalidates_continuation_token: bool = False
+    # Log-only trace of the deciding evidence, e.g. ``"http 429"``.
+    evidence: str = ""
+
+
+# Matched by class name anywhere in the MRO: the owning classes live in
+# higher tiers than foundation.
+_TYPE_KINDS = (
+    (frozenset({"StreamStall", "StreamStallExhausted"}), ErrorKind.STREAM_STALLED),
+    (frozenset({"ChatClientContentFilterException", "AgentContentFilterException"}), ErrorKind.CONTENT_FILTERED),
+    (
+        frozenset({"ChatClientInvalidResponseException", "AgentInvalidResponseException", "ResponseValidationError"}),
+        ErrorKind.INVALID_RESPONSE,
+    ),
+)
+
+# httpx and httpcore timeouts, by class name.
+_TIMEOUT_PHASES: dict[str, TimeoutPhase] = {
+    "ConnectTimeout": "connect",
+    "WriteTimeout": "write",
+    "ReadTimeout": "read",
+    "PoolTimeout": "pool",
+}
+_TIMEOUT_MODULES = frozenset({"httpx", "httpcore"})
+
+# What Anthropic says when replayed thinking no longer matches the conversation before it.
+_THINKING_BINDING_PHRASE = "bound to a different conversation"
+
+# Kinds no retry can fix, whatever the transient layers say.
+_NON_RETRYABLE_KINDS = frozenset({ErrorKind.QUOTA_EXHAUSTED, ErrorKind.CONTEXT_OVERFLOW, ErrorKind.PAYLOAD_TOO_LARGE})
+
+
+def _status_code(exc: BaseException) -> int | None:
+    status = getattr(exc, "status_code", None)
+    if isinstance(status, int):
+        return status
+    response = getattr(exc, "response", None)
+    status = getattr(response, "status_code", None) if response is not None else None
+    return status if isinstance(status, int) else None
+
+
+def _type_kind(exc: BaseException) -> ErrorKind | None:
+    names = {cls.__name__ for cls in type(exc).__mro__}
+    return next((kind for type_names, kind in _TYPE_KINDS if names & type_names), None)
+
+
+def _timeout_phase(exc: BaseException) -> TimeoutPhase | None:
+    for cls in type(exc).__mro__:
+        if cls.__module__.partition(".")[0] in _TIMEOUT_MODULES and cls.__name__ in _TIMEOUT_PHASES:
+            return _TIMEOUT_PHASES[cls.__name__]
+    return None
+
+
+def _first_timeout_phase(explicit: tuple[BaseException, ...]) -> TimeoutPhase | None:
+    return next((phase for node in explicit if (phase := _timeout_phase(node)) is not None), None)
+
+
+def _explicit_kind(
+    explicit: tuple[BaseException, ...],
+    signal: ProviderSignal | None,
+    network: NetworkFailure | None,
+    overflow: bool,
+) -> tuple[ErrorKind, str]:
+    """Return the kind explicit evidence names: provider signal, then network leaf, then node types."""
+    if overflow:
+        return ErrorKind.CONTEXT_OVERFLOW, "context overflow"
+    if signal is not None:
+        kind, evidence = signal_kind(signal)
+        if kind is not ErrorKind.UNKNOWN:
+            return kind, evidence
+    if network is not None and network.kind is not ErrorKind.UNKNOWN:
+        return network.kind, network.evidence
+    for node in explicit:
+        if node is not (signal.source if signal is not None else None) and (status := _status_code(node)) is not None:
+            return status_kind(status), f"http {status}"
+        if (kind := _type_kind(node)) is not None:
+            return kind, f"type {type(node).__name__}"
+    return ErrorKind.UNKNOWN, ""
+
+
+def _from_model_service(explicit: tuple[BaseException, ...], route: RouteFacts | None) -> bool:
+    return route is not None or any(
+        isinstance(node, ProviderResponseError) or _type_kind(node) is not None for node in explicit
+    )
+
+
+def _invalidates_continuation_token(explicit: tuple[BaseException, ...]) -> bool:
+    return any(isinstance(node, ContinuationVerdictError) and node.invalidates_continuation_token for node in explicit)
+
+
+def classify_error(exc: BaseException) -> ErrorClassification:
+    """Classify *exc* for retry policy and display."""
+    explicit = tuple(iter_explicit_graph(exc))
+    route = route_of(explicit)
+    signal = provider_signal(explicit)
+    network = classify_connection_failure(exc, route)
+    overflow = names_context_overflow(
+        signal, (_clean_exception_text(node) for node in explicit if _type_kind(node) is None)
+    )
+    kind, evidence = _explicit_kind(explicit, signal, network, overflow)
+    # The full chain feeds only the frozen legacy layers.
+    full = tuple(iter_full_chain(exc))
+    if _legacy.is_owner_terminal(full):
+        retryable = False
+    elif signal is not None and signal.explicit_retryable is not None:
+        retryable = signal.explicit_retryable
+    elif (
+        (network is not None and network.deterministic)
+        or kind in _NON_RETRYABLE_KINDS
+        or _names_a_final_in_band_failure(signal)
+    ):
+        retryable = False
+    elif signal is not None and is_2xx(signal.status_code):
+        retryable = stream_error_retryable(signal)
+    else:
+        # The legacy owner and deterministic vetoes were both decided above.
+        retryable = _legacy.is_transient(full)
+    return ErrorClassification(
+        kind=kind,
+        retryable=retryable,
+        signal=signal,
+        timeout_phase=(network.timeout_phase if network is not None else None) or _first_timeout_phase(explicit),
+        route=route,
+        failed_at_first_hop=network is not None and network.first_hop_evidence,
+        from_model_service=_from_model_service(explicit, route),
+        invalidates_continuation_token=_invalidates_continuation_token(explicit),
+        evidence=evidence,
+    )
+
+
+def _names_a_final_in_band_failure(signal: ProviderSignal | None) -> bool:
+    """Whether *signal* is an error a stream reported in-band whose code a retry meets again.
+
+    The OpenAI SDK raises an error event inside a stream as a bare
+    ``APIError`` with no status: its code gets the verdict an adapter gives
+    the same failure (:func:`in_band_failure_retryable`). A veto only: an
+    unknown code keeps the retry it had.
+    """
+    return (
+        signal is not None
+        and signal.status_code is None
+        and signal.code is not None
+        and not in_band_failure_retryable(signal.code)
+    )
+
+
+def is_retryable(e: BaseException) -> bool:
+    """Check if an exception is a transient error worth retrying."""
+    return classify_error(e).retryable
+
+
+def is_context_overflow(exc: BaseException) -> bool:
+    """Return whether the provider rejected the request for exceeding the context window.
+
+    ``request_too_large`` / 413 is an oversized payload, not an overflow.
+    """
+    return classify_error(exc).kind is ErrorKind.CONTEXT_OVERFLOW
+
+
+def is_thinking_binding_rejection(exc: BaseException) -> bool:
+    """Return whether Anthropic refused replayed thinking as bound to a different conversation.
+
+    The service binds each signed thinking block to the request before it and
+    answers a changed one with a 400 ``invalid_request_error`` saying so. All
+    three are read from the one provider signal: a gateway that rewrites the
+    text is missed rather than every invalid request caught. The text may
+    also name the context window, so *exc* can be an overflow as well.
+    """
+    signal = classify_error(exc).signal
+    return (
+        signal is not None
+        and signal.status_code == 400
+        and signal.error_type == "invalid_request_error"
+        and signal.message is not None
+        and _THINKING_BINDING_PHRASE in signal.message
+    )
+
+
+def context_overflow_limit(exc: BaseException) -> int | None:
+    """Return the window limit, in tokens, the provider named when it rejected the request as too long.
+
+    Read only from the text that made *exc* an overflow: the provider
+    signal's own, or without one the explicit nodes' (never ``__context__``).
+    None when *exc* is no overflow or names no single positive limit.
+    """
+    result = classify_error(exc)
+    if result.kind is not ErrorKind.CONTEXT_OVERFLOW:
+        return None
+    if (signal := result.signal) is not None:
+        return named_context_limit((signal.message or "", _clean_exception_text(signal.source)))
+    return named_context_limit(
+        _clean_exception_text(node) for node in iter_explicit_graph(exc) if _type_kind(node) is None
+    )
+
+
+def may_be_context_overflow(exc: BaseException) -> bool:
+    """Return whether *exc* is, or may be, a context-window rejection.
+
+    Only for a caller whose false positive merely shrinks its input, such as
+    compaction's last-words shrink sequence: beyond :func:`is_context_overflow`,
+    a 5xx whose text names the context window counts, since a gateway may wrap
+    an overflow in one.  Retry policy, display and the main turn use
+    :func:`is_context_overflow`, which leaves that 5xx retryable.
+    """
+    classification = classify_error(exc)
+    if classification.kind is ErrorKind.CONTEXT_OVERFLOW:
+        return True
+    return classification.signal is not None and names_server_error_overflow(classification.signal)
+
+
+def invalidates_continuation_token(exc: BaseException) -> bool:
+    """Return whether *exc* judged a terminal response, so a retry must not re-poll it.
+
+    A type check over the explicit graph alone: every failed wire call asks,
+    and the retry policy classifies separately.
+    """
+    return _invalidates_continuation_token(tuple(iter_explicit_graph(exc)))
+
+
+def is_read_timeout(exc: BaseException) -> bool:
+    """Return whether *exc* is a read timeout (connect, write and pool timeouts aren't)."""
+    return classify_error(exc).timeout_phase == "read"

chrys/foundation/errors/display.py

@@ -0,0 +1,274 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""What a classified error means to the user, as locale-neutral display messages.
+
+Producers attach :func:`display_fields` to failure events; frontends render
+the message and hint in the current locale and join them with
+:data:`DISPLAY_WITH_HINT`.  The raw English text (``clean_error_message``)
+stays on the event for the model, logs, ACP and the detail line.  Kinds with
+nothing more useful to say than the raw text (a rejected request, an invalid
+response, an unknown failure) describe as None, and so does any failure the
+model service didn't answer: a network failure without a route snapshot (only
+the LLM client stamps one) or another client's HTTP status.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from chrys.foundation.branding import APP_DISPLAY_NAME
+from chrys.foundation.i18n import MessageDef, MessageRef, msg
+from chrys.foundation.net.route_probe import default_route_available, is_local_target
+
+from .classify import ErrorClassification, classify_error, context_overflow_limit
+from .kinds import NETWORK_KINDS, ErrorKind
+from .route import Origin
+
+logger = logging.getLogger(__name__)
+
+_NO_ROUTE = msg(
+    "error.kind.no_route",
+    fallback="Can't reach the network: there is no route to {host}. Check your network connection or VPN.",
+)
+_DNS_FAILED = msg(
+    "error.kind.dns_failed",
+    fallback=(
+        "Can't resolve {host}. Check your network connection and DNS; "
+        "if the address is wrong, fix the base URL in the model profile."
+    ),
+)
+_HOST_UNREACHABLE = msg(
+    "error.kind.host_unreachable",
+    fallback="Can't reach {host}: the host is unreachable. Check your network, VPN, or firewall.",
+)
+_CONNECTION_REFUSED = msg(
+    "error.kind.connection_refused",
+    fallback="{host} refused the connection. Check the address and port, and that the service is running.",
+)
+_CONNECT_TIMEOUT = msg(
+    "error.kind.connect_timeout", fallback="Connecting to {host} timed out. Check your network and firewall."
+)
+_CONNECTION_FAILED = msg(
+    "error.kind.connection_failed", fallback="Couldn't connect to {host}. Check your network connection."
+)
+_CONNECTION_LOST = msg("error.kind.connection_lost", fallback="The connection to {host} was interrupted.")
+_READ_TIMEOUT = msg("error.kind.read_timeout", fallback="Timed out waiting for a response from {host}.")
+_WRITE_TIMEOUT = msg("error.kind.write_timeout", fallback="Timed out sending the request to {host}.")
+_NETWORK_GENERIC = msg(
+    "error.kind.network_generic",
+    fallback="Couldn't connect to the model service. Check your network and proxy settings.",
+)
+_PROXY_UNREACHABLE = msg(
+    "error.kind.proxy_unreachable",
+    fallback=(
+        "Can't connect to the proxy {proxy}. Check that the proxy is running and configured correctly, "
+        'or turn on "Bypass proxy" in the model profile.'
+    ),
+)
+_PROXY_REJECTED = msg("error.kind.proxy_rejected", fallback="The proxy {proxy} couldn't connect to {host}.")
+_VIA_PROXY_FAILED = msg(
+    "error.kind.via_proxy_failed",
+    fallback="Connecting to {host} through the proxy {proxy} failed. Check the proxy and your network connection.",
+)
+_PROXY_AUTH_FAILED = msg(
+    "error.kind.proxy_auth_failed",
+    fallback="The proxy {proxy} requires authentication or rejected the credentials.",
+)
+_TLS_FAILED = msg(
+    "error.kind.tls_failed",
+    fallback=(
+        "Couldn't establish a secure connection to {host}: the certificate isn't trusted or the protocol "
+        "doesn't match. On a corporate network, check the proxy certificate setup."
+    ),
+)
+_INVALID_ENDPOINT = msg(
+    "error.kind.invalid_endpoint",
+    fallback="The service address is invalid. Check the base URL in the model profile.",
+)
+_RATE_LIMITED = msg("error.kind.rate_limited", fallback="The model service is rate limiting requests.")
+_QUOTA_EXHAUSTED = msg(
+    "error.kind.quota_exhausted",
+    fallback="The model service account is out of quota or credit. Check the account and try again.",
+)
+_OVERLOADED = msg("error.kind.overloaded", fallback="The model service is overloaded.")
+_SERVER_ERROR = msg("error.kind.server_error", fallback="The model service returned an internal error.")
+_CONTEXT_OVERFLOW = msg(
+    "error.kind.context_overflow",
+    fallback=(
+        "The request exceeds the model's context window. "
+        "Check that the profile's context window matches the model's real one."
+    ),
+)
+_CONTEXT_OVERFLOW_CONFIG_MISMATCH = msg(
+    "error.kind.context_overflow_config_mismatch",
+    fallback=(
+        "The model profile's maximum context window ({configured_max_context_tokens}) is larger than the server's "
+        'limit ({server_max_context_tokens}). Set "Max Context Window" in the model profile '
+        "to {server_max_context_tokens} or less."
+    ),
+)
+_PAYLOAD_TOO_LARGE = msg(
+    "error.kind.payload_too_large",
+    fallback="The request is too large (for example, an image or attachment). Make it smaller and try again.",
+)
+_AUTH_FAILED = msg(
+    "error.kind.auth_failed",
+    fallback="The API key is invalid or lacks access. Check the API key in the model profile.",
+)
+_CONTENT_FILTERED = msg(
+    "error.kind.content_filtered", fallback="The model service's content filter blocked this request."
+)
+_STREAM_TRUNCATED = msg("error.kind.stream_truncated", fallback="The model's response was cut off.")
+_STREAM_STALLED = msg("retry.stream_stalled", fallback="Stream stalled")
+_CONTEXT_OVERFLOW_RESEND = msg(
+    "retry.context_overflow", fallback="The context window is full. Compacting the context before one retry."
+)
+# The probe checks the device {app} runs on: under ``icode serve`` that is the
+# server, not the device showing the browser.
+_MAYBE_OFFLINE = msg(
+    "error.hint.maybe_offline",
+    fallback="The device running {app} doesn't seem to have a network connection. Check it first.",
+)
+DISPLAY_WITH_HINT = msg("error.display.with_hint", fallback="{message} {hint}")
+"""Joins a rendered message and its rendered hint; zh-Hans joins without a space."""
+
+# Messages that name the target host.  TLS keeps its own wording through a
+# proxy: an untrusted certificate is usually the proxy's own.
+_HOST_MESSAGES: dict[ErrorKind, MessageDef] = {
+    ErrorKind.NO_ROUTE: _NO_ROUTE,
+    ErrorKind.DNS_FAILED: _DNS_FAILED,
+    ErrorKind.HOST_UNREACHABLE: _HOST_UNREACHABLE,
+    ErrorKind.CONNECTION_REFUSED: _CONNECTION_REFUSED,
+    ErrorKind.CONNECT_TIMEOUT: _CONNECT_TIMEOUT,
+    ErrorKind.CONNECTION_FAILED: _CONNECTION_FAILED,
+    ErrorKind.CONNECTION_LOST: _CONNECTION_LOST,
+    ErrorKind.READ_TIMEOUT: _READ_TIMEOUT,
+    ErrorKind.WRITE_TIMEOUT: _WRITE_TIMEOUT,
+    ErrorKind.TLS_FAILED: _TLS_FAILED,
+}
+# The model service's own answers, shown only when it answered.
+_HOSTLESS_MESSAGES: dict[ErrorKind, MessageDef] = {
+    ErrorKind.RATE_LIMITED: _RATE_LIMITED,
+    ErrorKind.QUOTA_EXHAUSTED: _QUOTA_EXHAUSTED,
+    ErrorKind.OVERLOADED: _OVERLOADED,
+    ErrorKind.SERVER_ERROR: _SERVER_ERROR,
+    ErrorKind.CONTEXT_OVERFLOW: _CONTEXT_OVERFLOW,
+    ErrorKind.PAYLOAD_TOO_LARGE: _PAYLOAD_TOO_LARGE,
+    ErrorKind.AUTH_FAILED: _AUTH_FAILED,
+    ErrorKind.CONTENT_FILTERED: _CONTENT_FILTERED,
+    ErrorKind.STREAM_TRUNCATED: _STREAM_TRUNCATED,
+}
+# Failures an offline machine produces; refused, unreachable and no-route
+# already name their cause.
+_PROBED_KINDS = frozenset({ErrorKind.DNS_FAILED, ErrorKind.CONNECT_TIMEOUT, ErrorKind.CONNECTION_FAILED})
+_DEFAULT_PORTS = {"http": 80, "https": 443}
+
+
+@dataclass(frozen=True, slots=True)
+class ErrorDescription:
+    """A classified error's display message, plus an optional hint shown after it."""
+
+    kind: ErrorKind
+    message: MessageRef
+    hint: MessageRef | None = None
+
+
+def _label(origin: Origin, *, with_port: bool) -> str:
+    host = f"[{origin.host}]" if ":" in origin.host else origin.host
+    return f"{host}:{origin.port}" if with_port else host
+
+
+def _host(origin: Origin) -> str:
+    """The target as the user wrote it: the port only when it isn't the scheme's default."""
+    return _label(origin, with_port=_DEFAULT_PORTS.get(origin.scheme) != origin.port)
+
+
+def _proxy(origin: Origin) -> str:
+    return _label(origin, with_port=True)
+
+
+def _describe_network(result: ErrorClassification, route_probe: Callable[[], bool | None]) -> ErrorDescription | None:
+    kind = result.kind
+    route = result.route
+    if route is None:
+        return None
+    if kind is ErrorKind.INVALID_ENDPOINT:
+        return ErrorDescription(kind, _INVALID_ENDPOINT.bind())
+    host = _host(route.target)
+    if route.proxy is not None:
+        proxy = _proxy(route.proxy)
+        if kind is ErrorKind.PROXY_AUTH_FAILED:
+            return ErrorDescription(kind, _PROXY_AUTH_FAILED.bind(proxy=proxy))
+        if kind is ErrorKind.PROXY_REJECTED:
+            return ErrorDescription(kind, _PROXY_REJECTED.bind(host=host, proxy=proxy))
+        if result.failed_at_first_hop:
+            return ErrorDescription(kind, _PROXY_UNREACHABLE.bind(proxy=proxy))
+        if kind is ErrorKind.TLS_FAILED:
+            return ErrorDescription(kind, _TLS_FAILED.bind(host=host))
+        # Timeouts, a dropped tunnel, a lost connection: which hop failed is unknown.
+        return ErrorDescription(kind, _VIA_PROXY_FAILED.bind(host=host, proxy=proxy))
+    definition = _HOST_MESSAGES.get(kind)
+    if definition is None:
+        # A proxy verdict with no proxy on the route.
+        return ErrorDescription(kind, _NETWORK_GENERIC.bind())
+    hint = None
+    if kind in _PROBED_KINDS and not is_local_target(route.target.host) and route_probe() is False:
+        hint = _MAYBE_OFFLINE.bind(app=APP_DISPLAY_NAME)
+    return ErrorDescription(kind, definition.bind(host=host), hint)
+
+
+def describe_error(
+    exc: BaseException,
+    *,
+    route_probe: Callable[[], bool | None] = default_route_available,
+    retry_notice: bool = False,
+    max_context_tokens: int | None = None,
+) -> ErrorDescription | None:
+    """Describe *exc* for the user, or None when the raw text is the best description.
+
+    *route_probe* runs only for a direct request to a public host that
+    failed to resolve or connect; it adds a hint and never changes the
+    message.  A *retry_notice* also names a stalled stream; a paused
+    sub-agent's card already labels a stall by its pause reason.  A retry
+    notice for a context overflow is the one resend after compacting.
+    *max_context_tokens*, the failed request's configured window, lets an
+    overflow whose provider names a smaller limit say which value to set.
+    """
+    result = classify_error(exc)
+    kind = result.kind
+    if kind is ErrorKind.STREAM_STALLED and retry_notice:
+        return ErrorDescription(kind, _STREAM_STALLED.bind())
+    if kind is ErrorKind.CONTEXT_OVERFLOW and retry_notice:
+        return ErrorDescription(kind, _CONTEXT_OVERFLOW_RESEND.bind())
+    if (definition := _HOSTLESS_MESSAGES.get(kind)) is not None:
+        if not result.from_model_service:
+            return None
+        if kind is ErrorKind.CONTEXT_OVERFLOW and max_context_tokens is not None:
+            limit = context_overflow_limit(exc)
+            if limit is not None and limit < max_context_tokens:
+                return ErrorDescription(
+                    kind,
+                    _CONTEXT_OVERFLOW_CONFIG_MISMATCH.bind(
+                        configured_max_context_tokens=max_context_tokens, server_max_context_tokens=limit
+                    ),
+                )
+        return ErrorDescription(kind, definition.bind())
+    if kind in NETWORK_KINDS:
+        return _describe_network(result, route_probe)
+    return None
+
+
+def display_fields(
+    exc: BaseException, *, retry_notice: bool = False, max_context_tokens: int | None = None
+) -> tuple[MessageRef | None, MessageRef | None]:
+    """Return ``(display_message, display_hint)`` for a failure event; ``(None, None)`` on any internal error."""
+    try:
+        description = describe_error(exc, retry_notice=retry_notice, max_context_tokens=max_context_tokens)
+    except Exception:
+        logger.debug("Describing an error for display failed", exc_info=True)
+        return None, None
+    if description is None:
+        return None, None
+    return description.message, description.hint