feat(maf): conversation-driven MAF roundtable (R1/R2) + server-owned stage-3 dispatch

Backend:
- Conversation API at /api/maf-roundtable/conversations: create/list/detail,
  paginated messages, atomic send+run start, owner-only isolation,
  admin read-only diagnostic access
- SSE real-time event stream (GET /conversations/{id}/stream) backed by
  ConversationEventHub + conversation_events store; multi-worker deployment doc
- Deterministic server-owned stage-3 dispatch contracts (dispatch_contracts.py):
  routing resolved from trusted MAF deployment config instead of manager-chosen
  agent ids; config.yaml keeps stage-3 routing deployment-owned
  (default_manager_agent_id / seat ids / business_routes / max_seats_per_run)
- Conversation persistence (conversations/messages stores) + v2 migration script
- Tests: conversations, conversation stream, migration, phase3 conversation dispatch

Frontend:
- Vitest test infra for MAF (vitest.maf.config.ts + test:maf script) with
  component tests for ApprovalCard/RunHeader/SessionsPage and use-maf-events
- Session form lib, flow-graph dialog / run-detail / sessions page updates,
  routes and nav tweaks
- Docs: R0 legacy interaction baseline mapping, updated implementation plan

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
董宏凯andCursor committed 2026-08-03 12:09:47 +08:00
1 parent df408831e5
commit 99642fca6c
46 files changed
+6358 -1306

No files matched your search

@@ -0,0 +1,473 @@
"""Tests for MAF roundtable V2 Conversation SSE streaming (Phase 2 / R2 + P0 fixes).
Covers:
- ConversationEventHub: generation counter, publish/subscribe, multi-subscriber.
- P0-1: race-free replay — events published during replay are not lost.
- P0-2: terminal events auto-close the stream.
- P0-4: projection dedup via source_event_id.
- SSE replay: events persisted before connect are delivered.
- after_seq cursor: reconnect resumes without duplicates.
- Heartbeat: idle connection produces ``: heartbeat`` frames.
- Concurrent subscribers: fan-out to multiple listeners.
- Ownership: non-owner gets 404 on the stream endpoint.
"""
from __future__ import annotations
import asyncio
import json
import pytest
import pytest_asyncio
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
from app.maf_roundtable.conversation_event_hub import ConversationEventHub
from app.maf_roundtable.conversation_service import (
ConversationNotFoundError,
MafConversationService,
)
from deerflow.persistence.base import Base
from deerflow.persistence.maf_roundtable import make_maf_roundtable_store
from deerflow.persistence.maf_roundtable.model import (
MafRoundtableConversationRow,
)
from deerflow.persistence.maf_roundtable.store import MafRoundtableStore
class FakeMafConfig:
enabled = True
default_mode = "structured"
default_model_name = "test-model"
default_reasoning_effort = None
default_manager_agent_id = "mgr-agent"
default_max_rounds = 8
default_write_policy = "confirm_high_risk"
admin_diagnostic_access = True
@pytest_asyncio.fixture
async def store(tmp_path):
engine = create_async_engine(f"sqlite+aiosqlite:///{tmp_path / 'stream.db'}")
async with engine.begin() as conn:
import deerflow.persistence.maf_roundtable.model # noqa: F401
await conn.run_sync(Base.metadata.create_all)
sf = async_sessionmaker(engine, expire_on_commit=False)
yield make_maf_roundtable_store(sf)
await engine.dispose()
@pytest_asyncio.fixture
async def hub():
h = ConversationEventHub(heartbeat_interval=0.3)
yield h
h.shutdown()
@pytest_asyncio.fixture
async def svc(store, hub):
return MafConversationService(store, maf_config=FakeMafConfig(), event_hub=hub)
# ── ConversationEventHub unit tests ───────────────────────────────────────
@pytest.mark.asyncio
async def test_hub_publish_notifies_subscriber(hub):
sub = hub.open_subscription("c1")
assert not sub.has_pending
await hub.publish("c1")
assert sub.has_pending
changed = await sub.wait_for_change(timeout=2.0)
assert changed
sub.close()
@pytest.mark.asyncio
async def test_hub_heartbeat_on_idle(hub):
sub = hub.open_subscription("c2")
changed = await sub.wait_for_change(timeout=0.2)
assert not changed
sub.close()
@pytest.mark.asyncio
async def test_hub_multi_subscriber_fanout(hub):
sub_a = hub.open_subscription("c3")
sub_b = hub.open_subscription("c3")
await hub.publish("c3")
assert await sub_a.wait_for_change(timeout=2.0)
assert await sub_b.wait_for_change(timeout=2.0)
sub_a.close()
sub_b.close()
assert hub.conversation_subscriber_count("c3") == 0
@pytest.mark.asyncio
async def test_hub_publish_no_subscribers_is_noop(hub):
await hub.publish("c_noone")
assert hub.conversation_subscriber_count("c_noone") == 0
@pytest.mark.asyncio
async def test_hub_unsubscribe_cleans_up(hub):
sub = hub.open_subscription("c4")
assert hub.conversation_subscriber_count("c4") == 1
sub.close()
assert hub.conversation_subscriber_count("c4") == 0
@pytest.mark.asyncio
async def test_hub_shutdown_stops_subscribers():
h = ConversationEventHub(heartbeat_interval=0.2)
sub = h.open_subscription("c_shutdown")
h.shutdown()
assert h.is_closed
# After shutdown, generation should have advanced.
assert sub.has_pending or sub.current_generation > sub.seen_generation
sub.close()
# ── P0-1: Race-free replay ────────────────────────────────────────────────
@pytest.mark.asyncio
async def test_p0_1_event_during_replay_is_not_lost(svc, store, hub):
"""Event published between list_events() and subscription must be caught
by the stabilisation loop."""
conv = await svc.create_conversation(user_id="u1", title="Race")
await svc.send_message(conversation_id=conv["id"], user_id="u1", content="msg1")
await _reset_conv_to_idle(store, conv["id"])
# Simulate: subscribe, replay, then a publish sneaks in before stabilise.
sub = hub.open_subscription(conv["id"])
last_seq = 0
# Phase 1: initial replay
events = await store.conversation_events.list_events(conv["id"], after_seq=last_seq)
for evt in events:
last_seq = max(last_seq, evt["seq"])
# Event sneaks in here (between replay and stabilise)
await svc.send_message(conversation_id=conv["id"], user_id="u1", content="sneaky")
await hub.publish(conv["id"])
# Stabilise: should detect the pending generation
assert sub.has_pending
sub.mark_seen()
late_events = await store.conversation_events.list_events(conv["id"], after_seq=last_seq)
assert len(late_events) >= 1 # The sneaky event was caught
for evt in late_events:
last_seq = max(last_seq, evt["seq"])
sub.close()
@pytest.mark.asyncio
async def test_p0_1_subscribe_before_replay_catches_concurrent_publish(svc, store, hub):
"""Subscribe must be opened BEFORE any DB query so a publish during replay
is detected via generation delta."""
conv = await svc.create_conversation(user_id="u1", title="SubBefore")
sub = hub.open_subscription(conv["id"])
# No events yet
events = await store.conversation_events.list_events(conv["id"], after_seq=0)
assert len(events) == 0
# Publish arrives
await svc.send_message(conversation_id=conv["id"], user_id="u1", content="first")
await hub.publish(conv["id"])
# Stabilisation detects it
assert sub.has_pending
sub.mark_seen()
events = await store.conversation_events.list_events(conv["id"], after_seq=0)
assert len(events) >= 1
sub.close()
# ── P0-2: Terminal events auto-close stream ──────────────────────────────
@pytest.mark.asyncio
async def test_p0_2_replay_terminal_event_closes_stream():
from app.gateway.routers.maf_conversations import _TERMINAL_EVENT_TYPES, _is_terminal
assert "run.completed" in _TERMINAL_EVENT_TYPES
assert "run.error" in _TERMINAL_EVENT_TYPES
assert "run.cancelled" in _TERMINAL_EVENT_TYPES
assert _is_terminal({"type": "run.completed"})
assert _is_terminal({"type": "run.error"})
assert _is_terminal({"type": "run.cancelled"})
assert not _is_terminal({"type": "agent.message.delta"})
assert not _is_terminal({"type": "user.message.created"})
@pytest.mark.asyncio
async def test_p0_2_terminal_event_in_replay_stops_generator(store):
"""If the replay phase hits a terminal event, the generator should stop."""
from app.gateway.routers.maf_conversations import _is_terminal
# Simulate a conversation with events ending in run.completed
events = [
{"seq": 1, "type": "user.message.created"},
{"seq": 2, "type": "agent.message.delta"},
{"seq": 3, "type": "run.completed"},
{"seq": 4, "type": "should_not_reach"},
]
found_terminal = False
for evt in events:
if _is_terminal(evt):
found_terminal = True
break
assert found_terminal
# Verify the event after terminal would not be reached
terminal_idx = next(i for i, e in enumerate(events) if _is_terminal(e))
assert events[terminal_idx]["type"] == "run.completed"
# ── P0-4: Projection dedup ────────────────────────────────────────────────
@pytest.mark.asyncio
async def test_p0_4_dedup_same_source_event_id(svc, store):
"""Projecting the same source_event_id twice should not create a duplicate."""
conv = await svc.create_conversation(user_id="u1", title="Dedup")
result1 = await svc._publish_conversation_event(
conversation_id=conv["id"],
owner_user_id="u1",
event_type="tool.started",
event_data={"tool_name": "search"},
source_event_id="evt_src_001",
)
assert result1 is True
result2 = await svc._publish_conversation_event(
conversation_id=conv["id"],
owner_user_id="u1",
event_type="tool.started",
event_data={"tool_name": "search"},
source_event_id="evt_src_001",
)
assert result2 is False # Deduped
events = await store.conversation_events.list_events(conv["id"], after_seq=0)
tool_events = [e for e in events if e["type"] == "tool.started"]
assert len(tool_events) == 1
@pytest.mark.asyncio
async def test_p0_4_different_source_event_ids_both_written(svc, store):
conv = await svc.create_conversation(user_id="u1", title="MultiSrc")
await svc._publish_conversation_event(
conversation_id=conv["id"], owner_user_id="u1",
event_type="tool.started", event_data={"tool_name": "a"},
source_event_id="src_1",
)
await svc._publish_conversation_event(
conversation_id=conv["id"], owner_user_id="u1",
event_type="tool.started", event_data={"tool_name": "b"},
source_event_id="src_2",
)
events = await store.conversation_events.list_events(conv["id"], after_seq=0)
tool_events = [e for e in events if e["type"] == "tool.started"]
assert len(tool_events) == 2
@pytest.mark.asyncio
async def test_p0_4_null_source_event_id_not_deduped(svc, store):
"""Events with no source_event_id should never be deduped."""
conv = await svc.create_conversation(user_id="u1", title="NoSrc")
await svc._publish_conversation_event(
conversation_id=conv["id"], owner_user_id="u1",
event_type="manager.dispatch", event_data={"reason": "x"},
source_event_id=None,
)
await svc._publish_conversation_event(
conversation_id=conv["id"], owner_user_id="u1",
event_type="manager.dispatch", event_data={"reason": "y"},
source_event_id=None,
)
events = await store.conversation_events.list_events(conv["id"], after_seq=0)
assert len(events) == 2
# ── SSE replay + cursor + real-time integration ──────────────────────────
async def _reset_conv_to_idle(store: MafRoundtableStore, conv_id: str):
async with store.session_factory() as session:
row = await session.get(MafRoundtableConversationRow, conv_id)
if row:
row.safe_status = "idle"
row.active_run_id = None
await session.commit()
@pytest.mark.asyncio
async def test_sse_replay_delivers_past_events(svc, store):
conv = await svc.create_conversation(user_id="u1", title="Replay")
await svc.send_message(conversation_id=conv["id"], user_id="u1", content="msg1")
await _reset_conv_to_idle(store, conv["id"])
await svc.send_message(conversation_id=conv["id"], user_id="u1", content="msg2")
events = await store.conversation_events.list_events(conv["id"], after_seq=0)
assert len(events) >= 2
types = [e["type"] for e in events]
assert types.count("user.message.created") == 2
seqs = [e["seq"] for e in events]
assert seqs == sorted(seqs)
@pytest.mark.asyncio
async def test_sse_after_seq_prevents_duplicates(svc, store):
conv = await svc.create_conversation(user_id="u1", title="Cursor")
await svc.send_message(conversation_id=conv["id"], user_id="u1", content="first")
await _reset_conv_to_idle(store, conv["id"])
await svc.send_message(conversation_id=conv["id"], user_id="u1", content="second")
all_events = await store.conversation_events.list_events(conv["id"], after_seq=0)
last_seq = all_events[0]["seq"]
replay = await store.conversation_events.list_events(conv["id"], after_seq=last_seq)
assert all(e["seq"] > last_seq for e in replay)
assert len(replay) == len(all_events) - 1
@pytest.mark.asyncio
async def test_real_time_event_pushed_after_subscribe(svc, store, hub):
conv = await svc.create_conversation(user_id="u1", title="RT")
received_events: list[dict] = []
async def stream_consumer():
sub = hub.open_subscription(conv["id"])
last_seq = 0
# Stabilise (no events yet)
while sub.has_pending:
sub.mark_seen()
# Wait for change
changed = await sub.wait_for_change(timeout=5.0)
if changed:
new_evts = await store.conversation_events.list_events(conv["id"], after_seq=last_seq)
for evt in new_evts:
received_events.append(evt)
last_seq = max(last_seq, evt["seq"])
sub.close()
task = asyncio.create_task(stream_consumer())
await asyncio.sleep(0.1)
await svc.send_message(conversation_id=conv["id"], user_id="u1", content="live msg")
await asyncio.wait_for(task, timeout=5.0)
types = [e["type"] for e in received_events]
assert "user.message.created" in types
@pytest.mark.asyncio
async def test_concurrent_subscribers_both_receive(svc, store, hub):
conv = await svc.create_conversation(user_id="u1", title="Fanout")
buf_a: list[dict] = []
buf_b: list[dict] = []
async def consume(buf):
sub = hub.open_subscription(conv["id"])
last_seq = 0
changed = await sub.wait_for_change(timeout=5.0)
if changed:
new_evts = await store.conversation_events.list_events(conv["id"], after_seq=last_seq)
for evt in new_evts:
buf.append(evt)
last_seq = max(last_seq, evt["seq"])
sub.close()
ta = asyncio.create_task(consume(buf_a))
tb = asyncio.create_task(consume(buf_b))
await asyncio.sleep(0.15)
await svc.send_message(conversation_id=conv["id"], user_id="u1", content="broadcast")
await asyncio.wait_for(asyncio.gather(ta, tb), timeout=5.0)
assert len(buf_a) >= 1
assert len(buf_b) >= 1
assert buf_a[0]["seq"] == buf_b[0]["seq"]
@pytest.mark.asyncio
async def test_reconnect_after_seq_resume(svc, store):
conv = await svc.create_conversation(user_id="u1", title="Reconnect")
await svc.send_message(conversation_id=conv["id"], user_id="u1", content="batch1")
await _reset_conv_to_idle(store, conv["id"])
await svc.send_message(conversation_id=conv["id"], user_id="u1", content="batch2")
all_events = await store.conversation_events.list_events(conv["id"], after_seq=0)
midpoint = all_events[len(all_events) // 2]["seq"]
replay = await store.conversation_events.list_events(conv["id"], after_seq=midpoint)
assert all(e["seq"] > midpoint for e in replay)
# ── SSE frame format ──────────────────────────────────────────────────────
@pytest.mark.asyncio
async def test_sse_frame_format():
from app.gateway.routers.maf_conversations import _format_heartbeat, _format_sse_event
frame = _format_sse_event({
"seq": 42,
"event_id": "evt_abc",
"conversation_id": "conv_1",
"run_id": "run_1",
"type": "user.message.created",
"occurred_at": "2026-08-03T00:00:00Z",
"data": {"content": "hi"},
})
assert "event: user.message.created" in frame
assert "data: " in frame
assert "id: evt_abc" in frame
assert frame.endswith("\n\n")
parsed = None
for line in frame.splitlines():
if line.startswith("data: "):
parsed = json.loads(line[len("data: "):])
break
assert parsed is not None
assert parsed["seq"] == 42
assert parsed["type"] == "user.message.created"
hb = _format_heartbeat()
assert hb == ": heartbeat\n\n"
# ── Ownership ────────────────────────────────────────────────────────────
@pytest.mark.asyncio
async def test_ownership_check_before_stream(svc):
conv = await svc.create_conversation(user_id="u1", title="OwnerOnly")
fetched = await svc.get_conversation(conversation_id=conv["id"], user_id="u1")
assert fetched["id"] == conv["id"]
with pytest.raises(ConversationNotFoundError):
await svc.get_conversation(conversation_id=conv["id"], user_id="u2")