fix: pin the eager-503 default error_code to not_ready (Worldtree b2)

worldtree-dev finalized the #331 503 turn-launch error_code as `not_ready` (re-pinned from internal_error; retryable, matching the /readyz 503 sense) and re-froze the OpenAPI at 2.2.0 documenting the 409/503 statuses our v0.18.3 mapping already handles. Tighten our fallback default from the placeholder `turn_launch_unavailable` to the canonical `not_ready` (the default only fires when the body omits error_code — the real code is surfaced verbatim regardless). +1 test, suite 510 green. NOTE: a full conversation-api-spec.md re-vendor to the b2 era is a separate, larger pin-refresh (ratatoskr vendors the markdown spec, not the OpenAPI JSON) — deferred, to bundle with the v1 coverage-audit / when personal is on b2.
2026-06-30 13:26:14 -07:00
4 changed files with 20 additions and 3 deletions
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"

 [project]
 name = "ratatoskr"
-version = "0.18.3"
+version = "0.18.4"
 description = "Worldtree Conversation API debug TUI — multi-pane observability dashboard"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -241,7 +241,11 @@ class TurnLaunchUnavailable(SseConnectFailed):
        self.message = message


-_EAGER_TURN_FAILURE_CODE = {409: "agent_not_available", 503: "turn_launch_unavailable"}
+# Canonical error_codes (Worldtree #331 / v1.0.0b2): 409 -> agent_not_available,
+# 503 -> not_ready (retryable; re-pinned from internal_error). Used only as a
+# fallback default when the body omits error_code — the real code is surfaced
+# verbatim from the {detail:{error_code,message}} envelope.
+_EAGER_TURN_FAILURE_CODE = {409: "agent_not_available", 503: "not_ready"}


 def _eager_failure_fields(body: bytes, status: int) -> tuple[str, str]:
@@ -479,6 +479,19 @@ class TestStreamTurn:
                _ = [e async for e in stream_turn(client, "s1", "hi")]
        assert exc.value.error_code == "agent_not_available"

+    @respx.mock
+    async def test_eager_503_non_json_body_defaults_not_ready(self) -> None:
+        """b2: eager 503 with a non-JSON body -> TurnLaunchUnavailable with the
+        canonical default error_code `not_ready`."""
+        respx.post("https://w.example/sessions/s1/messages").mock(
+            return_value=httpx.Response(503, content=b"<html>nope</html>")
+        )
+        async with httpx.AsyncClient(base_url="https://w.example") as client:
+            with pytest.raises(TurnLaunchUnavailable) as exc:
+                _ = [e async for e in stream_turn(client, "s1", "hi")]
+        assert exc.value.error_code == "not_ready"
+        assert exc.value.retryable is True
+
    @respx.mock
    async def test_no_text_aggregation(self) -> None:
        """no_text_aggregation: consumer yields each text event separately; no concat."""
@@ -1052,7 +1052,7 @@ wheels = [

 [[package]]
 name = "ratatoskr"
-version = "0.18.3"
+version = "0.18.4"
 source = { editable = "." }
 dependencies = [
    { name = "httpx" },