Skip to content

feat(*): extend provider error guidance to channels, tui, and transcription #336

Open

Description

@0xKT

Problem

Provider errors are normalized into a canonical single-line form (built by format_llm_error, machine-parseable via parse_llm_error in raven/providers/base.py:116 and :145), and the CLI one-shot path renders them as a friendly diagnosis plus a Fix hint with a nonzero exit. Other surfaces did not get the same treatment:

  1. Channels and the TUI deliver the raw canonical line, e.g. Error calling LLM (auth@openrouter): AuthenticationError: ... User not found. This is better than the old raw exception dump, but has no category-appropriate hint and no Fix line.
  2. Missing-credential remedies travel to the TUI as a raw remedy string that tells the user to run terminal commands, which is awkward inside the TUI.
  3. Groq transcription with no API key only logs "Groq API key not configured for transcription" and silently returns an empty transcript, so the user just sees the agent ignore their voice message with no hint about where to configure the key.

Evidence

  • parse_llm_error is consumed only by raven/cli/agent_commands.py:76; no channel or TUI rendering path uses it.
  • raven/cli/tui_commands.py:528 and raven/tui_rpc/methods/config.py:345 forward the remedy text verbatim into RPC error data.
  • raven/providers/transcription.py:31 warns and returns "" with no fix guidance.
  • Auth error rendering deliberately avoids naming a specific HTTP status (401 vs 403 cannot be distinguished from the exception across providers), so the line currently says the provider rejected the credentials without a status.

Suggested direction

  • Reuse parse_llm_error in the channel outlet and TUI rendering so every surface gets the same category-based diagnosis plus a surface-appropriate hint (channels can point at gateway/provider config; the TUI can point at its own config screen instead of terminal commands).
  • Give the transcription no-key warning the same one-line fix hint the chat path has.
  • If showing the real HTTP status is ever wanted: a sketched design exists where format_llm_error extracts the status from the live exception into the canonical header ((<category>[@<provider>][ <status>])), parse_llm_error returns it as an extra field, and the render layer chooses between the real value and a neutral word. That keeps the status truthful end to end instead of hardcoding one in the renderer.

Activity

  1. joei4cm commented on Nov 7, 2026

    @joei4cm
    Contributor

    Taking the parts of this that are still open, unless someone has started.

    Re-reading the tree today, item 1 looks largely done since the report: parse_llm_error now also feeds gateway/spine.py and agent/loop/turn_path.py, so channel replies already carry the parsed summary. What I still see open:

    • Item 2: rpc/methods/config.py (the error arms around lines 553 and 634) forwards the remedy payload as raw data, and the TUI renders whatever sentence it gets; the terminal-command remedy reads oddly inside the TUI and there is no category-appropriate hint.
    • Item 3: providers/transcription.py:38 still warns and returns an empty transcript, so a voice message on an install without a Groq key looks ignored.

    Plan: structure the remedy and hint payload the TUI renders (mapping categories to the fix hints the CLI one-shot path already uses, and phrasing remedies so they work inside the TUI), and make the missing transcription key surface as a visible diagnosis with its fix. Tests per surface, following the CLI shape. If you read item 1 as still open somewhere specific, point me at it and I will take that too.

  2. joei4cm commented on Nov 17, 2026

    @joei4cm
    Contributor

    The channel half of item 1 is now an open PR: #1342.

    The fix hint for a failed model call lived in the CLI alone -- raven/cli/agent_commands.py held a table of category-apt hints next to the renderer that used it. A chat reader got the failure's category and endpoint and nothing else, so a rate limit reached the room as a sentence with nothing to do about it.

    #1342 moves that knowledge into one module (raven/providers/error_hints.py) and lets each surface ask for the wording it can honour: the CLI keeps the wording it had, and a chat gets what its reader can act on -- "Try again in a moment." for a rate limit, "The operator can check the provider key." for a rejected key -- with no command in it, since nobody in a chat can run one on the operator's behalf. The provider's own account stays in the operator's log, as before.

    What is left on this issue: the TUI half of item 1 and item 2. The TUI's error event carries no hint field, and the credential remedy arrives as raw terminal commands. Both are wire changes -- the error event in rpc-schema/openrpc.json, the regenerated clients, and the TUI's rendering -- so they land as their own change.

  3. joei4cm commented on Nov 17, 2026

    @joei4cm
    Contributor

    The TUI half of item 1 has landed in #1342, which now covers all three surfaces rather than the channel alone.

    Before this, the error event carried the canonical detail and no advice, so a rejected key read as Turn failed - Error calling LLM (auth@openrouter): ... and stopped there -- the reader was told what failed and nothing about what to do. emit_error now takes the advice and the failed-turn sink derives it from the failure's category, so the TUI closes the line with "Open Settings to check the provider key." for a rejected key. That is the one wording difference from the chat: it names the screen the TUI owns instead of a command nobody there can run. Every other category reads as it does in a chat, and a crash carries no category, so it gets no advice rather than a guessed one.

    The wire gained an optional hint field on the error event (rpc-schema/openrpc.json, raven/rpc/models.py, both generated clients), optional on both sides: an older client ignores it, and a newer runtime talking to an older client omits it.

    Item 1 is therefore complete across the CLI, the channel and the TUI. What is left on this issue:

    • Item 2: the credential remedy. rpc/methods/config.py forwards it as raw data and neither client renders it -- ui-web's remedy parser expects a structured dict, so the actionable sentence never reaches the screen at all. This needs a client-side decision about the payload's shape and is a separate change.
    • Item 3: providers/transcription.py:38 still warns and returns an empty transcript, so a voice message on an install without a Groq key looks ignored.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions