Client, error handling, and streaming hardening pass

- Update AGENTS.md to the shared hawk-eco extension-authoring format

Author: Patel230

AGENTS.md

@@ -3,12 +3,12 @@
 from __future__ import annotations
 
 from typing import Any
-from urllib.parse import urlparse
+from urllib.parse import quote, urlparse
 
 import httpx
 
 from ._version import __version__
-from .errors import parse_error
+from .errors import HawkConnectionError, parse_error
 from .retry import DEFAULT_RETRY_CONFIG, RetryConfig, with_retry, with_retry_sync
 from .streaming import AsyncStreamReader, StreamReader
 from .types import (
@@ -40,6 +40,24 @@ def _build_headers(api_key: str | None) -> dict[str, str]:
     return headers
 
 
+def _mask_api_key(api_key: str | None) -> str:
+    """Mask an API key for safe display in repr()/logs.
+
+    Only reveals a trailing suffix when the key is long enough that doing
+    so doesn't expose the whole secret.
+    """
+    if not api_key:
+        return "None"
+    if len(api_key) <= 8:
+        return "***"
+    return "***" + api_key[-4:]
+
+
+def _session_path(session_id: str) -> str:
+    """URL-encode a session_id before splicing it into a request path."""
+    return quote(session_id, safe="")
+
+
 def _validate_base_url(url: str) -> str:
     """Validate that base_url uses http/https and has a hostname."""
     parsed = urlparse(url)
@@ -86,7 +104,7 @@ def __init__(
         )
 
     def __repr__(self) -> str:
-        masked = "***" + self._api_key[-4:] if self._api_key else "None"
+        masked = _mask_api_key(self._api_key)
         return f"HawkClient(base_url='{self._base_url}', api_key='{masked}')"
 
     def __enter__(self) -> HawkClient:
@@ -101,7 +119,10 @@ def close(self) -> None:
 
     def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
         """Make an HTTP request, raising typed errors on failure."""
-        response = self._client.request(method, path, **kwargs)
+        try:
+            response = self._client.request(method, path, **kwargs)
+        except httpx.RequestError as e:
+            raise HawkConnectionError(f"request failed: {e}") from e
         if response.status_code >= 400:
             raise parse_error(response)
         return response
@@ -149,7 +170,7 @@ def _do() -> ChatResponse:
             )
             return ChatResponse.model_validate(resp.json())
 
-        return with_retry_sync(_do, self._retry_config)
+        return with_retry_sync(_do, self._retry_config, idempotent=False)
 
     def chat_stream(
         self,
@@ -178,29 +199,35 @@ def chat_stream(
         )
 
         def _do() -> StreamReader:
-            response = self._client.send(
-                self._client.build_request(
-                    "POST",
-                    "/v1/chat",
-                    json=request.model_dump(exclude_none=True, by_alias=True),
-                    headers={"Accept": "text/event-stream"},
-                ),
-                stream=True,
-            )
+            try:
+                response = self._client.send(
+                    self._client.build_request(
+                        "POST",
+                        "/v1/chat",
+                        json=request.model_dump(exclude_none=True, by_alias=True),
+                        headers={"Accept": "text/event-stream"},
+                    ),
+                    stream=True,
+                )
+            except httpx.RequestError as e:
+                raise HawkConnectionError(f"request failed: {e}") from e
 
             if response.status_code >= 400:
-                response.read()
-                raise parse_error(response)
+                try:
+                    response.read()
+                    raise parse_error(response)
+                finally:
+                    response.close()
 
             return StreamReader(response)
 
-        return with_retry_sync(_do, self._retry_config)
+        return with_retry_sync(_do, self._retry_config, idempotent=False)
 
     def get_session(self, session_id: str) -> SessionDetail:
         """Get a session by ID."""
 
         def _do() -> SessionDetail:
-            resp = self._request("GET", f"/v1/sessions/{session_id}")
+            resp = self._request("GET", f"/v1/sessions/{_session_path(session_id)}")
             return SessionDetail.model_validate(resp.json())
 
         return with_retry_sync(_do, self._retry_config)
@@ -222,7 +249,7 @@ def delete_session(self, session_id: str) -> None:
         """Delete a session by ID."""
 
         def _do() -> None:
-            self._request("DELETE", f"/v1/sessions/{session_id}")
+            self._request("DELETE", f"/v1/sessions/{_session_path(session_id)}")
 
         return with_retry_sync(_do, self._retry_config)
 
@@ -235,7 +262,9 @@ def _do() -> PaginatedResponse[Message]:
             params: dict[str, Any] = {"limit": limit}
             if offset > 0:
                 params["offset"] = offset
-            resp = self._request("GET", f"/v1/sessions/{session_id}/messages", params=params)
+            resp = self._request(
+                "GET", f"/v1/sessions/{_session_path(session_id)}/messages", params=params
+            )
             return PaginatedResponse[Message].model_validate(resp.json())
 
         return with_retry_sync(_do, self._retry_config)
@@ -286,7 +315,7 @@ def __init__(
         )
 
     def __repr__(self) -> str:
-        masked = "***" + self._api_key[-4:] if self._api_key else "None"
+        masked = _mask_api_key(self._api_key)
         return f"AsyncHawkClient(base_url='{self._base_url}', api_key='{masked}')"
 
     async def __aenter__(self) -> AsyncHawkClient:
@@ -301,7 +330,10 @@ async def close(self) -> None:
 
     async def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
         """Make an async HTTP request, raising typed errors on failure."""
-        response = await self._client.request(method, path, **kwargs)
+        try:
+            response = await self._client.request(method, path, **kwargs)
+        except httpx.RequestError as e:
+            raise HawkConnectionError(f"request failed: {e}") from e
         if response.status_code >= 400:
             raise parse_error(response)
         return response
@@ -349,7 +381,7 @@ async def _do() -> ChatResponse:
             )
             return ChatResponse.model_validate(resp.json())
 
-        return await with_retry(_do, self._retry_config)
+        return await with_retry(_do, self._retry_config, idempotent=False)
 
     async def chat_stream(
         self,
@@ -378,29 +410,35 @@ async def chat_stream(
         )
 
         async def _do() -> AsyncStreamReader:
-            response = await self._client.send(
-                self._client.build_request(
-                    "POST",
-                    "/v1/chat",
-                    json=request.model_dump(exclude_none=True, by_alias=True),
-                    headers={"Accept": "text/event-stream"},
-                ),
-                stream=True,
-            )
+            try:
+                response = await self._client.send(
+                    self._client.build_request(
+                        "POST",
+                        "/v1/chat",
+                        json=request.model_dump(exclude_none=True, by_alias=True),
+                        headers={"Accept": "text/event-stream"},
+                    ),
+                    stream=True,
+                )
+            except httpx.RequestError as e:
+                raise HawkConnectionError(f"request failed: {e}") from e
 
             if response.status_code >= 400:
-                await response.aread()
-                raise parse_error(response)
+                try:
+                    await response.aread()
+                    raise parse_error(response)
+                finally:
+                    await response.aclose()
 
             return AsyncStreamReader(response)
 
-        return await with_retry(_do, self._retry_config)
+        return await with_retry(_do, self._retry_config, idempotent=False)
 
     async def get_session(self, session_id: str) -> SessionDetail:
         """Get a session by ID."""
 
         async def _do() -> SessionDetail:
-            resp = await self._request("GET", f"/v1/sessions/{session_id}")
+            resp = await self._request("GET", f"/v1/sessions/{_session_path(session_id)}")
             return SessionDetail.model_validate(resp.json())
 
         return await with_retry(_do, self._retry_config)
@@ -422,7 +460,7 @@ async def delete_session(self, session_id: str) -> None:
         """Delete a session by ID."""
 
         async def _do() -> None:
-            await self._request("DELETE", f"/v1/sessions/{session_id}")
+            await self._request("DELETE", f"/v1/sessions/{_session_path(session_id)}")
 
         return await with_retry(_do, self._retry_config)
 
@@ -435,7 +473,9 @@ async def _do() -> PaginatedResponse[Message]:
             params: dict[str, Any] = {"limit": limit}
             if offset > 0:
                 params["offset"] = offset
-            resp = await self._request("GET", f"/v1/sessions/{session_id}/messages", params=params)
+            resp = await self._request(
+                "GET", f"/v1/sessions/{_session_path(session_id)}/messages", params=params
+            )
             return PaginatedResponse[Message].model_validate(resp.json())
 
         return await with_retry(_do, self._retry_config)

src/hawk/client.py

@@ -27,6 +27,19 @@ def __init__(
         super().__init__(f"hawk-sdk: {message} (status {status_code})")
 
 
+class HawkConnectionError(HawkAPIError):
+    """Transport-level failure (connection refused, timeout, DNS, etc.).
+
+    Raised in place of raw httpx exceptions so callers only ever need to
+    catch HawkAPIError to handle all SDK failures, and so retry logic can
+    treat transient connectivity failures the same as retryable HTTP status
+    codes.
+    """
+
+    def __init__(self, message: str, **kwargs: Any) -> None:
+        super().__init__(message, status_code=0, **kwargs)
+
+
 class BadRequestError(HawkAPIError):
     """400 Bad Request."""
 

src/hawk/errors.py

@@ -23,7 +23,24 @@
 import statistics
 import time
 from dataclasses import dataclass, field
-from typing import Any, Callable
+from typing import TYPE_CHECKING, Any, Callable, Protocol
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable
+
+
+class SyncBenchAgent(Protocol):
+    """Structural type for the agent accepted by run_benchmark."""
+
+    def reset(self) -> None: ...
+    def chat(self, prompt: str) -> Any: ...
+
+
+class AsyncBenchAgent(Protocol):
+    """Structural type for the agent accepted by run_benchmark_async."""
+
+    def reset(self) -> None: ...
+    def chat(self, prompt: str) -> Awaitable[Any]: ...
 
 
 @dataclass
@@ -104,7 +121,7 @@ def summary(self) -> str:
 
 
 def run_benchmark(
-    agent: Any,
+    agent: SyncBenchAgent,
     tasks: list[EvalTask],
     *,
     runs: int = 1,
@@ -136,8 +153,6 @@ def run_benchmark(
                 success = True
                 if task.validate:
                     success = task.validate(response)
-                    if not success:
-                        pass
 
                 results.results.append(
                     EvalResult(
@@ -168,7 +183,7 @@ def run_benchmark(
 
 
 async def run_benchmark_async(
-    agent: Any,
+    agent: AsyncBenchAgent,
     tasks: list[EvalTask],
     *,
     runs: int = 1,
@@ -190,8 +205,6 @@ async def run_benchmark_async(
                 success = True
                 if task.validate:
                     success = task.validate(response)
-                    if not success:
-                        pass
 
                 results.results.append(
                     EvalResult(