You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
feat(*): extend provider error guidance to channels, tui, and transcription #336
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:
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.
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.
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.
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.
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.
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.
Activity
joei4cm commentedon Nov 7, 2026
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_errornow also feedsgateway/spine.pyandagent/loop/turn_path.py, so channel replies already carry the parsed summary. What I still see open:rpc/methods/config.py(the error arms around lines 553 and 634) forwards theremedypayload 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.providers/transcription.py:38still 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.
fix(providers): name the fix when the Groq transcription key is missing
fix(providers): name the fix when the Groq transcription key is missing
fix(providers): name the fix when the Groq transcription key is missing
fix(providers): name the fix when the Groq transcription key is missing
fix(providers): name the fix when the Groq transcription key is missing
fix(providers): name the fix when the Groq transcription key is missi…
joei4cm commentedon Nov 17, 2026
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.pyheld 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.joei4cm commentedon Nov 17, 2026
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
detailand no advice, so a rejected key read asTurn failed - Error calling LLM (auth@openrouter): ...and stopped there -- the reader was told what failed and nothing about what to do.emit_errornow 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
hintfield 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:
rpc/methods/config.pyforwards 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.providers/transcription.py:38still warns and returns an empty transcript, so a voice message on an install without a Groq key looks ignored.feat(*): share the provider-error hint across the surfaces that show one