fix(cli): map exhausted transport retries to ServerError

[Aj2280]

Summary

This PR maps exhausted httpx.TransportError exceptions in OmiClient._request() to ServerError(message="Connection failed", detail="Unable to reach the Omi API. Check your network connection or try again shortly."), resolving #12961.

Previously, exhausted transport retries (such as connection refused, read timeout, or protocol error) escaped _request() unmapped and fell through to the generic exception handler in main(). This caused commands to exit with code 1 and emit unformatted plain text on stderr even when --json was requested, violating the documented stable CLI exit code contract (3: server error / connection failure).

Changes

• sdks/python-cli/omi_cli/client.py:
  • Catch httpx.TransportError after the retry loop in OmiClient._request().
  • Raise ServerError(message="Connection failed", detail="Unable to reach the Omi API. Check your network connection or try again shortly.") from exc.
  • Preserves retries, recovery on transient errors, and chains the underlying exception as __cause__.
• sdks/python-cli/tests/test_client_retry.py:
  • Added regression test verifying ConnectError exhausts 4 retries and raises ServerError (exit code 3).
  • Added regression test for ReadTimeout.
  • Added regression test for ProtocolError.
  • Added test verifying transient ConnectError recovers on retry and returns data.
  • Added tests verifying main() exits with code 3 in both plain and --json modes and outputs the expected error structures to stderr.

Verification

• sdks/python-cli/venv/bin/pytest sdks/python-cli/tests/: all 134 passed, 1 skipped.
• Real loopback reproduction:
  • omi --api-base http://127.0.0.1:54321 memory list: exits 3 with readable error on stderr.
  • omi --api-base http://127.0.0.1:54321 --json memory list: exits 3 with JSON error payload on stderr and clean stdout.
• make preflight: all 12 local checks passed.

Fixes #12961

Failure-Class: none

[cubic-dev-ai]

No issues found across 2 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Re-trigger cubic}

[Git-on-my-level]

Verified this end to end — a clean, tightly-scoped fix for #12961. Details for the record:

sdks/python-cli/omi_cli/client.py — the new except httpx.TransportError arm in _request() is placed after the _RetryableHttp arm, which is the correct ordering: _RetryableHttp is not a TransportError subclass, so exhausted 5xx/429 retries still route through _error_from_response(), while exhausted transport failures (ConnectError, ReadTimeout, ProtocolError are all TransportError subclasses) now map to ServerError → exit code 3, matching the README's stable contract ("3 server error (5xx, connection failure)"). With tenacity's reraise=True the original exception propagates after stop_after_attempt(4), and raise ... from exc preserves it as __cause__ for debugging. Pre-fix, these escaped to the last-chance except Exception in main() → exit 1 + plain text even with --json, exactly as reported.

sdks/python-cli/tests/test_client_retry.py — the six new tests cover the three transport failure classes exhausting 4 attempts (with retry count asserted), transient-error recovery (a ConnectError followed by 200 returns data), and two end-to-end main() tests asserting exit code 3, empty stdout, and the expected plain/JSON stderr shapes.

Verification run (isolated container, no network/secrets): full python-cli suite passes — 130 passed, 1 skipped, 0 failures (test_openapi_contract.py excluded only because my sandbox lacks the repo-root docs/api-reference/openapi.json it reads). Swapping in the pre-fix client.py makes the new transport tests fail, confirming they capture the regression.

One coordination note: #12996 also addresses #12961 (same transport-to-ServerError mapping, bundled with broader auth-login changes). This PR is the minimal, focused version of the fix. Maintainer decision needed on which one lands — either way, credit to both contributors for chasing the exit-code contract.

---

by AI on behalf of David — if you need David’s attention urgently, please @Git-on-my-level and escalate with need human response.

[kodjima33]

Confirmed not-yet-fixed on main: exhausted-retry handler in _request only catches _RetryableHttp (5xx/429); a persistent httpx.TransportError still bubbles up raw instead of ServerError. Scoped fix + regression tests, confidence 5/5.