# Server HTTP Client

The `ServerHttpClient` provides communication with a remote CleverAgents
server instance.  It wraps [httpx](https://www.python-httpx.org/) and
handles health checks, version negotiation, pagination, retry with
exponential backoff, and request/response logging with auth-header
redaction.

## Configuration

| Environment variable | Settings field | Default | Description |
|---|---|---|---|
| `CLEVERAGENTS_SERVER_BASE_URL` | `server_base_url` | `None` | Base URL of the remote server (e.g. `https://server.example.com`) |
| `CLEVERAGENTS_SERVER_API_TOKEN` | `server_api_token` | `None` | Bearer token for server authentication |
| `CLEVERAGENTS_SERVER_TLS_VERIFY` | `server_tls_verify` | `True` | Verify TLS certificates; set to `False` only for development |
| `CLEVERAGENTS_SERVER_REQUEST_TIMEOUT` | `server_request_timeout` | `30.0` | Per-request timeout in seconds |

## Usage

```python
from cleveragents.client.http_client import create_client_from_settings

client = create_client_from_settings()

# Health check
is_healthy = client.health_check()

# Version negotiation
version = client.get_version()
negotiated = client.negotiate_version("1.0")

# Paginated list endpoint
page = client.list_endpoint("/plans", page=1, per_page=20)
print(page.items, page.has_next)
```

## Connection Errors

| Exception | Cause |
|---|---|
| `ServerConnectionError` | Cannot reach the server, non-retryable HTTP error, or authentication failure |
| `ServerTimeoutError` | Request exceeded the configured timeout |
| `ServerVersionMismatchError` | Client and server protocol versions are incompatible |
| `A2aNotAvailableError` | Server returned 503 Service Unavailable |

## Retry Policy

Idempotent methods (`GET`, `HEAD`, `OPTIONS`, `PUT`, `DELETE`) are
automatically retried up to 3 times with exponential backoff on status
codes 429, 500, 502, and 504.  Non-idempotent methods (`POST`, `PATCH`)
are never retried automatically.

## TLS Verification

When `server_tls_verify` is set to `False` a warning is logged at
client creation time.  This is intended only for local development
against self-signed certificates; production deployments must always
verify TLS.

## Health Check Failure

When `health_check()` encounters a connection or timeout error it
returns `False` rather than raising.  This allows callers to use it as
a boolean probe without try/except.

## Version Negotiation Failure

`negotiate_version()` raises `ServerVersionMismatchError` when the
server does not return a negotiated version.  The exception includes
both the requested client version and the list of versions the server
supports.