feat(exceptions): expose response headers on RoeAPIException (1.0.801)

[jadenfix]

Summary

RoeAPIException now carries the response headers so callers can read Retry-After on 429s symmetrically with the raw-httpx path. Today the SDK discards headers entirely in translate_response, forcing downstream consumers (e.g. roe-mcp) to hardcode retry_after=1.0 because there's no machine-readable signal available — even though roe-main correctly emits the standard Retry-After header on its DRF-throttled responses.

Changes

• src/roe/exceptions.py: RoeAPIException.__init__ gains a headers: Mapping[str, str] | None = None kwarg; stored as a lowercase-normalised dict so callers can always look up by exc.headers["retry-after"] (httpx Headers iterates lowercased; generated-client MutableMapping preserves original casing — the normalisation makes the contract uniform). translate_response() threads getattr(response, "headers", None) into the raised exception.
• tests/unit/test_translate_response.py: 7 new tests — Retry-After (numeric + HTTP-date), missing-header, general header preservation on 404/500, stub-without-headers safety, and the uppercased-headers normalisation contract.
• pyproject.toml: version 1.0.80 → 1.0.801. Heads up: this intentionally skips past the natural patch sequence to ship the headers fix immediately on PR merge (auto-tags v1.0.801 via tag-on-release-merge.yml, publish.yml → PyPI). The next roe-main weekly (release-1-0-81-*) will write 1.0.81 to pyproject.toml; that's a downgrade in semver ordering (1.0.801 > 1.0.81), so tag-on-release-merge.yml fires v1.0.81 → publishes 1.0.81 to PyPI. Consumers with loose >= pins resolve to the highest published version (1.0.801) and stay on this PR's code until weekly patch sequence catches up past 1.0.801; consumers with exact ==1.0.81 pins get the natural weekly bundle.

Parity

Companion PRs: roe-ai/roe-typescript#13 (also 1.0.801), roe-ai/roe-golang#14 (1.0.81 — Go takes a different path because its weekly bump path is one of the lower-touched ones; see that PR for rationale).

Test plan

• uv run pytest tests/unit/test_translate_response.py -v → 23/23 pass (16 existing + 7 new)
• uv run ruff check src/roe/exceptions.py tests/unit/test_translate_response.py clean
• CI green

[greptile-apps]

Greptile Summary

This PR exposes response headers on RoeAPIException so callers can read Retry-After on 429 responses without falling back to the raw-httpx layer. Keys are normalised to lowercase at store time, giving a consistent lookup contract across both httpx.Headers and the generated-client's MutableMapping.

• RoeAPIException.__init__ gains a headers: Mapping[str, str] | None kwarg; stored as a lowercase-keyed dict via {k.lower(): v for k, v in headers.items()}.
• translate_response threads getattr(response, \"headers\", None) into the raised exception, with a zero-crash fallback for stubs that omit the attribute.
• 7 new unit tests cover the numeric Retry-After, HTTP-date form, absent header, general header preservation on 404/500, generated-stub normalisation, and the no-headers stub path; the version is bumped to 1.0.801.

Confidence Score: 5/5

Safe to merge — the change is additive, purely extends the exception with an optional attribute, and is guarded by a no-crash getattr fallback for legacy stubs.

The headers are normalised at store time, the translate_response fallback to None covers any response shape that lacks a .headers attribute, and the 7 new tests exercise all meaningful paths including the uppercase-normalisation contract. No existing behaviour is altered; the new headers kwarg defaults to None so all current call sites remain valid.

No files require special attention.

Important Files Changed

Filename	Overview
src/roe/exceptions.py	Adds headers kwarg to RoeAPIException.__init__ with lowercase normalisation; translate_response picks up headers via getattr with a safe fallback. Previously-flagged casing issue is addressed.
tests/unit/test_translate_response.py	7 new tests fully cover the headers contract (httpx path, generated-client stub, absent header, uppercase-normalisation, no-headers stub). Test name test_429_no_retry_after_header_when_absent now has an updated docstring clarifying headers dict is not empty.
pyproject.toml	Version bumped 1.0.80 → 1.0.801; intentional skip to publish headers fix ahead of the weekly semver sequence, as described in the PR.
uv.lock	Lock file updated to reflect the new roe-ai version; no other dependency changes.

_{Reviews (2): Last reviewed commit: "Revert "chore(version): revert pyproject..." | Re-trigger Greptile}

[jadenfix]

@greptile please re-review — latest commit includes Greptile-flagged fix-ups (lowercase-key contract / checked type assertions) plus the version-strategy decision (Python+TS at 1.0.801, Go at 1.0.81; see PR description for rationale)