Skip to content

armgit / dify

Public Imported from GitHub
0

Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.

40.7 KB
Raw Blame
from __future__ import annotations

import asyncio
import json
from collections.abc import AsyncIterator, Iterator
from datetime import UTC, datetime
from typing import cast, override

import httpx
import pytest

from dify_agent.protocol.snapshot import SessionSnapshot
from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig
from dify_agent.client import _client as client_module
from dify_agent.client import (
    Client,
    DifyAgentHTTPError,
    DifyAgentNotFoundError,
    DifyAgentStreamError,
    DifyAgentTimeoutError,
    DifyAgentValidationError,
)
from dify_agent.protocol import (
    BindingFileDownloadRequest,
    BindingFileDownloadResponse,
    BindingFileListResponse,
    BindingFileReadResponse,
    CancelRunRequest,
    CancelRunResponse,
    CreateExecutionBindingRequest,
    CreateHomeSnapshotFromBindingRequest,
    CreateRunRequest,
    DestroyExecutionBindingRequest,
    RUN_EVENT_ADAPTER,
    RunCancelledEvent,
    RunCancelledEventData,
    RunEvent,
    RunEventsResponse,
    RunFailedEvent,
    RunFailedEventData,
    RunStartedEvent,
    RunSucceededEvent,
    RunSucceededEventData,
)


def _create_run_payload() -> dict[str, object]:
    return {
        "composition": {
            "schema_version": 2,
            "layers": [{"name": "prompt", "config": {"user": "hello"}}],
        }
    }


def _event_frame(event: RunEvent, *, event_id: str | None = None, exclude_id: bool = False) -> str:
    payload = RUN_EVENT_ADAPTER.dump_json(event, exclude={"id"} if exclude_id else None).decode()
    lines: list[str] = []
    if event_id is not None:
        lines.append(f"id: {event_id}")
    lines.append(f"data: {payload}")
    return "\n".join(lines) + "\n\n"


def _run_succeeded_event(*, event_id: str = "2-0", run_id: str = "run-1") -> RunSucceededEvent:
    return RunSucceededEvent(
        id=event_id,
        run_id=run_id,
        data=RunSucceededEventData(output="done", session_snapshot=SessionSnapshot(layers={})),
    )


def _run_failed_event(error: str, *, event_id: str = "2-0", run_id: str = "run-1") -> RunFailedEvent:
    return RunFailedEvent(
        id=event_id,
        run_id=run_id,
        data=RunFailedEventData(error=error),
    )


def _run_status_json(status: str) -> dict[str, object]:
    now = datetime(2026, 5, 11, tzinfo=UTC).isoformat()
    return {"run_id": "run-1", "status": status, "created_at": now, "updated_at": now, "error": None}


def _binding_file_download_request(path: str = "report.txt") -> BindingFileDownloadRequest:
    return BindingFileDownloadRequest(
        backend_binding_ref="binding-ref",
        path=path,
        execution_context=DifyExecutionContextLayerConfig(
            tenant_id="tenant-1",
            user_id="account-1",
            user_from="account",
            agent_mode="agent_app",
            invoke_from="debugger",
        ),
    )


def _assert_binding_download_timeout(request: httpx.Request, expected: float = 240.0) -> None:
    timeout = cast(dict[str, float], request.extensions["timeout"])
    assert timeout == {"connect": expected, "read": expected, "write": expected, "pool": expected}


def _function_tool_result_payload(key: str) -> dict[str, object]:
    return {
        "type": "pydantic_ai_event",
        "run_id": "run-1",
        "created_at": datetime(2026, 5, 11, tzinfo=UTC).isoformat(),
        "data": {
            "event_kind": "function_tool_result",
            key: {
                "tool_name": "shell_run",
                "content": "ok",
                "tool_call_id": "call-1",
                "part_kind": "tool-return",
            },
        },
    }


class DisconnectingSyncStream(httpx.SyncByteStream):
    chunks: list[bytes]

    def __init__(self, *chunks: str) -> None:
        self.chunks = [chunk.encode() for chunk in chunks]

    @override
    def __iter__(self) -> Iterator[bytes]:
        yield from self.chunks
        raise httpx.ReadError("stream disconnected")


class DisconnectingAsyncStream(httpx.AsyncByteStream):
    chunks: list[bytes]

    def __init__(self, *chunks: str) -> None:
        self.chunks = [chunk.encode() for chunk in chunks]

    @override
    async def __aiter__(self) -> AsyncIterator[bytes]:
        for chunk in self.chunks:
            yield chunk
        raise httpx.ReadError("stream disconnected")


def test_sse_decoder_accepts_function_tool_result_part_alias(monkeypatch: pytest.MonkeyPatch) -> None:
    monkeypatch.setattr(client_module, "_function_tool_result_payload_key_cache", "part")
    decoder = client_module._SSEDecoder()
    payload = _function_tool_result_payload("result")

    assert decoder.feed_line(f"data: {json.dumps(payload)}") is None
    event = decoder.feed_line("")

    assert event is not None
    assert event.type == "pydantic_ai_event"
    assert event.data.event_kind == "function_tool_result"
    assert event.data.part.tool_name == "shell_run"


def test_function_tool_result_payload_normalization_supports_old_part_schema(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    monkeypatch.setattr(client_module, "_function_tool_result_payload_key_cache", "part")
    payload = _function_tool_result_payload("result")

    normalized = client_module._normalize_run_event_payload_for_local_pydantic_ai(payload)

    assert normalized["data"]["part"]["tool_name"] == "shell_run"
    assert "result" not in normalized["data"]


def test_sync_methods_parse_protocol_dtos_and_send_create_request_dto() -> None:
    def handler(request: httpx.Request) -> httpx.Response:
        if request.method == "POST" and request.url.path == "/runs":
            payload = cast(dict[str, object], json.loads(request.content))
            composition = cast(dict[str, object], payload["composition"])
            layers = cast(list[dict[str, object]], composition["layers"])
            assert layers[0]["config"] == {"user": "hello"}
            assert "compositor" not in payload
            assert "agent_profile" not in payload
            return httpx.Response(202, json={"run_id": "run-1", "status": "running"})
        if request.method == "GET" and request.url.path == "/runs/run-1":
            return httpx.Response(200, json=_run_status_json("running"))
        if request.method == "GET" and request.url.path == "/runs/run-1/events":
            assert request.url.params["after"] == "0-0"
            assert request.url.params["limit"] == "10"
            event = RunStartedEvent(id="1-0", run_id="run-1")
            return httpx.Response(
                200,
                json={
                    "run_id": "run-1",
                    "events": [cast(object, json.loads(RUN_EVENT_ADAPTER.dump_json(event)))],
                    "next_cursor": "1-0",
                },
            )
        if request.method == "POST" and request.url.path == "/runs/run-1/cancel":
            payload = cast(dict[str, object], json.loads(request.content))
            assert payload == {"reason": "user_cancelled", "message": None}
            return httpx.Response(202, json={"run_id": "run-1", "status": "cancelled"})
        raise AssertionError(f"unexpected request: {request.method} {request.url}")

    http_client = httpx.Client(transport=httpx.MockTransport(handler))
    client = Client(base_url="http://testserver", sync_http_client=http_client)

    created = client.create_run_sync(CreateRunRequest.model_validate(_create_run_payload()))
    status = client.get_run_sync(created.run_id)
    events = client.get_events_sync(created.run_id, after="0-0", limit=10)
    cancelled = client.cancel_run_sync(created.run_id, CancelRunRequest(reason="user_cancelled"))

    assert created.status == "running"
    assert status.status == "running"
    assert isinstance(events, RunEventsResponse)
    assert [event.type for event in events.events] == ["run_started"]
    assert isinstance(cancelled, CancelRunResponse)
    assert cancelled.status == "cancelled"


def test_async_methods_and_wait_run_parse_protocol_dtos() -> None:
    statuses = iter(["running", "succeeded"])

    def handler(request: httpx.Request) -> httpx.Response:
        if request.method == "POST" and request.url.path == "/runs":
            return httpx.Response(202, json={"run_id": "run-1", "status": "running"})
        if request.method == "GET" and request.url.path == "/runs/run-1":
            return httpx.Response(200, json=_run_status_json(next(statuses)))
        if request.method == "GET" and request.url.path == "/runs/run-1/events":
            return httpx.Response(200, json={"run_id": "run-1", "events": [], "next_cursor": "0-0"})
        raise AssertionError(f"unexpected request: {request.method} {request.url}")

    async def scenario() -> None:
        http_client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
        client = Client(base_url="http://testserver", async_http_client=http_client)
        request = CreateRunRequest.model_validate(_create_run_payload())

        created = await client.create_run(request)
        events = await client.get_events(created.run_id)
        terminal = await client.wait_run(created.run_id, poll_interval_seconds=0)

        assert created.run_id == "run-1"
        assert events.events == []
        assert terminal.status == "succeeded"
        await http_client.aclose()

    asyncio.run(scenario())


def test_cancel_run_and_wait_sync_resumes_after_cursor_and_returns_cancelled_snapshot() -> None:
    snapshot = SessionSnapshot(layers={})

    def handler(request: httpx.Request) -> httpx.Response:
        if request.method == "POST":
            return httpx.Response(202, json={"run_id": "run-1", "status": "cancelled"})
        if request.url.path == "/runs/run-1":
            return httpx.Response(
                200,
                json={
                    "run_id": "run-1",
                    "status": "running",
                    "created_at": "2026-08-17T00:00:00Z",
                    "updated_at": "2026-08-17T00:00:00Z",
                },
            )
        assert request.url.params["after"] == "3-0"
        event = RunCancelledEvent(
            id="4-0",
            run_id="run-1",
            data=RunCancelledEventData(reason="stopped", session_snapshot=snapshot),
        )
        return httpx.Response(200, content=_event_frame(event))

    client = Client(
        base_url="http://testserver",
        sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)),
    )

    event = client.cancel_run_and_wait_sync(
        "run-1",
        CancelRunRequest(reason="stopped"),
        after="3-0",
    )

    assert event.data.session_snapshot == snapshot


def test_cancel_run_and_wait_sync_replays_when_cursor_already_points_to_cancelled_event() -> None:
    def handler(request: httpx.Request) -> httpx.Response:
        if request.method == "POST":
            return httpx.Response(202, json={"run_id": "run-1", "status": "cancelled"})
        if request.url.path == "/runs/run-1":
            return httpx.Response(
                200,
                json={
                    "run_id": "run-1",
                    "status": "cancelled",
                    "created_at": "2026-08-17T00:00:00Z",
                    "updated_at": "2026-08-17T00:00:01Z",
                },
            )
        assert request.url.params["after"] == "0-0"
        return httpx.Response(200, content=_event_frame(RunCancelledEvent(id="4-0", run_id="run-1")))

    client = Client(
        base_url="http://testserver",
        sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)),
    )

    event = client.cancel_run_and_wait_sync("run-1", after="4-0")

    assert event.id == "4-0"


def test_cancel_run_and_wait_async_returns_cancelled_terminal() -> None:
    def handler(request: httpx.Request) -> httpx.Response:
        if request.method == "POST":
            return httpx.Response(202, json={"run_id": "run-1", "status": "cancelled"})
        if request.url.path == "/runs/run-1":
            return httpx.Response(200, json=_run_status_json("running"))
        assert request.url.params["after"] == "1-0"
        return httpx.Response(200, content=_event_frame(RunCancelledEvent(id="2-0", run_id="run-1")))

    async def scenario() -> None:
        http_client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
        client = Client(base_url="http://testserver", async_http_client=http_client)
        event = await client.cancel_run_and_wait("run-1", after="1-0")
        assert event.type == "run_cancelled"
        await http_client.aclose()

    asyncio.run(scenario())


def test_cancel_run_and_wait_async_replays_when_cursor_already_points_to_cancelled_event() -> None:
    def handler(request: httpx.Request) -> httpx.Response:
        if request.method == "POST":
            return httpx.Response(202, json={"run_id": "run-1", "status": "cancelled"})
        if request.url.path == "/runs/run-1":
            return httpx.Response(200, json=_run_status_json("cancelled"))
        assert request.url.params["after"] == "0-0"
        return httpx.Response(200, content=_event_frame(RunCancelledEvent(id="4-0", run_id="run-1")))

    async def scenario() -> None:
        http_client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
        client = Client(base_url="http://testserver", async_http_client=http_client)
        event = await client.cancel_run_and_wait("run-1", after="4-0")
        assert event.id == "4-0"
        await http_client.aclose()

    asyncio.run(scenario())


def test_sync_binding_file_methods_post_dtos_and_parse_responses() -> None:
    def handler(request: httpx.Request) -> httpx.Response:
        if request.url.path == "/execution-bindings/files/list":
            payload = cast(dict[str, object], json.loads(request.content))
            assert payload["path"] == "."
            assert payload["backend_binding_ref"] == "binding-ref"
            return httpx.Response(200, json={"path": ".", "entries": [], "truncated": False})
        if request.url.path == "/execution-bindings/files/read":
            payload = cast(dict[str, object], json.loads(request.content))
            assert payload["path"] == "note.txt"
            assert payload["max_bytes"] == 128
            return httpx.Response(
                200, json={"path": "note.txt", "size": 5, "truncated": False, "binary": False, "text": "hello"}
            )
        if request.url.path == "/execution-bindings/files/download":
            _assert_binding_download_timeout(request)
            payload = cast(dict[str, object], json.loads(request.content))
            assert payload["path"] == "report.txt"
            return httpx.Response(
                200,
                json={"reference": "dify-file-ref:file-1"},
            )
        raise AssertionError(f"unexpected request: {request.method} {request.url}")

    client = Client(base_url="http://testserver", sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)))

    listing = client.list_binding_files_sync("binding-ref", ".")
    preview = client.read_binding_file_sync("binding-ref", "note.txt", max_bytes=128)
    downloaded = client.download_binding_file_sync(_binding_file_download_request())

    assert isinstance(listing, BindingFileListResponse)
    assert listing.path == "."
    assert isinstance(preview, BindingFileReadResponse)
    assert preview.text == "hello"
    assert isinstance(downloaded, BindingFileDownloadResponse)
    assert downloaded.reference == "dify-file-ref:file-1"


def test_async_binding_file_methods_post_dtos_and_parse_responses() -> None:
    def handler(request: httpx.Request) -> httpx.Response:
        if request.url.path == "/execution-bindings/files/list":
            return httpx.Response(200, json={"path": ".", "entries": [], "truncated": False})
        if request.url.path == "/execution-bindings/files/read":
            payload = cast(dict[str, object], json.loads(request.content))
            assert payload["max_bytes"] == 262144
            return httpx.Response(
                200, json={"path": "note.txt", "size": 5, "truncated": False, "binary": False, "text": "hello"}
            )
        if request.url.path == "/execution-bindings/files/download":
            _assert_binding_download_timeout(request, expected=123.5)
            return httpx.Response(200, json={"reference": "dify-file-ref:file-1"})
        raise AssertionError(f"unexpected request: {request.method} {request.url}")

    async def scenario() -> None:
        http_client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
        client = Client(
            base_url="http://testserver",
            binding_file_download_timeout=123.5,
            async_http_client=http_client,
        )

        listing = await client.list_binding_files("binding-ref", ".")
        preview = await client.read_binding_file("binding-ref", "note.txt")
        downloaded = await client.download_binding_file(_binding_file_download_request())

        assert listing.path == "."
        assert preview.text == "hello"
        assert downloaded.reference == "dify-file-ref:file-1"
        await http_client.aclose()

    asyncio.run(scenario())


def test_sync_execution_binding_client_uses_private_binding_routes() -> None:
    def handler(request: httpx.Request) -> httpx.Response:
        payload = cast(dict[str, object], json.loads(request.content))
        if request.url.path == "/execution-bindings":
            assert payload["binding_id"] == "binding-1"
            assert payload["home_snapshot_ref"] == "home-ref"
            return httpx.Response(201, json={"binding_ref": "backend-binding", "workspace_ref": "backend-workspace"})
        assert request.url.path == "/execution-bindings/destroy"
        assert payload == {
            "binding_ref": "backend-binding",
            "destroy_workspace": True,
            "workspace_ref": "backend-workspace",
        }
        return httpx.Response(204)

    client = Client(
        base_url="http://testserver",
        sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)),
    )
    allocation = client.create_execution_binding_sync(
        CreateExecutionBindingRequest(
            tenant_id="tenant-1",
            agent_id="agent-1",
            binding_id="binding-1",
            workspace_id="workspace-1",
            existing_workspace_ref=None,
            home_snapshot_ref="home-ref",
        )
    )
    client.destroy_execution_binding_sync(
        DestroyExecutionBindingRequest(
            binding_ref=allocation.binding_ref,
            workspace_ref=allocation.workspace_ref,
            destroy_workspace=True,
        )
    )

    assert allocation.binding_ref == "backend-binding"


def _create_home_snapshot_from_binding_request() -> CreateHomeSnapshotFromBindingRequest:
    return CreateHomeSnapshotFromBindingRequest(
        tenant_id="tenant-1",
        agent_id="agent-1",
        home_snapshot_id="home-2",
        backend_binding_ref="binding-ref",
    )


def test_sync_home_snapshot_client_parses_checkpoint_and_delete() -> None:
    def handler(request: httpx.Request) -> httpx.Response:
        if request.method == "POST":
            if request.url.path == "/home-snapshots/from-binding":
                assert json.loads(request.content) == _create_home_snapshot_from_binding_request().model_dump(
                    mode="json"
                )
                return httpx.Response(201, json={"snapshot_ref": "team/home 1"})
            assert request.url.path == "/home-snapshots/delete"
            assert json.loads(request.content) == {"snapshot_ref": "team/home 1"}
            return httpx.Response(204)
        raise AssertionError(request.url)

    http_client = httpx.Client(transport=httpx.MockTransport(handler))
    client = Client(base_url="http://testserver", sync_http_client=http_client)

    created = client.create_home_snapshot_from_binding_sync(_create_home_snapshot_from_binding_request())
    client.delete_home_snapshot_sync(created.snapshot_ref)

    assert created.snapshot_ref == "team/home 1"
    http_client.close()


def test_async_home_snapshot_client_parses_checkpoint_and_delete() -> None:
    def handler(request: httpx.Request) -> httpx.Response:
        if request.method == "POST":
            if request.url.path == "/home-snapshots/from-binding":
                return httpx.Response(201, json={"snapshot_ref": "team/home 1"})
            assert request.url.path == "/home-snapshots/delete"
            return httpx.Response(204)
        raise AssertionError(request.url)

    async def scenario() -> None:
        http_client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
        client = Client(base_url="http://testserver", async_http_client=http_client)

        created = await client.create_home_snapshot_from_binding(_create_home_snapshot_from_binding_request())
        await client.delete_home_snapshot(created.snapshot_ref)

        assert created.snapshot_ref == "team/home 1"
        await http_client.aclose()

    asyncio.run(scenario())


def test_home_snapshot_client_maps_sync_validation_and_async_http_errors() -> None:
    sync_http_client = httpx.Client(transport=httpx.MockTransport(lambda _request: httpx.Response(200, json={})))
    sync_client = Client(
        base_url="http://testserver",
        sync_http_client=sync_http_client,
    )

    with pytest.raises(DifyAgentValidationError):
        _ = sync_client.create_home_snapshot_from_binding_sync(_create_home_snapshot_from_binding_request())
    sync_http_client.close()

    async def scenario() -> None:
        http_client = httpx.AsyncClient(
            transport=httpx.MockTransport(
                lambda _request: httpx.Response(502, json={"detail": {"code": "backend_failed"}})
            )
        )
        client = Client(base_url="http://testserver", async_http_client=http_client)

        with pytest.raises(DifyAgentHTTPError) as exc_info:
            _ = await client.create_home_snapshot_from_binding(_create_home_snapshot_from_binding_request())
        assert exc_info.value.status_code == 502
        assert exc_info.value.detail == {"code": "backend_failed"}
        await http_client.aclose()

    asyncio.run(scenario())


def test_sync_download_binding_file_rejects_missing_reference() -> None:
    def handler(request: httpx.Request) -> httpx.Response:
        if request.url.path != "/execution-bindings/files/download":
            raise AssertionError(f"unexpected request: {request.method} {request.url}")
        return httpx.Response(
            200,
            json={},
        )

    client = Client(base_url="http://testserver", sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)))

    with pytest.raises(DifyAgentValidationError):
        _ = client.download_binding_file_sync(_binding_file_download_request())


def test_sync_binding_file_methods_map_invalid_json_to_validation_error() -> None:
    responses = iter([httpx.Response(200, text="not-json"), httpx.Response(404, json={"detail": "missing"})])

    def handler(_request: httpx.Request) -> httpx.Response:
        return next(responses)

    client = Client(base_url="http://testserver", sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)))

    with pytest.raises(DifyAgentValidationError):
        _ = client.list_binding_files_sync("binding-ref", ".")

    with pytest.raises(DifyAgentHTTPError) as http_error:
        _ = client.read_binding_file_sync("binding-ref", "missing.txt")
    assert http_error.value.status_code == 404


def test_error_mapping_and_create_run_input_validation() -> None:
    responses = iter(
        [
            httpx.Response(404, json={"detail": "run not found"}),
            httpx.Response(422, json={"detail": "invalid"}),
            httpx.Response(500, json={"detail": "boom"}),
        ]
    )

    def handler(_request: httpx.Request) -> httpx.Response:
        return next(responses)

    client = Client(
        base_url="http://testserver",
        sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)),
    )

    with pytest.raises(DifyAgentNotFoundError) as not_found:
        _ = client.get_run_sync("missing")
    assert not_found.value.status_code == 404
    assert not_found.value.detail == "run not found"

    with pytest.raises(DifyAgentValidationError) as validation:
        _ = client.get_run_sync("bad")
    assert validation.value.status_code == 422

    with pytest.raises(DifyAgentHTTPError) as server_error:
        _ = client.get_run_sync("bad")
    assert server_error.value.status_code == 500

    with pytest.raises(DifyAgentValidationError):
        _ = client.create_run_sync({"unknown": "field"})  # pyright: ignore[reportArgumentType]


def test_http_timeout_maps_to_client_timeout_error() -> None:
    def handler(request: httpx.Request) -> httpx.Response:
        raise httpx.ReadTimeout("slow", request=request)

    client = Client(
        base_url="http://testserver",
        sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)),
    )

    with pytest.raises(DifyAgentTimeoutError):
        _ = client.get_run_sync("run-1")


def test_create_run_is_not_retried_after_timeout() -> None:
    attempts = 0

    def handler(request: httpx.Request) -> httpx.Response:
        nonlocal attempts
        attempts += 1
        raise httpx.ConnectTimeout("cannot connect", request=request)

    client = Client(
        base_url="http://testserver",
        sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)),
    )

    with pytest.raises(DifyAgentTimeoutError):
        _ = client.create_run_sync(CreateRunRequest.model_validate(_create_run_payload()))
    assert attempts == 1


def test_sync_sse_parser_supports_comments_multiline_data_and_id_fill() -> None:
    payload = RUN_EVENT_ADAPTER.dump_json(RunStartedEvent(run_id="run-1"), exclude={"id"}).decode()
    before_type, after_type = payload.split('"type"', maxsplit=1)
    body = f': keepalive\nid: 5-0\nevent: run_started\ndata: {before_type}\ndata: "type"{after_type}\n\n'

    def handler(request: httpx.Request) -> httpx.Response:
        assert request.url.params["after"] == "0-0"
        return httpx.Response(200, content=body)

    client = Client(
        base_url="http://testserver",
        sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)),
    )

    events = list(client.stream_events_sync("run-1", until_terminal=False, reconnect=False))

    assert [event.id for event in events] == ["5-0"]
    assert [event.type for event in events] == ["run_started"]


@pytest.mark.parametrize("separator", ["\x85", "\u2028", "\u2029"])
def test_sync_sse_parser_preserves_unicode_line_separators(separator: str) -> None:
    error = f"before{separator}after"
    body = _event_frame(_run_failed_event(error))

    def handler(_request: httpx.Request) -> httpx.Response:
        return httpx.Response(200, content=body)

    client = Client(
        base_url="http://testserver",
        sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)),
    )

    events = list(client.stream_events_sync("run-1", reconnect=False))

    assert len(events) == 1
    assert isinstance(events[0], RunFailedEvent)
    assert events[0].data.error == error


def test_stream_events_stops_after_terminal_event() -> None:
    calls = 0
    body = "".join(
        [
            _event_frame(RunStartedEvent(id="1-0", run_id="run-1")),
            _event_frame(_run_succeeded_event()),
        ]
    )

    def handler(_request: httpx.Request) -> httpx.Response:
        nonlocal calls
        calls += 1
        return httpx.Response(200, content=body)

    client = Client(
        base_url="http://testserver",
        sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)),
    )

    events = list(client.stream_events_sync("run-1", reconnect_delay_seconds=0))

    assert [event.type for event in events] == ["run_started", "run_succeeded"]
    assert calls == 1


def test_stream_events_stops_after_cancelled_terminal_event() -> None:
    calls = 0
    body = "".join(
        [
            _event_frame(RunStartedEvent(id="1-0", run_id="run-1")),
            _event_frame(RunCancelledEvent(id="2-0", run_id="run-1")),
        ]
    )

    def handler(_request: httpx.Request) -> httpx.Response:
        nonlocal calls
        calls += 1
        return httpx.Response(200, content=body)

    client = Client(
        base_url="http://testserver",
        sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)),
    )

    events = list(client.stream_events_sync("run-1", reconnect_delay_seconds=0))

    assert [event.type for event in events] == ["run_started", "run_cancelled"]
    assert calls == 1


def test_stream_events_does_not_reconnect_after_terminal_when_until_terminal_is_false() -> None:
    calls = 0

    def handler(_request: httpx.Request) -> httpx.Response:
        nonlocal calls
        calls += 1
        return httpx.Response(200, content=_event_frame(_run_succeeded_event()))

    client = Client(
        base_url="http://testserver",
        sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)),
    )

    events = list(client.stream_events_sync("run-1", until_terminal=False, reconnect_delay_seconds=0))

    assert [event.type for event in events] == ["run_succeeded"]
    assert calls == 1


def test_stream_events_does_not_reconnect_after_terminal_transport_error() -> None:
    calls = 0

    def handler(_request: httpx.Request) -> httpx.Response:
        nonlocal calls
        calls += 1
        return httpx.Response(200, stream=DisconnectingSyncStream(_event_frame(_run_succeeded_event())))

    client = Client(
        base_url="http://testserver",
        sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)),
    )

    events = list(client.stream_events_sync("run-1", until_terminal=False, reconnect_delay_seconds=0))

    assert [event.type for event in events] == ["run_succeeded"]
    assert calls == 1


def test_stream_events_reconnects_from_latest_event_id() -> None:
    seen_after: list[str] = []

    def handler(request: httpx.Request) -> httpx.Response:
        seen_after.append(request.url.params["after"])
        if len(seen_after) == 1:
            return httpx.Response(
                200,
                stream=DisconnectingSyncStream(_event_frame(RunStartedEvent(id="1-0", run_id="run-1"))),
            )
        return httpx.Response(200, content=_event_frame(_run_succeeded_event()))

    client = Client(
        base_url="http://testserver",
        sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)),
    )

    events = list(client.stream_events_sync("run-1", reconnect_delay_seconds=0))

    assert seen_after == ["0-0", "1-0"]
    assert [event.type for event in events] == ["run_started", "run_succeeded"]


def test_stream_events_reconnects_after_http_5xx_response() -> None:
    seen_after: list[str] = []

    def handler(request: httpx.Request) -> httpx.Response:
        seen_after.append(request.url.params["after"])
        if len(seen_after) == 1:
            return httpx.Response(503, json={"detail": "temporarily unavailable"})
        return httpx.Response(200, content=_event_frame(_run_succeeded_event()))

    client = Client(
        base_url="http://testserver",
        sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)),
    )

    events = list(client.stream_events_sync("run-1", reconnect_delay_seconds=0))

    assert seen_after == ["0-0", "0-0"]
    assert [event.type for event in events] == ["run_succeeded"]


def test_stream_events_raises_when_reconnects_are_exhausted() -> None:
    calls = 0

    def handler(_request: httpx.Request) -> httpx.Response:
        nonlocal calls
        calls += 1
        return httpx.Response(200, stream=DisconnectingSyncStream())

    client = Client(
        base_url="http://testserver",
        sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)),
    )

    with pytest.raises(DifyAgentStreamError):
        _ = list(client.stream_events_sync("run-1", max_reconnects=1, reconnect_delay_seconds=0))
    assert calls == 2


def test_stream_events_default_reconnect_budget_is_finite() -> None:
    calls = 0

    def handler(_request: httpx.Request) -> httpx.Response:
        nonlocal calls
        calls += 1
        return httpx.Response(200, content="")

    client = Client(
        base_url="http://testserver",
        sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)),
    )

    with pytest.raises(DifyAgentStreamError, match="reconnect attempts exhausted"):
        _ = list(client.stream_events_sync("run-1", reconnect_delay_seconds=0))
    assert calls == 4


def test_stream_events_enforces_total_timeout_before_connecting() -> None:
    calls = 0

    def handler(_request: httpx.Request) -> httpx.Response:
        nonlocal calls
        calls += 1
        return httpx.Response(200, content="")

    client = Client(
        base_url="http://testserver",
        sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)),
    )

    with pytest.raises(DifyAgentTimeoutError, match="exceeded its timeout"):
        _ = list(client.stream_events_sync("run-1", timeout_seconds=0))
    assert calls == 0


def test_stream_events_observes_caller_stop_on_heartbeat() -> None:
    stop_checks = 0

    def should_stop() -> bool:
        nonlocal stop_checks
        stop_checks += 1
        return stop_checks >= 2

    def handler(_request: httpx.Request) -> httpx.Response:
        return httpx.Response(200, content=": keepalive\n\n")

    client = Client(
        base_url="http://testserver",
        sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)),
    )

    with pytest.raises(DifyAgentStreamError, match="cancelled by the caller"):
        _ = list(client.stream_events_sync("run-1", should_stop=should_stop))
    assert stop_checks == 2


def test_malformed_sse_frame_does_not_reconnect() -> None:
    calls = 0

    def handler(_request: httpx.Request) -> httpx.Response:
        nonlocal calls
        calls += 1
        return httpx.Response(200, content="data: not-json\n\n")

    client = Client(
        base_url="http://testserver",
        sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)),
    )

    with pytest.raises(DifyAgentStreamError):
        _ = list(client.stream_events_sync("run-1", reconnect_delay_seconds=0))
    assert calls == 1


def test_async_stream_events_yields_terminal_event() -> None:
    body = _event_frame(_run_succeeded_event())

    def handler(_request: httpx.Request) -> httpx.Response:
        return httpx.Response(200, content=body)

    async def scenario() -> None:
        http_client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
        client = Client(base_url="http://testserver", async_http_client=http_client)

        events = [event async for event in client.stream_events("run-1")]

        assert [event.type for event in events] == ["run_succeeded"]
        await http_client.aclose()

    asyncio.run(scenario())


def test_async_stream_events_enforces_total_timeout_before_connecting() -> None:
    calls = 0

    def handler(_request: httpx.Request) -> httpx.Response:
        nonlocal calls
        calls += 1
        return httpx.Response(200, content="")

    async def scenario() -> None:
        async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http_client:
            client = Client(base_url="http://testserver", async_http_client=http_client)

            with pytest.raises(DifyAgentTimeoutError, match="exceeded its timeout"):
                _ = [event async for event in client.stream_events("run-1", timeout_seconds=0)]

    asyncio.run(scenario())

    assert calls == 0


def test_async_stream_events_does_not_reconnect_after_terminal_when_until_terminal_is_false() -> None:
    calls = 0

    def handler(_request: httpx.Request) -> httpx.Response:
        nonlocal calls
        calls += 1
        return httpx.Response(200, content=_event_frame(_run_succeeded_event()))

    async def scenario() -> None:
        http_client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
        client = Client(base_url="http://testserver", async_http_client=http_client)

        events = [event async for event in client.stream_events("run-1", until_terminal=False)]

        assert [event.type for event in events] == ["run_succeeded"]
        assert calls == 1
        await http_client.aclose()

    asyncio.run(scenario())


def test_async_stream_events_does_not_reconnect_after_terminal_transport_error() -> None:
    calls = 0

    def handler(_request: httpx.Request) -> httpx.Response:
        nonlocal calls
        calls += 1
        return httpx.Response(200, stream=DisconnectingAsyncStream(_event_frame(_run_succeeded_event())))

    async def scenario() -> None:
        http_client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
        client = Client(base_url="http://testserver", async_http_client=http_client)

        events = [event async for event in client.stream_events("run-1", until_terminal=False)]

        assert [event.type for event in events] == ["run_succeeded"]
        assert calls == 1
        await http_client.aclose()

    asyncio.run(scenario())


def test_async_stream_events_reconnects_from_latest_event_after_transport_error() -> None:
    seen_after: list[str] = []

    def handler(request: httpx.Request) -> httpx.Response:
        seen_after.append(request.url.params["after"])
        if len(seen_after) == 1:
            return httpx.Response(
                200,
                stream=DisconnectingAsyncStream(_event_frame(RunStartedEvent(id="1-0", run_id="run-1"))),
            )
        return httpx.Response(200, content=_event_frame(_run_succeeded_event()))

    async def scenario() -> None:
        http_client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
        client = Client(base_url="http://testserver", async_http_client=http_client)

        events = [event async for event in client.stream_events("run-1", reconnect_delay_seconds=0)]

        assert seen_after == ["0-0", "1-0"]
        assert [event.type for event in events] == ["run_started", "run_succeeded"]
        await http_client.aclose()

    asyncio.run(scenario())


def test_async_stream_events_reconnects_after_eof_before_terminal() -> None:
    calls = 0

    def handler(_request: httpx.Request) -> httpx.Response:
        nonlocal calls
        calls += 1
        return httpx.Response(200, content="")

    async def scenario() -> None:
        http_client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
        client = Client(base_url="http://testserver", async_http_client=http_client)

        with pytest.raises(DifyAgentStreamError, match="reconnect attempts exhausted"):
            _ = [
                event
                async for event in client.stream_events(
                    "run-1",
                    max_reconnects=1,
                    reconnect_delay_seconds=0,
                )
            ]

        assert calls == 2
        await http_client.aclose()

    asyncio.run(scenario())


def test_async_sse_parser_preserves_unicode_line_separators() -> None:
    error = "next-line:\x85line-separator:\u2028paragraph-separator:\u2029done"
    body = _event_frame(_run_failed_event(error))

    def handler(_request: httpx.Request) -> httpx.Response:
        return httpx.Response(200, content=body)

    async def scenario() -> None:
        http_client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
        client = Client(base_url="http://testserver", async_http_client=http_client)

        events = [event async for event in client.stream_events("run-1")]

        assert len(events) == 1
        assert isinstance(events[0], RunFailedEvent)
        assert events[0].data.error == error
        await http_client.aclose()

    asyncio.run(scenario())


def test_async_stream_events_reconnects_after_http_5xx_response() -> None:
    seen_after: list[str] = []

    def handler(request: httpx.Request) -> httpx.Response:
        seen_after.append(request.url.params["after"])
        if len(seen_after) == 1:
            return httpx.Response(502, json={"detail": "bad gateway"})
        return httpx.Response(200, content=_event_frame(_run_succeeded_event()))

    async def scenario() -> None:
        http_client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
        client = Client(base_url="http://testserver", async_http_client=http_client)

        events = [event async for event in client.stream_events("run-1", reconnect_delay_seconds=0)]

        assert seen_after == ["0-0", "0-0"]
        assert [event.type for event in events] == ["run_succeeded"]
        await http_client.aclose()

    asyncio.run(scenario())


def test_stream_timeout_can_reconnect_until_terminal() -> None:
    calls = 0

    def handler(request: httpx.Request) -> httpx.Response:
        nonlocal calls
        calls += 1
        if calls == 1:
            raise httpx.ReadTimeout("stream stalled", request=request)
        return httpx.Response(200, content=_event_frame(_run_succeeded_event()))

    client = Client(
        base_url="http://testserver",
        sync_http_client=httpx.Client(transport=httpx.MockTransport(handler)),
    )

    events = list(client.stream_events_sync("run-1", reconnect_delay_seconds=0))

    assert calls == 2
    assert [event.type for event in events] == ["run_succeeded"]