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,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.",
)