feat(web): orchestrator events read API + SSE stream

GET /api/v1/orchestrator/events — paginated list with optional
kind=traffic|file filter. GET /api/v1/orchestrator/events/stream —
SSE: snapshot on connect, live forward of orchestrator.> bus events
mapped to 'traffic' / 'file' SSE event names.

Repo gains list_orchestrator_events(limit, offset, kind?, since_ts?),
count_orchestrator_events(kind?), and prune_orchestrator_events
(per_dst_cap=10000) for periodic worker-side trimming.

tests/api/orchestrator/test_events_stream.py

@@ -0,0 +1,166 @@
+"""SSE events stream + list — /api/v1/orchestrator/events{,/stream}."""
+from __future__ import annotations
+
+import asyncio
+from unittest.mock import AsyncMock, patch
+
+import httpx
+import pytest
+
+from decnet.bus import app as _bus_app
+from decnet.bus import topics as _topics
+from decnet.bus.fake import FakeBus
+from decnet.web.api import app
+
+_V1 = "/api/v1/orchestrator"
+
+
+@pytest.fixture
+def _fake_app_bus(monkeypatch):
+    bus = FakeBus()
+
+    async def _get() -> FakeBus:
+        if not bus._connected:
+            await bus.connect()
+        return bus
+
+    monkeypatch.setattr(_bus_app, "get_app_bus", _get)
+    from decnet.web.router.orchestrator import api_events as _ev
+    monkeypatch.setattr(_ev, "get_app_bus", _get)
+    return bus
+
+
+@pytest.mark.anyio
+async def test_events_unauthenticated_401():
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app), base_url="http://test",
+    ) as ac:
+        r = await ac.get(f"{_V1}/events")
+        assert r.status_code == 401
+
+
+@pytest.mark.anyio
+async def test_stream_unauthenticated_401():
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app), base_url="http://test",
+    ) as ac:
+        r = await ac.get(f"{_V1}/events/stream")
+        assert r.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_list_returns_paginated_envelope():
+    from decnet.web.router.orchestrator.api_list_events import (
+        list_orchestrator_events,
+    )
+
+    rows = [{"uuid": f"e-{n}", "kind": "traffic"} for n in range(3)]
+    with patch(
+        "decnet.web.router.orchestrator.api_list_events.repo"
+    ) as mock_repo:
+        mock_repo.list_orchestrator_events = AsyncMock(return_value=rows)
+        mock_repo.count_orchestrator_events = AsyncMock(return_value=3)
+
+        result = await list_orchestrator_events(
+            limit=50, offset=0, kind=None,
+            user={"uuid": "u", "role": "viewer"},
+        )
+
+    assert result == {"total": 3, "limit": 50, "offset": 0, "data": rows}
+    mock_repo.list_orchestrator_events.assert_awaited_once_with(
+        limit=50, offset=0, kind=None,
+    )
+
+
+@pytest.mark.asyncio
+async def test_list_forwards_kind_filter():
+    from decnet.web.router.orchestrator.api_list_events import (
+        list_orchestrator_events,
+    )
+
+    with patch(
+        "decnet.web.router.orchestrator.api_list_events.repo"
+    ) as mock_repo:
+        mock_repo.list_orchestrator_events = AsyncMock(return_value=[])
+        mock_repo.count_orchestrator_events = AsyncMock(return_value=0)
+
+        await list_orchestrator_events(
+            limit=10, offset=20, kind="file",
+            user={"uuid": "u", "role": "viewer"},
+        )
+
+    mock_repo.list_orchestrator_events.assert_awaited_once_with(
+        limit=10, offset=20, kind="file",
+    )
+    mock_repo.count_orchestrator_events.assert_awaited_once_with(kind="file")
+
+
+@pytest.mark.anyio
+async def test_stream_emits_snapshot_and_live_events(_fake_app_bus):
+    from decnet.web.router.orchestrator import api_events as _ev
+
+    class _FakeRequest:
+        async def is_disconnected(self) -> bool:
+            return False
+
+    with patch(
+        "decnet.web.router.orchestrator.api_events.repo"
+    ) as mock_repo:
+        mock_repo.list_orchestrator_events = AsyncMock(return_value=[])
+        response = await _ev.api_orchestrator_events(
+            request=_FakeRequest(),  # type: ignore[arg-type]
+            user={"role": "admin", "uuid": "00000000-0000-0000-0000-000000000000"},
+        )
+
+    gen = response.body_iterator
+
+    def _as_text(frame) -> str:
+        return frame if isinstance(frame, str) else frame.decode()
+
+    async def _publish_after_snapshot() -> None:
+        await asyncio.sleep(0.1)
+        await _fake_app_bus.publish(
+            _topics.orchestrator(_topics.ORCHESTRATOR_TRAFFIC, "decky-1"),
+            {"action": "exec:uptime", "success": True},
+            event_type=_topics.ORCHESTRATOR_TRAFFIC,
+        )
+        await asyncio.sleep(0.05)
+        await _fake_app_bus.publish(
+            _topics.orchestrator(_topics.ORCHESTRATOR_FILE, "decky-1"),
+            {"action": "file:create", "success": True},
+            event_type=_topics.ORCHESTRATOR_FILE,
+        )
+
+    pub_task = asyncio.create_task(_publish_after_snapshot())
+
+    async def _drive():
+        saw = {"snapshot": False, "traffic": False, "file": False}
+        for _ in range(8):
+            frame = _as_text(await gen.__anext__())
+            for key in saw:
+                if f"event: {key}" in frame:
+                    saw[key] = True
+            if all(saw.values()):
+                break
+        return saw
+
+    try:
+        seen = await asyncio.wait_for(_drive(), timeout=5.0)
+    finally:
+        pub_task.cancel()
+        try:
+            await pub_task
+        except (asyncio.CancelledError, Exception):
+            pass
+        await gen.aclose()
+
+    assert seen["snapshot"]
+    assert seen["traffic"]
+    assert seen["file"]
+
+
+def test_sse_name_maps_topic_to_kind():
+    from decnet.web.router.orchestrator.api_events import _sse_name_for
+    assert _sse_name_for("orchestrator.traffic.decky-1") == "traffic"
+    assert _sse_name_for("orchestrator.file.decky-1") == "file"
+    assert _sse_name_for("system.bus.health") == "system.bus.health"

tests/orchestrator/test_repo_pagination.py

@@ -0,0 +1,107 @@
+"""Pagination + filter + prune for orchestrator_events repo methods."""
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from decnet.web.db.models import Topology, TopologyDecky
+from decnet.web.db.sqlite.repository import SQLiteRepository
+
+
+async def _make_repo(tmp_path, name: str) -> SQLiteRepository:
+    r = SQLiteRepository(db_path=str(tmp_path / name))
+    await r.initialize()
+    return r
+
+
+@pytest.mark.asyncio
+async def test_empty_table_zero_total(tmp_path):
+    repo = await _make_repo(tmp_path, "orch.db")
+    assert await repo.list_orchestrator_events(limit=50, offset=0) == []
+    assert await repo.count_orchestrator_events() == 0
+
+
+async def _seed_decky(repo: SQLiteRepository, name: str = "d-1") -> str:
+    async with repo._session() as session:
+        topo = Topology(name=f"t-{name}", config_snapshot="{}", status="active")
+        session.add(topo)
+        await session.commit()
+        await session.refresh(topo)
+        d = TopologyDecky(
+            topology_id=topo.id, name=name,
+            services=json.dumps(["ssh"]), ip="10.0.0.2", state="running",
+        )
+        session.add(d)
+        await session.commit()
+        await session.refresh(d)
+        return d.uuid
+
+
+async def _seed(
+    repo: SQLiteRepository,
+    n: int = 5,
+    kind: str = "traffic",
+    dst: str | None = None,
+) -> str:
+    if dst is None:
+        dst = await _seed_decky(repo, "decky-A")
+    for i in range(n):
+        await repo.record_orchestrator_event({
+            "kind": kind,
+            "protocol": "ssh",
+            "action": f"exec:{i}",
+            "src_decky_uuid": None,
+            "dst_decky_uuid": dst,
+            "success": True,
+            "payload": {"i": i},
+        })
+    return dst
+
+
+@pytest.mark.asyncio
+async def test_pagination_respects_limit_offset(tmp_path):
+    repo = await _make_repo(tmp_path, "p.db")
+    await _seed(repo, n=5)
+
+    assert await repo.count_orchestrator_events() == 5
+    page1 = await repo.list_orchestrator_events(limit=2, offset=0)
+    page2 = await repo.list_orchestrator_events(limit=2, offset=2)
+    assert len(page1) == 2
+    assert len(page2) == 2
+    assert {r["uuid"] for r in page1}.isdisjoint({r["uuid"] for r in page2})
+
+
+@pytest.mark.asyncio
+async def test_kind_filter_narrows(tmp_path):
+    repo = await _make_repo(tmp_path, "k.db")
+    dst = await _seed_decky(repo, "decky-K")
+    for i in range(3):
+        await repo.record_orchestrator_event({
+            "kind": "traffic", "protocol": "ssh", "action": f"a{i}",
+            "src_decky_uuid": None, "dst_decky_uuid": dst,
+            "success": True, "payload": {},
+        })
+    for i in range(2):
+        await repo.record_orchestrator_event({
+            "kind": "file", "protocol": "ssh", "action": f"f{i}",
+            "src_decky_uuid": None, "dst_decky_uuid": dst,
+            "success": True, "payload": {},
+        })
+
+    assert await repo.count_orchestrator_events() == 5
+    assert await repo.count_orchestrator_events(kind="traffic") == 3
+    assert await repo.count_orchestrator_events(kind="file") == 2
+
+    only_file = await repo.list_orchestrator_events(limit=50, kind="file")
+    assert {r["kind"] for r in only_file} == {"file"}
+
+
+@pytest.mark.asyncio
+async def test_prune_caps_per_dst(tmp_path):
+    repo = await _make_repo(tmp_path, "prune.db")
+    await _seed(repo, n=10)
+
+    deleted = await repo.prune_orchestrator_events(per_dst_cap=3)
+    assert deleted == 7
+    assert await repo.count_orchestrator_events() == 3