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

@@ -50,6 +50,7 @@ from app.gateway.routers import (
knowledge_ingest,
light_apps,
llm_metrics,
maf_conversations,
maf_roundtable,
mcp,
memory,
@@ -1612,6 +1613,9 @@ This gateway provides custom endpoints for models, MCP configuration, skills, an
# roundtable; feature-flag-gated, six isolated tables) at /api/maf-roundtable
app.include_router(maf_roundtable.router)
# MAF roundtable V2 Conversation API (user-visible layer) at /api/maf-roundtable/conversations
app.include_router(maf_conversations.router)
# Temporary compatibility bridge for the TaskCOP situation-overview frontend.
app.include_router(taskcop_tasks.router)
@@ -319,8 +319,9 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
# abort Gateway startup (the feature is experimental / opt-in).
from deerflow.persistence.maf_roundtable import make_maf_roundtable_store
app.state.maf_roundtable_store = make_maf_roundtable_store(sf)
try:
app.state.maf_roundtable_store = make_maf_roundtable_store(sf)
maf_enabled = False
try:
from app.maf_roundtable import MafRoundtableService
maf_cfg = getattr(config, "maf_roundtable", None)
@@ -369,6 +370,32 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
logger.exception("[maf-roundtable] service initialization failed; feature stays off")
app.state.maf_roundtable_service = None
# ── MAF roundtable V2 Conversation service + SSE event hub ──
try:
from app.maf_roundtable.conversation_event_hub import ConversationEventHub
app.state.maf_conversation_event_hub = ConversationEventHub()
if app.state.maf_roundtable_store is not None:
from app.maf_roundtable.conversation_service import MafConversationService
from app.maf_roundtable.dispatcher import get_dispatcher
app.state.maf_conversation_service = MafConversationService(
app.state.maf_roundtable_store,
maf_config=getattr(config, "maf_roundtable", None),
event_hub=app.state.maf_conversation_event_hub,
agent_store=getattr(app.state, "agent_store", None),
app_config=config,
dispatcher=get_dispatcher(app),
enabled=maf_enabled,
)
else:
app.state.maf_conversation_service = None
except Exception: # noqa: BLE001
logger.exception("[maf-roundtable] conversation service init failed")
app.state.maf_conversation_service = None
app.state.maf_conversation_event_hub = None
from deerflow.persistence.roundtable_jobs import (
make_roundtable_job_store,
)
@@ -458,6 +485,15 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
try:
yield
finally:
# P1: shut down the SSE event hub before closing the DB engine
# so active SSE streams are released cleanly.
hub = getattr(app.state, "maf_conversation_event_hub", None)
if hub is not None:
try:
hub.shutdown()
except Exception: # noqa: BLE001
logger.warning("[maf-roundtable] hub shutdown failed", exc_info=True)
from deerflow.persistence.notifications import set_notification_store
set_notification_store(None)
@@ -0,0 +1,341 @@
"""HTTP router for MAF roundtable Conversation API at ``/api/maf-roundtable/conversations``.
Phase 1 (R1) scope:
- POST /conversations — create blank user conversation
- GET /conversations — list current user's history
- GET /conversations/{id} — public conversation DTO
- GET /conversations/{id}/messages — paginated message history
- POST /conversations/{id}/messages — atomic send + run start
Phase 2 (R2) adds:
- GET /conversations/{id}/stream — SSE real-time event stream
User isolation: owner-only reads/writes. Admin diagnostic access is read-only.
Internal fields (owner_user_id, internal_session_id, active_run_id, thread ids)
are never returned.
"""
from __future__ import annotations
import asyncio
import json
import logging
from datetime import UTC, datetime
from typing import Any
from fastapi import APIRouter, HTTPException, Query, Request, status
from fastapi.responses import StreamingResponse
from app.maf_roundtable.conversation_event_hub import ConversationEventHub
from app.maf_roundtable.conversation_schemas import (
ConversationListResponse,
ConversationResponse,
CreateConversationRequest,
MessageListResponse,
SendMessageRequest,
SendMessageResponse,
)
from app.maf_roundtable.conversation_service import (
ConversationConflictError,
ConversationDisabledError,
ConversationNoSessionConfigError,
ConversationNotFoundError,
ConversationServiceError,
MafConversationService,
)
logger = logging.getLogger(__name__)
router = APIRouter(prefix="/api/maf-roundtable", tags=["maf-roundtable-conversations"])
_SSE_HEADERS = {
"Cache-Control": "no-cache",
"Connection": "keep-alive",
"X-Accel-Buffering": "no",
}
def _get_conversation_service(request: Request) -> MafConversationService:
svc = getattr(request.app.state, "maf_conversation_service", None)
if svc is None:
raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="MAF conversation service not available")
return svc
def _get_event_hub(request: Request) -> ConversationEventHub | None:
return getattr(request.app.state, "maf_conversation_event_hub", None)
def _user_ctx(request: Request) -> tuple[str, bool]:
"""Match the main MAF router's authenticated-user convention.
``AuthMiddleware`` stamps the resolved account on ``request.state.user``;
it does not create ``user_id`` / ``is_admin`` attributes. Reading those
nonexistent attributes collapses every authenticated caller into the
fallback account and breaks owner isolation.
"""
user = getattr(request.state, "user", None)
if user is None:
return "default", False
return str(user.id), getattr(user, "system_role", None) == "admin"
# ── REST endpoints (Phase 1) ──────────────────────────────────────────────
@router.post("/conversations", response_model=ConversationResponse, status_code=status.HTTP_201_CREATED)
async def create_conversation(body: CreateConversationRequest, request: Request):
svc = _get_conversation_service(request)
user_id, _ = _user_ctx(request)
try:
return await svc.create_conversation(
user_id=user_id,
title=body.title.strip(),
task_context=body.task_context,
)
except ConversationDisabledError:
raise HTTPException(
status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
detail="MAF roundtable feature is disabled",
)
@router.get("/conversations", response_model=ConversationListResponse)
async def list_conversations(
request: Request,
limit: int = Query(default=50, ge=1, le=200),
offset: int = Query(default=0, ge=0),
):
svc = _get_conversation_service(request)
user_id, _ = _user_ctx(request)
conversations, total = await svc.list_conversations(user_id=user_id, limit=limit, offset=offset)
return {"conversations": conversations, "total": total}
@router.get("/conversations/{conversation_id}", response_model=ConversationResponse)
async def get_conversation(conversation_id: str, request: Request):
svc = _get_conversation_service(request)
user_id, is_admin = _user_ctx(request)
try:
return await svc.get_conversation(conversation_id=conversation_id, user_id=user_id, is_admin=is_admin)
except ConversationNotFoundError:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Conversation not found")
@router.get("/conversations/{conversation_id}/messages", response_model=MessageListResponse)
async def list_messages(
conversation_id: str,
request: Request,
before_seq: int | None = Query(default=None, ge=1),
limit: int = Query(default=50, ge=1, le=200),
):
svc = _get_conversation_service(request)
user_id, is_admin = _user_ctx(request)
try:
messages, last_stream_seq = await svc.list_messages(
conversation_id=conversation_id, user_id=user_id, is_admin=is_admin,
before_seq=before_seq, limit=limit,
)
return {"messages": messages, "last_stream_seq": last_stream_seq}
except ConversationNotFoundError:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Conversation not found")
@router.post("/conversations/{conversation_id}/messages", response_model=SendMessageResponse, status_code=status.HTTP_201_CREATED)
async def send_message(conversation_id: str, body: SendMessageRequest, request: Request):
svc = _get_conversation_service(request)
user_id, _ = _user_ctx(request)
try:
return await svc.send_message(conversation_id=conversation_id, user_id=user_id, content=body.content)
except ConversationNotFoundError:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Conversation not found")
except ConversationConflictError:
raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="A run is already active")
except ConversationNoSessionConfigError:
raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="No trusted session configuration")
except ConversationDisabledError:
raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="MAF roundtable feature is disabled")
except ConversationServiceError as exc:
raise HTTPException(status_code=exc.status_code, detail=exc.message)
# ── SSE endpoint (Phase 2 / R2) ───────────────────────────────────────────
# Event types that mark the end of a run's lifecycle. When the SSE stream
# encounters any of these in order, it sends the event and then closes the
# connection so the client doesn't sit idle receiving heartbeats.
_TERMINAL_EVENT_TYPES = frozenset({
"run.completed",
"run.error",
"run.cancelled",
})
def _format_sse_event(event: dict[str, Any]) -> str:
"""Format one conversation event as an SSE frame per §4.3 contract.
``event:`` field carries the event type; ``data:`` carries the full
envelope; ``id:`` carries the event_id for Last-Event-ID reconnection.
"""
event_type = event.get("type", "message")
event_id = event.get("event_id")
payload = json.dumps(event, default=str, ensure_ascii=False)
parts = [f"event: {event_type}", f"data: {payload}"]
if event_id:
parts.append(f"id: {event_id}")
parts.append("")
parts.append("")
return "\n".join(parts)
def _format_heartbeat() -> str:
"""SSE comment frame — keeps the connection alive without producing a
client-visible event."""
return ": heartbeat\n\n"
def _is_terminal(event: dict[str, Any]) -> bool:
return event.get("type") in _TERMINAL_EVENT_TYPES
@router.get("/conversations/{conversation_id}/stream")
async def stream_conversation(
conversation_id: str,
request: Request,
after_seq: int = Query(default=0, ge=0),
):
"""SSE stream for one conversation (§4.2).
Single fetch-reader connection per conversation. The ordering is:
1. **Open subscription** (register before any DB query — P0-1 fix).
2. **Replay** from DB: ``list_events(after_seq)``.
3. **Stabilise**: re-query while the hub generation advanced during replay.
4. **Snapshot** marker.
5. **Real-time**: ``wait_for_change`` → query DB → yield events.
On terminal events (``run.completed`` / ``run.error`` / ``run.cancelled``)
the stream sends the event and closes (P0-2 fix).
Heartbeat every 15 s. Disconnect detection via ``request.is_disconnected()``.
"""
svc = _get_conversation_service(request)
hub = _get_event_hub(request)
user_id, is_admin = _user_ctx(request)
if hub is None:
raise HTTPException(
status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
detail="SSE event hub not configured",
)
# Ownership check before opening the stream.
try:
await svc.get_conversation(
conversation_id=conversation_id, user_id=user_id, is_admin=is_admin,
)
except ConversationNotFoundError:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Conversation not found")
store = svc._store # noqa: SLF001 — router needs raw event queries for streaming
async def event_generator():
# ── P0-1: Open subscription BEFORE replay ──
sub = hub.open_subscription(conversation_id)
last_seq = after_seq
try:
# ── Phase 1: Replay from DB ──
try:
replay_events = await store.conversation_events.list_events(
conversation_id, after_seq=last_seq,
)
for evt in replay_events:
if await request.is_disconnected():
return
yield _format_sse_event(evt)
last_seq = max(last_seq, int(evt.get("seq", last_seq)))
# P0-2: stop if replay already hit a terminal event.
if _is_terminal(evt):
return
except Exception:
logger.exception("SSE replay error conv=%s", conversation_id)
yield _format_sse_event({
"seq": last_seq,
"event_id": f"replay_error_{last_seq}",
"conversation_id": conversation_id,
"type": "run.error",
"occurred_at": datetime.now(UTC).isoformat(),
"data": {"error": "replay_failed"},
})
return
# ── P0-1: Stabilise — catch events published during replay ──
while sub.has_pending:
sub.mark_seen()
late_events = await store.conversation_events.list_events(
conversation_id, after_seq=last_seq,
)
if not late_events:
break
for evt in late_events:
if await request.is_disconnected():
return
yield _format_sse_event(evt)
last_seq = max(last_seq, int(evt.get("seq", last_seq)))
if _is_terminal(evt):
return
# ── Send snapshot marker ──
snapshot = {
"seq": last_seq,
"event_id": f"snapshot_{conversation_id}_{last_seq}",
"conversation_id": conversation_id,
"type": "conversation.snapshot",
"occurred_at": datetime.now(UTC).isoformat(),
"data": {"last_stream_seq": last_seq},
}
if not await request.is_disconnected():
yield _format_sse_event(snapshot)
# ── Phase 2: Real-time subscription ──
heartbeat_interval = hub.heartbeat_interval
while True:
if hub.is_closed:
return
if await request.is_disconnected():
return
changed = await sub.wait_for_change(timeout=heartbeat_interval)
if not changed:
# Timeout → heartbeat (or hub closed).
if hub.is_closed:
return
yield _format_heartbeat()
continue
# Generation advanced — fetch new events from DB.
new_events = await store.conversation_events.list_events(
conversation_id, after_seq=last_seq,
)
for evt in new_events:
if await request.is_disconnected():
return
yield _format_sse_event(evt)
last_seq = max(last_seq, int(evt.get("seq", last_seq)))
# P0-2: terminal event → close stream after sending it.
if _is_terminal(evt):
return
except asyncio.CancelledError:
logger.debug("SSE stream cancelled conv=%s", conversation_id)
raise
except Exception:
logger.exception("SSE stream error conv=%s", conversation_id)
return
finally:
sub.close()
return StreamingResponse(
event_generator(),
media_type="text/event-stream",
headers=_SSE_HEADERS,
)
@@ -131,6 +131,9 @@ async def get_health(request: Request) -> HealthResponse:
write_guard_ready=readiness["ready"],
action_secret_configured=readiness["secret_configured"],
write_guard_status=readiness["status"],
sse_hub_type="in_memory",
sse_multi_worker=False,
sse_warning="Single-worker only. Multi-worker requires Redis Pub/Sub.",
)