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:
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.",
|
||||
)
|
||||
|
||||
|
||||
|
||||
Reference in new issue
Block a user