# Error-taxonomy propagation — structured LLM errors up to the UI

`reason`, `retryable`, and `retry_after_s` travel from the provider failure all
the way to the chat-turn error event, so the UI renders a categorized,
actionable error instead of an opaque string. This builds on the taxonomy in
`openprogram/providers/utils/errors.py`.

## 1. Why the structure must survive the trip

The taxonomy exists at the **provider-stream** layer: `providers/utils/errors.py`
defines `ErrorReason` (`transport / rate_limit / authentication / authorization /
context_length / content_policy / invalid_request / provider_internal /
unknown`), an `LLMError` carrying `reason` + `retry_after_s`, and
`classify(exc) -> (reason, retryable)`. `stream_retry` uses it to drive backoff.

If the structure is flattened to `str(exc)` above that layer — the agent loop
catching a failure, or a chat-turn error event shaped as
`{"type": "error", "content": "<string>"}` — the UI cannot tell apart:

- a **rate limit** (retryable — show "retrying in Ns", maybe auto-retry) from
- an **auth** failure (fatal — "check your API key / re-login") from
- a **context-length** overflow (fatal — "the conversation is too long; compact
  or start a new chat") from
- a transient **provider_internal** (retryable).

Every failure then looks like the same red string, and no affordance can be
offered because nothing knows what kind of failure it was.

The scope is the **main chat-turn streaming error**. Operational error strings
(retry and compact-failure messages) stay plain.

## 2. Design

1. **Classify at the agent error boundary.** Where the agent turn catches a
   stream failure, if it's an `LLMError` use its `reason` / `retry_after_s`;
   otherwise run `errors.classify(exc)` to derive `(reason, retryable)`. Carry
   these on the error the agent surfaces (a small structured error object, not a
   bare string).
2. **Widen the chat-turn error event.** The webui error payload becomes
   `{"type": "error", "content": <human string>, "reason": <ErrorReason>,
   "retryable": <bool>, "retry_after_s": <float|null>}`. `content` stays for
   back-compat; the new fields are additive.
3. **Frontend renders by reason.** A categorized error chip maps reason →
   actionable copy + affordance:
   - `rate_limit` → "Rate limited — retrying in {retry_after_s}s" (and, if a
     retry policy exists, an auto-retry/▸ countdown).
   - `authentication`/`authorization` → "Your {provider} key was rejected —
     check it in Settings → Providers."
   - `context_length` → "This conversation is too long — compact it or start a
     new chat."
   - `content_policy` → "The provider blocked this request (content policy)."
   - `provider_internal`/`transport` → "Temporary provider/network error — try
     again." (retryable styling)
   - `invalid_request`/`unknown` → the raw `content` (fallback).

## 3. Where the classification happens

A chat failure is caught at three layers, and each classifies via
`taxonomy_fields` and emits `reason / retryable / retry_after_s`:

- `agent.py` — the `Agent` class boundary, used by the Agent run.
- `_execute/__init__.py` outer except — the action-level error.
- `dispatcher.py` — the common path for the webui chat turn, which runs through
  the dispatcher's `_run_loop_blocking`. The failure is caught in the
  dispatcher's own except, and the reason flows through `TurnResult`
  (`error_reason` / `error_retryable` / `error_retry_after_s`) into both the
  in-run dispatcher error event and the post-run `chat.py` broadcast.

The frontend side is `assistant-bubble.tsx`, which renders the categorized
headline keyed off `errorReason` with the raw message below;
`ChatResponseData` and `ChatMsg` carry the fields, and `finalize()` captures
them.

Classification is worth doing at the backend boundary on its own terms: API
consumers, logs, and other channels all read the reason, independent of what
the chat UI does with it.

## 4. Verification

Induce each reason and confirm the WS payload's `reason` / `retryable` and the
UI render: a rejected key gives `authentication`, fatal, "check your key"; a 429
gives `rate_limit`, retryable, with the retry hint; an oversized context gives
`context_length`, fatal, "compact". `errors.classify` has unit coverage of the
mapping, alongside a test that the agent boundary preserves an `LLMError`'s
reason unchanged.

Reproducing a deterministic provider failure end to end is the awkward part: the
frontend sends its own selected model rather than the agent default, so changing
the agent model does not change what is exercised. A repeatable failure on the
selected model is what confirms the live render — an expired key for `auth`, or
an OpenRouter `:free` model that 503s for `provider`.

## 5. Limits

The persisted error node carries only the string, not the reason; the taxonomy
travels on the live broadcast. Rendering a categorized error after a reload
would require the stored node to carry the taxonomy too.

## 6. Non-goals

Not a rewrite of the ~991 `except Exception` sites — only the chat-turn LLM
error path is classified-and-surfaced. The blanket-except audit is separate.
Not an auto-retry policy change; this only *exposes* `retryable`/`retry_after_s`
so the UI (and any future policy) can act on it.