Consolidate error classification for realtime WebSocket failures#107
Merged
Conversation
Three modules (tts/session, agent/session, client) each carried their own copy of the same failure classification: try diagnostics.handshake_error for a rejected handshake (HTTP 401/403), else fall back to the rejected- key/API mapping. Collapse them onto one diagnostics.classify_error so the realtime paths (stream, agent, speak) can't drift apart; ws.is_rejected_key and ws.auth_or_api_error widen to `object` to admit the stream path's recorded Error events (errors.is_auth_failure already took object). Likewise the lazy `import sounddevice` with its ImportError -> audio_missing_error mapping was copy-pasted in microphone, tts/audio, and agent/audio; it now lives once as microphone.import_sounddevice. No behavior change: the handshake fallback in client ran with a None handshake status, where is_rejected_key reduces to is_auth_failure. https://claude.ai/code/session_017LGjFkWANGnCZmgHDHWM7E
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Refactors error handling across realtime streaming paths (agent, TTS, and client streaming) to use a single shared error classification function, eliminating duplication and ensuring consistent error messages and suggestions across all WebSocket connection failures.
Key Changes
New
classify_error()function inaai_cli/streaming/diagnostics.py: Centralizes the logic for mapping WebSocket failures to appropriateCLIErrortypes. Handles both rejected handshakes (HTTP 401/403) with actionable suggestions and other failures via thewsutilmapping.Refactored
import_sounddevice()inaai_cli/microphone.py: Extracted lazy import logic into a public function with clear documentation. This is now the single import-and-fail path for all audio device operations (mic capture, TTS playback, agent duplex stream), ensuring consistent error handling.Updated WebSocket error handlers in
aai_cli/tts/session.py,aai_cli/agent/session.py, andaai_cli/client.py: Replaced inline error classification logic with calls toclassify_error(), reducing code duplication and ensuring all paths handle handshake rejections identically.Simplified audio imports in
aai_cli/agent/audio.pyandaai_cli/tts/audio.py: Replaced try/except blocks with direct calls toimport_sounddevice(), leveraging the centralized error handling.Type signature improvements in
aai_cli/ws.py: Changedis_rejected_key()andauth_or_api_error()to acceptobjectinstead ofException, improving type flexibility for error classification.Implementation Details
The refactoring ensures that:
wsutilmapping (rejected key →auth_failure(), rest →APIError)https://claude.ai/code/session_017LGjFkWANGnCZmgHDHWM7E