fix: unwrap nested OpenAI-style error envelope in extract_detail

[shoemoney]

What

extract_detail() in src/otari/_base.py pulls the gateway's detail/message/error key out of the error body, but never unwrapped the error value when it's itself a dict. The gateway is OpenAI-compatible, so upstream provider errors arrive as {"error": {"message": "..."}}. That nested dict fell through to str(detail), which stringifies it as a Python repr instead of the actual message.

body = {"error": {"message": "context length exceeded"}}

before: "[gateway] {'message': 'context length exceeded'}"
after:  "[gateway] context length exceeded"

Anything that logs, displays, or string-matches the error message (e.g. checking for "context length" to trigger a retry-with-truncation) silently breaks on this shape.

Why this is worth fixing now

Both sibling SDKs already handle this correctly, so this brings Python in line with a decision that's already been made twice:

• otari-sdk-ts's mapError.ts detailFromObject() — fixed by Regenerate SDK client core from Otari OpenAPI spec #41, which closed issue Regenerate SDK client core from Otari OpenAPI spec #40 ("Error messages are [object Object] for OpenAI-style error bodies").
• otari-sdk-rust's core.rs extract_detail(), whose docstring literally names both shapes it recognizes: "the FastAPI/gateway {\"detail\": \"...\"} shape and the OpenAI-style {\"error\": {\"message\": \"...\"}} / {\"error\": \"...\"} shapes."

Python was the one SDK still missing it.

The fix

Mirrors the TS detailFromObject() precedence exactly: if the resolved detail value is itself a dict, pull its message key; if that's absent or non-string, fall back to json.dumps(detail) instead of str(detail) so the fallback is valid JSON rather than a Python repr.

if isinstance(detail, dict):
    nested = detail.get("message")
    if isinstance(nested, str):
        return nested
if detail is not None:
    return json.dumps(detail)

Tests

Added TestExtractDetailOpenAIEnvelope to tests/unit/test_errors.py, mirroring the TS test cases in client.test.ts ("extracts a useful message from error envelopes"):

• nested {"error": {"message": "..."}} -> unwraps to the message
• regression: FastAPI {"detail": "..."} shape unchanged
• regression: flat {"error": "..."} string unchanged
• regression: top-level {"message": "..."} unchanged
• nested {"error": {"code": 400}} with no message -> valid JSON fallback, not a Python repr
• non-JSON body returned verbatim

What I ran

Wrote the tests first and confirmed RED before touching the source:

tests/unit/test_errors.py::TestExtractDetailOpenAIEnvelope::test_nested_openai_error_object_unwraps_to_message FAILED
tests/unit/test_errors.py::TestExtractDetailOpenAIEnvelope::test_fastapi_detail_shape_unchanged PASSED
tests/unit/test_errors.py::TestExtractDetailOpenAIEnvelope::test_flat_error_string_unchanged PASSED
tests/unit/test_errors.py::TestExtractDetailOpenAIEnvelope::test_top_level_message_unchanged PASSED
tests/unit/test_errors.py::TestExtractDetailOpenAIEnvelope::test_nested_error_object_without_message_falls_back_to_json FAILED
tests/unit/test_errors.py::TestExtractDetailOpenAIEnvelope::test_non_json_body_returned_verbatim PASSED
2 failed, 4 passed, 30 deselected

Applied the fix, same file went GREEN:

6 passed, 30 deselected

Then reverted the source fix (kept the tests) to confirm the tests actually catch the regression — same two tests failed with the identical dict-repr output — before restoring the fix.

Full unit suite after restoring the fix:

144 passed in 0.34s

Also ran ruff check (clean) and mypy (clean) on the touched files.

One more thing

The same gap exists in otari-sdk-go's errors.go errorDetail() (around line 283-303) — it tries to unmarshal the "error" value into a string, fails silently on the nested object, and falls through to returning the raw JSON bytes. Happy to file that as a separate PR if maintainers want it — didn't want to bundle an unrelated repo's fix into this one.