Skip to content

Autonomous OODA-loop pentesting agent. Hermes brain, Kali + Playwright tools over MCP, ATT&CK as the Orient language.

24.5 KB
Raw Blame
"""Tests del cliente :8642 y el batcher SSE (`docker/mcp/hermes_api_client.py`).

NO importan `mcp`/FastMCP: solo el módulo SDK-free `hermes_api_client` + httpx + anyio +
pytest (mismo patrón que `docker/kali/tests/test_scope_guard.py`). Cubren:
  - El batcher SSE puro (`batch_sse_events`): wire `: open`/`id:`/`data:` (incl. multilínea),
    cursor por `seq`, dedup entre páginas, skip best-effort de eventos malformados, y los
    topes de batch (max_events, presupuesto de bytes SIN overshoot) + razón de parada
    (STOP_CAP/STOP_TERMINAL/STOP_DRAINED).
  - `encode_run_id_segment`: el run_id (dato no confiable) se codifica como UN segmento y se
    rechaza cualquier intento de recorrido/salto de ruta (fija review Finding "run_id route
    escape"), incluida la variante percent-encoded; y que un run_id de recorrido NO toca red.
  - `iter_events` (async, httpx.AsyncClient + MockTransport): stream/dedup, corte en el
    evento terminal, y preservación del sobre {"error": {...}} COMPLETO en non-2xx/invalid.
  - HermesApiClient con httpx.MockTransport: Bearer puesto, Idempotency-Key solo cuando se
    da, el mapeo de cada forma de error (sobre JSON, non-2xx sin sobre, fallo de conexión), y
    que la ruta construida es el target exacto esperado.
"""

from __future__ import annotations

import json
import sys
from pathlib import Path

import anyio
import httpx
import pytest

# El módulo bajo prueba vive en docker/mcp/ (el servidor MCP NO se importa: arrastra `mcp`).
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))

import hermes_api_client as hac  # noqa: E402


# ------------------------------------------------------------------ parser SSE


def _sse_message(seq: int, event: str = "message.delta", **extra) -> str:
    """Construye un mensaje SSE `id:`+`data:` con un evento JSON de `seq`/`event`."""
    payload = {"event": event, "run_id": "run_x", "timestamp": 1.0, "seq": seq}
    payload.update(extra)
    return "id: %d\ndata: %s\n\n" % (seq, json.dumps(payload))


def _lines(raw: str):
    """Itera líneas como lo haría httpx.Response.iter_lines (sin el '\\n' final)."""
    return iter(raw.split("\n"))


def test_parser_basic_wire_and_cursor():
    raw = ": open\n\n" + _sse_message(1) + _sse_message(2) + _sse_message(3)
    events, next_cursor, reason, _ = hac.batch_sse_events(_lines(raw))
    assert [e["seq"] for e in events] == [1, 2, 3]
    assert next_cursor == 3
    assert reason == hac.STOP_DRAINED  # el iterador se agotó sin evento terminal
    # Opaco: el dict de evento se entrega sin tocar.
    assert events[0]["event"] == "message.delta"
    assert events[0]["run_id"] == "run_x"


def test_parser_multiline_data():
    # SSE permite `data:` multilínea: cada línea `data:` se une con '\n'. Se usa un JSON
    # pretty-printed (los '\n' entre elementos estructurales son JSON válido tras el join).
    payload = {"event": "message.interim", "run_id": "run_x", "timestamp": 1.0, "seq": 5,
               "text": "a"}
    dumped = json.dumps(payload, indent=2)  # multilínea, válido
    data_lines = "".join("data: %s\n" % ln for ln in dumped.split("\n"))
    raw = "id: 5\n" + data_lines + "\n"
    events, _, _, _ = hac.batch_sse_events(_lines(raw))
    assert len(events) == 1 and events[0]["seq"] == 5 and events[0]["text"] == "a"


def test_parser_dedup_by_after_seq():
    raw = _sse_message(1) + _sse_message(2) + _sse_message(3)
    events, next_cursor, _, _ = hac.batch_sse_events(_lines(raw), after_seq=2)
    assert [e["seq"] for e in events] == [3]
    assert next_cursor == 3


def test_parser_skips_malformed_and_missing_seq():
    good = _sse_message(1)
    bad_json = "id: 2\ndata: {not json}\n\n"
    no_seq = "id: 3\ndata: %s\n\n" % json.dumps({"event": "x", "run_id": "r"})
    good2 = _sse_message(4)
    events, _, _, _ = hac.batch_sse_events(_lines(good + bad_json + no_seq + good2))
    assert [e["seq"] for e in events] == [1, 4]


def test_parser_stops_on_terminal_event():
    raw = _sse_message(1) + _sse_message(2, event=hac.TERMINAL_EVENT) + _sse_message(3)
    events, next_cursor, reason, _ = hac.batch_sse_events(_lines(raw))
    # Se para TRAS emitir el evento terminal; el seq 3 no se entrega.
    assert [e["seq"] for e in events] == [1, 2]
    assert events[-1]["event"] == hac.TERMINAL_EVENT
    assert reason == hac.STOP_TERMINAL
    assert next_cursor == 2


def test_parser_max_events_cap():
    raw = "".join(_sse_message(i) for i in range(1, 11))
    events, next_cursor, reason, _ = hac.batch_sse_events(_lines(raw), max_events=3)
    assert [e["seq"] for e in events] == [1, 2, 3]
    assert reason == hac.STOP_CAP  # cap -> hay más datos, el servidor NO declara done
    assert next_cursor == 3


def test_parser_byte_budget_cap_single_event():
    # Un presupuesto de bytes diminuto deja pasar UN único evento (anti-starvation) y corta.
    raw = "".join(_sse_message(i, text="x" * 50) for i in range(1, 6))
    events, _, reason, _ = hac.batch_sse_events(_lines(raw), byte_budget=10)
    assert len(events) == 1 and events[0]["seq"] == 1
    assert reason == hac.STOP_CAP


def test_parser_byte_budget_closes_page_before_overshoot():
    # Fija review Finding "byte budget overshoots by one event": con DOS eventos grandes y un
    # presupuesto que cabe el primero pero no la suma, el segundo NO se incluye (se mide ANTES
    # de añadir). El batch devuelve solo el primero y el segundo queda para la próxima página.
    big = "y" * 200
    one = _sse_message(1, text=big)
    two = _sse_message(2, text=big)
    size_one = len(json.dumps(json.loads(one.split("data: ", 1)[1].split("\n\n")[0])))
    # Presupuesto: cabe el primero, pero el primero+segundo lo cruza.
    budget = size_one + 10
    events, next_cursor, reason, _ = hac.batch_sse_events(
        _lines(one + two), byte_budget=budget
    )
    assert [e["seq"] for e in events] == [1]  # el segundo NO se incluyó (sin overshoot)
    assert next_cursor == 1  # el seq del segundo NO avanza: se re-leerá en la próxima página
    assert reason == hac.STOP_CAP


def test_parser_byte_budget_two_small_events_both_fit():
    # Control: si ambos caben, los dos salen (no se corta de más).
    one = _sse_message(1, text="a")
    two = _sse_message(2, text="b")
    events, _, reason, _ = hac.batch_sse_events(_lines(one + two), byte_budget=10_000)
    assert [e["seq"] for e in events] == [1, 2]
    assert reason == hac.STOP_DRAINED


# ------------------------------------------------------------------ techo absoluto por evento


def test_parser_oversized_single_event_fails_loud_without_consuming_cursor():
    # Fija los blocking Findings de la revisión 4 ("oversized event placeholder breaks opaque
    # verbatim pass-through"): un ÚNICO evento cuyo JSON supera el techo absoluto NO se emite
    # —ni verbatim ni como placeholder dentro de `events`—. La página sale VACÍA, el cursor NO
    # avanza (el seq queda recuperable) y se señala STOP_OVERSIZE con los metadatos SIN payload
    # en batcher.oversized.
    huge = "Z" * 5_000
    raw = _sse_message(7, event="tool.completed", preview=huge)
    events, next_cursor, reason, oversized = hac.batch_sse_events(
        _lines(raw), max_single_event_bytes=1_000
    )
    # NADA se emite dentro de events: el payload no confiable nunca viaja ni como placeholder.
    assert events == []
    # El cursor NO avanza: el seq del oversized queda recuperable (no se consume).
    assert next_cursor == 0
    assert reason == hac.STOP_OVERSIZE
    # Los metadatos (SIN payload) describen el evento sobredimensionado.
    assert oversized is not None
    assert oversized["seq"] == 7
    assert oversized["event"] == "tool.completed"
    assert oversized["serialized_bytes"] > 1_000
    assert oversized["limit_bytes"] == 1_000
    assert huge not in json.dumps(oversized)  # el payload nunca se reenvía


def test_parser_oversized_event_after_normal_closes_page_first():
    # Si la página YA tiene un evento normal, el oversized NO se mezcla: se cierra la página
    # ANTES (STOP_CAP) y su seq NO avanza, para reprocesarlo con la página vacía. Así los
    # eventos sub-techo se entregan COMPLETOS antes de fallar en el oversized.
    small = _sse_message(1, text="ok")
    huge = _sse_message(2, event="tool.completed", preview="Q" * 5_000)
    events, next_cursor, reason, oversized = hac.batch_sse_events(
        _lines(small + huge), max_single_event_bytes=1_000
    )
    assert [e["seq"] for e in events] == [1]  # solo el normal, COMPLETO
    assert events[0]["text"] == "ok"  # el evento sub-techo no se recorta
    assert next_cursor == 1  # el oversized queda pendiente (se reprocesa la próxima página)
    assert reason == hac.STOP_CAP
    assert oversized is None  # aún no se gatilló el fallo-loud (página no vacía)
    # Página siguiente (empezando tras el seq 1): el oversized falla loud con STOP_OVERSIZE.
    events2, next_cursor2, reason2, oversized2 = hac.batch_sse_events(
        _lines(huge), after_seq=1, max_single_event_bytes=1_000
    )
    assert events2 == []
    assert next_cursor2 == 1  # el cursor sigue SIN avanzar
    assert reason2 == hac.STOP_OVERSIZE
    assert oversized2 is not None and oversized2["seq"] == 2


def test_parser_oversized_terminal_run_completed_does_not_consume_cursor():
    # Fija el segundo blocking de la revisión 4 ("oversized terminal run.completed can return
    # done:false"): si el evento sobredimensionado ES run.completed, NO se devuelve como un
    # marcador terminal dentro de events (que combinado con STOP_OVERSIZE daría done:false).
    # Sale VACÍO, STOP_OVERSIZE, cursor sin avanzar; la terminalidad real se recupera luego con
    # get_run (ver test_iter_events_oversized_* y el server).
    huge_terminal = _sse_message(9, event=hac.TERMINAL_EVENT, output="X" * 5_000)
    events, next_cursor, reason, oversized = hac.batch_sse_events(
        _lines(huge_terminal), max_single_event_bytes=1_000
    )
    assert events == []  # NO se devuelve el run.completed como evento no terminal
    assert next_cursor == 0  # cursor no consumido
    assert reason == hac.STOP_OVERSIZE
    assert oversized is not None
    assert oversized["event"] == hac.TERMINAL_EVENT
    assert oversized["seq"] == 9


# ------------------------------------------------------------------ HermesApiClient


def _client_with(handler):
    """HermesApiClient cuyo httpx usa un MockTransport con `handler`.

    Se parchea httpx.request / httpx.stream para inyectar el transporte mock, ya que el
    cliente usa las funciones de módulo de httpx (no una instancia inyectada).
    """
    transport = httpx.MockTransport(handler)
    return transport


@pytest.fixture()
def patch_httpx(monkeypatch):
    """Devuelve una función que instala un handler mock sobre httpx.request/stream."""
    def _install(handler):
        transport = httpx.MockTransport(handler)

        def _request(method, url, **kwargs):
            with httpx.Client(transport=transport) as c:
                return c.request(method, url, **kwargs)

        def _stream(method, url, **kwargs):
            # Devuelve un context manager de stream sobre el transporte mock.
            c = httpx.Client(transport=transport)
            return c.stream(method, url, **kwargs)

        monkeypatch.setattr(hac.httpx, "request", _request)
        monkeypatch.setattr(hac.httpx, "stream", _stream)
    return _install


def test_health_sets_bearer(patch_httpx):
    captured = {}

    def handler(request: httpx.Request) -> httpx.Response:
        captured["auth"] = request.headers.get("Authorization")
        return httpx.Response(200, json={"status": "ok", "platform": "hermes-agent",
                                         "version": "0.22.0"})

    patch_httpx(handler)
    client = hac.HermesApiClient("http://up:8642", "SECRET")
    out = client.health()
    assert out["platform"] == "hermes-agent" and out["version"] == "0.22.0"
    assert captured["auth"] == "Bearer SECRET"


def test_create_run_idempotency_header_only_when_given(patch_httpx):
    seen_headers = []

    def handler(request: httpx.Request) -> httpx.Response:
        seen_headers.append(request.headers.get("Idempotency-Key"))
        return httpx.Response(200, json={"run_id": "run_1", "status": "started",
                                         "replayed": False})

    patch_httpx(handler)
    client = hac.HermesApiClient("http://up:8642", "K")
    client.create_run("hola")
    client.create_run("hola", idempotency_key="abc")
    assert seen_headers[0] is None
    assert seen_headers[1] == "abc"


def test_create_run_omits_empty_optionals(patch_httpx):
    bodies = []

    def handler(request: httpx.Request) -> httpx.Response:
        bodies.append(json.loads(request.content))
        return httpx.Response(200, json={"run_id": "run_1", "status": "started",
                                         "replayed": False})

    patch_httpx(handler)
    client = hac.HermesApiClient("http://up:8642", "K")
    client.create_run("hola", session_id=None, instructions="", previous_response_id="prev")
    body = bodies[0]
    assert body["input"] == "hola"
    assert body["previous_response_id"] == "prev"
    assert "session_id" not in body and "instructions" not in body
    # conversation_history NUNCA se envía (omisión deliberada del wrapper).
    assert "conversation_history" not in body


def test_error_envelope_forwarded_verbatim(patch_httpx):
    def handler(request: httpx.Request) -> httpx.Response:
        return httpx.Response(404, json={"error": {"message": "Run not found: run_x",
                                                   "type": "invalid_request_error",
                                                   "param": None, "code": "run_not_found"}})

    patch_httpx(handler)
    client = hac.HermesApiClient("http://up:8642", "K")
    out = client.get_run("run_x")
    assert out["error"]["code"] == "run_not_found"
    assert out["error"]["message"] == "Run not found: run_x"


def test_non_2xx_without_envelope_synthesizes_upstream_error(patch_httpx):
    def handler(request: httpx.Request) -> httpx.Response:
        return httpx.Response(500, text="<html>boom</html>")

    patch_httpx(handler)
    client = hac.HermesApiClient("http://up:8642", "K")
    out = client.get_run("run_x")
    assert out["error"]["code"] == "upstream_error"
    assert "500" in out["error"]["message"]


def test_connection_failure_maps_to_unreachable(patch_httpx):
    def handler(request: httpx.Request) -> httpx.Response:
        raise httpx.ConnectError("refused")

    patch_httpx(handler)
    client = hac.HermesApiClient("http://up:8642", "K")
    out = client.health()
    assert out["error"]["code"] == "upstream_unreachable"
    assert "cannot reach Hermes" in out["error"]["message"]


def test_steer_409_forwarded(patch_httpx):
    def handler(request: httpx.Request) -> httpx.Response:
        return httpx.Response(409, json={"error": {
            "message": "Run is not currently accepting steer input: run_x",
            "type": "invalid_request_error", "param": None,
            "code": "run_not_accepting_steer"}})

    patch_httpx(handler)
    client = hac.HermesApiClient("http://up:8642", "K")
    out = client.steer_run("run_x", "stop")
    assert out["error"]["code"] == "run_not_accepting_steer"


# ------------------------------------------------------------------ run_id como segmento


def test_encode_run_id_segment_normal():
    # Un id normal pasa tal cual (es ya un segmento seguro).
    assert hac.encode_run_id_segment("run_36998a15") == "run_36998a15"


def test_encode_run_id_segment_percent_encodes_specials():
    # Un espacio u otros caracteres se percent-encodean (siguen siendo UN segmento).
    assert hac.encode_run_id_segment("run with space") == "run%20with%20space"


@pytest.mark.parametrize("evil", [
    "../runs?ignored",       # el PoC del review: saltaría a POST /v1/runs
    "../runs",
    "a/b",                   # slash crudo
    "a\\b",                  # backslash
    "run?x=1",               # query
    "run#frag",              # fragment
    "%2e%2e%2fruns",         # ".." + "/" percent-encoded -> se decodifica y se rechaza
    "%2fetc%2fpasswd",       # "/" percent-encoded
    "run\x00id",             # NUL
])
def test_encode_run_id_segment_rejects_route_escape(evil):
    with pytest.raises(hac.RunIdError):
        hac.encode_run_id_segment(evil)


def test_run_id_route_escape_is_blocked_before_network(patch_httpx):
    # Fija el blocking Finding "run_id route escape": un run_id de recorrido NO debe tocar la
    # red; debe devolver invalid_request SIN hacer la petición (no crear un run via steer).
    called = {"n": 0}

    def handler(request: httpx.Request) -> httpx.Response:
        called["n"] += 1
        return httpx.Response(200, json={"run_id": "run_leak", "status": "started"})

    patch_httpx(handler)
    client = hac.HermesApiClient("http://up:8642", "K")
    out = client.steer_run("../runs?ignored", "please create a run")
    assert out["error"]["code"] == "invalid_request"
    assert called["n"] == 0  # NUNCA se llamó a upstream


def test_run_id_safe_hits_exact_target(patch_httpx):
    # "Test the final request target": un run_id normal construye la ruta esperada.
    targets = []

    def handler(request: httpx.Request) -> httpx.Response:
        targets.append(str(request.url))
        return httpx.Response(200, json={"ok": True})

    patch_httpx(handler)
    client = hac.HermesApiClient("http://up:8642", "K")
    client.get_run("run_abc")
    client.stop_run("run_abc")
    assert targets[0] == "http://up:8642/v1/runs/run_abc"
    assert targets[1] == "http://up:8642/v1/runs/run_abc/stop"


# ------------------------------------------------------------------ iter_events (async)


def _async_mock_client(hac_module, monkeypatch, handler):
    """Parchea httpx.AsyncClient para que iter_events use un MockTransport async."""
    orig_async_client = httpx.AsyncClient

    def _factory(*args, **kwargs):
        kwargs["transport"] = httpx.MockTransport(handler)
        return orig_async_client(*args, **kwargs)

    monkeypatch.setattr(hac_module.httpx, "AsyncClient", _factory)


def test_iter_events_non_2xx_preserves_full_envelope(monkeypatch):
    # Fija el blocking Finding "streaming errors lose the common error envelope": un run
    # desconocido en el endpoint de eventos devuelve el sobre {"error": {...}} COMPLETO como
    # `error`, con stop_reason "error" (misma forma que request/response).
    def handler(request: httpx.Request) -> httpx.Response:
        return httpx.Response(404, json={"error": {
            "message": "Run not found: run_x", "type": "invalid_request_error",
            "param": None, "code": "run_not_found"}})

    _async_mock_client(hac, monkeypatch, handler)
    client = hac.HermesApiClient("http://up:8642", "K")
    events, next_cursor, error, reason = anyio.run(
        lambda: client.iter_events("run_x", after_seq=0)
    )
    assert events == [] and next_cursor == 0
    assert reason == "error"
    assert error == {"error": {"message": "Run not found: run_x",
                               "type": "invalid_request_error", "param": None,
                               "code": "run_not_found"}}


def test_iter_events_streams_and_dedup(monkeypatch):
    body = ": open\n\n" + _sse_message(1) + _sse_message(2) + _sse_message(3)

    def handler(request: httpx.Request) -> httpx.Response:
        return httpx.Response(200, text=body,
                              headers={"content-type": "text/event-stream"})

    _async_mock_client(hac, monkeypatch, handler)
    client = hac.HermesApiClient("http://up:8642", "K")
    events, next_cursor, error, reason = anyio.run(
        lambda: client.iter_events("run_x", after_seq=1)
    )
    assert error is None
    assert [e["seq"] for e in events] == [2, 3]
    assert next_cursor == 3
    assert reason == hac.STOP_DRAINED


def test_iter_events_terminal_event_stops(monkeypatch):
    body = _sse_message(1) + _sse_message(2, event=hac.TERMINAL_EVENT) + _sse_message(3)

    def handler(request: httpx.Request) -> httpx.Response:
        return httpx.Response(200, text=body,
                              headers={"content-type": "text/event-stream"})

    _async_mock_client(hac, monkeypatch, handler)
    client = hac.HermesApiClient("http://up:8642", "K")
    events, _, error, reason = anyio.run(
        lambda: client.iter_events("run_x", after_seq=0)
    )
    assert error is None
    assert [e["seq"] for e in events] == [1, 2]  # para en el terminal
    assert reason == hac.STOP_TERMINAL


def test_iter_events_deadline_covers_pre_header_stall(monkeypatch):
    # Fija el blocking Finding "SSE pre-header wait escapes the deadline": si el upstream
    # ACEPTA la conexión pero RETIENE las cabeceras más allá de wait_seconds, iter_events debe
    # cortar por el deadline wall-clock (STOP_DEADLINE, frontera NORMAL sin error), NO colgar.
    # El handler async duerme más que wait_seconds ANTES de devolver la respuesta/cabeceras.
    async def handler(request: httpx.Request) -> httpx.Response:
        await anyio.sleep(5.0)  # retiene cabeceras (read-timeout está deshabilitado)
        return httpx.Response(200, text=_sse_message(1),
                              headers={"content-type": "text/event-stream"})

    _async_mock_client(hac, monkeypatch, handler)
    client = hac.HermesApiClient("http://up:8642", "K")
    events, next_cursor, error, reason = anyio.run(
        lambda: client.iter_events("run_x", after_seq=0, wait_seconds=0.2)
    )
    # Cortó por el deadline durante la adquisición de cabeceras: sin eventos, SIN error.
    assert events == []
    assert error is None
    assert reason == hac.STOP_DEADLINE
    assert next_cursor == 0


def test_iter_events_invalid_run_id_no_network(monkeypatch):
    called = {"n": 0}

    def handler(request: httpx.Request) -> httpx.Response:
        called["n"] += 1
        return httpx.Response(200, text="")

    _async_mock_client(hac, monkeypatch, handler)
    client = hac.HermesApiClient("http://up:8642", "K")
    events, _, error, reason = anyio.run(
        lambda: client.iter_events("../runs", after_seq=0)
    )
    assert reason == "error"
    assert error["error"]["code"] == "invalid_request"
    assert called["n"] == 0


def test_iter_events_oversized_single_event_bare_error(monkeypatch):
    # iter_events con un ÚNICO evento sobredimensionado sobre página vacía: aquí se fuerza el
    # techo bajo monkeypatcheando MAX_SINGLE_EVENT_BYTES (iter_events no lo expone por firma).
    monkeypatch.setattr(hac, "MAX_SINGLE_EVENT_BYTES", 1_000)
    huge = _sse_message(5, event=hac.TERMINAL_EVENT, output="Q" * 5_000)

    def handler(request: httpx.Request) -> httpx.Response:
        return httpx.Response(200, text=huge,
                              headers={"content-type": "text/event-stream"})

    _async_mock_client(hac, monkeypatch, handler)
    client = hac.HermesApiClient("http://up:8642", "K")
    events, next_cursor, error, reason = anyio.run(
        lambda: client.iter_events("run_x", after_seq=0)
    )
    # Sobre DESNUDO: sin eventos, cursor NO avanzado, code oversized_event con metadatos.
    assert events == []
    assert next_cursor == 0
    assert reason == "error"
    assert error["error"]["code"] == "oversized_event"
    md = error["error"]["oversized_event"]
    assert md["seq"] == 5 and md["event"] == hac.TERMINAL_EVENT
    assert "Q" * 5_000 not in json.dumps(error)  # el payload nunca viaja


class _StallingAsyncStream(httpx.AsyncByteStream):
    """Cuerpo de respuesta async que ENTREGA las cabeceras pero cuelga el cuerpo.

    Permite simular un non-2xx cuyo CUERPO no cierra: `__aiter__` duerme más que el deadline
    antes de producir nada, de modo que `resp.aread()` se cuelga y el deadline wall-clock lo
    corta (fija el NB "stalled error body downgrades to a deadline page").
    """

    async def __aiter__(self):
        await anyio.sleep(5.0)  # el cuerpo se cuelga más allá del deadline
        yield b"{}"


def test_iter_events_stalled_error_body_preserves_status(monkeypatch):
    # Fija el NB "stalled error body downgrades to a deadline page": un non-2xx cuyas CABECERAS
    # llegan pero cuyo CUERPO se cuelga más allá del deadline debe reportarse como un sobre de
    # error (status conocido), NO como una página de deadline vacía (done:false) que un cliente
    # loop-until-done reintentaría.
    def handler(request: httpx.Request) -> httpx.Response:
        return httpx.Response(503, stream=_StallingAsyncStream(),
                              headers={"content-type": "application/json"})

    _async_mock_client(hac, monkeypatch, handler)
    client = hac.HermesApiClient("http://up:8642", "K")
    events, next_cursor, error, reason = anyio.run(
        lambda: client.iter_events("run_x", after_seq=0, wait_seconds=0.2)
    )
    assert events == []
    assert reason == "error"  # NO STOP_DEADLINE
    assert error is not None
    assert error["error"]["code"] == "upstream_error"
    assert "503" in error["error"]["message"]