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

@@ -87,6 +87,32 @@ class MafToolMetadata(BaseModel):
return namespace
class MafBusinessRoute(BaseModel):
"""Server-owned route for one MAF business chain.
The browser and the model never submit these agent ids. Operators must
configure the exact ids discovered in the deployment's agent catalog.
Keeping the route in the MAF config also makes a session reproducible: the
selected route is frozen into its trusted capability snapshot at launch.
"""
manager_agent_id: str = Field(min_length=1, max_length=64)
seat_agent_ids: list[str] = Field(default_factory=list, max_length=64)
mode: MafMode | None = None
@field_validator("seat_agent_ids")
@classmethod
def _validate_seat_agent_ids(cls, ids: list[str]) -> list[str]:
normalized: list[str] = []
for agent_id in ids:
value = str(agent_id).strip()
if not value or len(value) > 64:
raise ValueError("seat_agent_ids must contain non-empty agent ids")
if value not in normalized:
normalized.append(value)
return normalized
class MafRoundtableConfig(BaseModel):
"""Microsoft Agent Framework 多智能体会商实验功能开关。
@@ -116,6 +142,13 @@ class MafRoundtableConfig(BaseModel):
le=64,
description="默认最大轮次上限(群聊模式硬上限,避免弱模型无限讨论)",
)
# Stage 3: server-owned routing. These remain empty in the repository;
# production deployments must inject exact agent ids in their deployment
# configuration instead of guessing from names or client input.
default_manager_agent_id: str | None = Field(default=None, max_length=64)
default_seat_agent_ids: list[str] = Field(default_factory=list, max_length=64)
business_routes: dict[str, MafBusinessRoute] = Field(default_factory=dict)
max_seats_per_run: int = Field(default=16, ge=1, le=64)
# 管理员诊断是否可见所有用户的会商(true=管理员跨用户读,false=管理员也只能看自己的)。
admin_diagnostic_access: bool = Field(
default=True,
@@ -162,6 +195,7 @@ class MafRoundtableConfig(BaseModel):
__all__ = [
"MafMode",
"MafBusinessRoute",
"MafParticipantRole",
"MafRiskLevel",
"MafRoundtableConfig",
@@ -31,13 +31,19 @@ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from deerflow.persistence.maf_roundtable.action_secrets import MafActionSecretRepository
from deerflow.persistence.maf_roundtable.actions import MafActionRepository
from deerflow.persistence.maf_roundtable.approvals import MafApprovalRepository
from deerflow.persistence.maf_roundtable.conversation_events import MafConversationEventRepository
from deerflow.persistence.maf_roundtable.conversations import MafConversationRepository
from deerflow.persistence.maf_roundtable.events import MafEventRepository
from deerflow.persistence.maf_roundtable.messages import MafMessageRepository
from deerflow.persistence.maf_roundtable.model import (
MafRoundtableActionLeaseRow,
MafRoundtableActionRow,
MafRoundtableActionSecretRow,
MafRoundtableApprovalRow,
MafRoundtableConversationEventRow,
MafRoundtableConversationRow,
MafRoundtableEventRow,
MafRoundtableMessageRow,
MafRoundtableParticipantRow,
MafRoundtableRunRow,
MafRoundtableSeatRunRow,
@@ -53,13 +59,19 @@ __all__ = [
"MafActionRepository",
"MafActionSecretRepository",
"MafApprovalRepository",
"MafConversationEventRepository",
"MafConversationRepository",
"MafEventRepository",
"MafMessageRepository",
"MafParticipantRepository",
"MafRoundtableActionRow",
"MafRoundtableActionLeaseRow",
"MafRoundtableActionSecretRow",
"MafRoundtableApprovalRow",
"MafRoundtableConversationEventRow",
"MafRoundtableConversationRow",
"MafRoundtableEventRow",
"MafRoundtableMessageRow",
"MafRoundtableParticipantRow",
"MafRoundtableRunRow",
"MafRoundtableSeatRunRow",
@@ -0,0 +1,102 @@
"""Conversation-event repository for the MAF roundtable V2 (SSE stream).
Unlike ``maf_roundtable_events`` (per-run seq), this table uses a
**conversation-global** monotonic ``seq`` so the frontend needs only one cursor
(``after_seq``) regardless of how many internal runs a conversation spawns.
The SSE hub (§4.2) replays from this table on connect/reconnect, then
subscribes to real-time notifications.
Seq allocation mirrors ``maf_roundtable_events``: ``SELECT MAX(seq) + 1`` with
``IntegrityError`` retry, portable across sqlite / postgres / mysql.
The writer order is "persist first, then notify" — the hub never broadcasts an
event that is not already durable here, so a reconnecting client can always
replay anything it missed.
"""
from __future__ import annotations
from datetime import UTC, datetime
from typing import Any
from sqlalchemy import func, select
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from deerflow.persistence.maf_roundtable.model import MafRoundtableConversationEventRow
def _now() -> datetime:
return datetime.now(UTC)
def conversation_event_to_dict(row: MafRoundtableConversationEventRow) -> dict[str, Any]:
"""Serialise a conversation-event ORM row to the §4.3 SSE envelope dict."""
return {
"seq": row.seq,
"event_id": row.id,
"conversation_id": row.conversation_id,
"run_id": row.run_id,
"source_event_id": getattr(row, "source_event_id", None),
"type": row.event_type,
"occurred_at": row.created_at.isoformat() if isinstance(row.created_at, datetime) else row.created_at,
"data": row.data_json or {},
}
class MafConversationEventRepository:
"""Conversation-global monotonic event stream backing the SSE channel."""
def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
self._sf = session_factory
async def append_event(
self,
*,
conversation_id: str,
event_type: str,
run_id: str | None = None,
data: dict[str, Any] | None = None,
) -> dict[str, Any]:
"""Persist one event with a monotonic conversation-global seq.
Concurrent appends are safe: each attempts ``MAX(seq)+1`` and retries
on the ``(conversation_id, seq)`` unique violation. Returns the §4.3
envelope dict.
"""
del conversation_id, event_type, run_id, data
raise RuntimeError(
"Conversation event writes must use "
"MafRoundtableStore.append_conversation_item"
)
async def list_events(
self, conversation_id: str, *, after_seq: int = 0, limit: int = 1000
) -> list[dict[str, Any]]:
"""Replay: events with ``seq > after_seq`` in ascending order.
Used by the SSE hub on connect/reconnect to catch the client up before
switching to the real-time subscription.
"""
stmt = (
select(MafRoundtableConversationEventRow)
.where(
MafRoundtableConversationEventRow.conversation_id == conversation_id,
MafRoundtableConversationEventRow.seq > after_seq,
)
.order_by(MafRoundtableConversationEventRow.seq.asc())
.limit(limit)
)
async with self._sf() as session:
rows = (await session.execute(stmt)).scalars().all()
return [conversation_event_to_dict(r) for r in rows]
async def latest_seq(self, conversation_id: str) -> int:
async with self._sf() as session:
max_seq = (
await session.execute(
select(func.max(MafRoundtableConversationEventRow.seq)).where(
MafRoundtableConversationEventRow.conversation_id == conversation_id
)
)
).scalar_one()
return int(max_seq or 0)
@@ -0,0 +1,200 @@
"""Conversation repository for the MAF roundtable V2 (user-visible aggregation).
A conversation is the **only** entity the frontend knows about. Owner-scoped
by ``owner_user_id``: every read / update / delete checks ownership. Admins
bypass the owner filter when ``admin_diagnostic_access`` is true (handled in
the service / router layer, not here).
"""
from __future__ import annotations
from datetime import UTC, datetime
from typing import Any
from uuid import uuid4
from sqlalchemy import delete, func, select, update
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from deerflow.persistence.maf_roundtable.model import MafRoundtableConversationRow
def _now() -> datetime:
return datetime.now(UTC)
def conversation_internal_to_dict(row: MafRoundtableConversationRow) -> dict[str, Any]:
"""Internal serialisation — includes all columns. Never expose to the browser."""
return {
"id": row.id,
"owner_user_id": row.owner_user_id,
"title": row.title,
"task_context": row.task_context_json,
"safe_status": row.safe_status,
"active_run_id": row.active_run_id,
"internal_session_id": row.internal_session_id,
"last_stream_seq": row.last_stream_seq,
"created_at": row.created_at.isoformat() if isinstance(row.created_at, datetime) else row.created_at,
"updated_at": row.updated_at.isoformat() if isinstance(row.updated_at, datetime) else row.updated_at,
}
_TASK_CONTEXT_SAFE_KEYS = frozenset({"business_code", "task_id", "task_name", "chain_id", "chain_name"})
def conversation_public_to_dict(row: MafRoundtableConversationRow) -> dict[str, Any]:
"""Public DTO — only fields safe for the browser. No owner, session, run, or thread ids."""
raw_ctx = row.task_context_json
safe_ctx: dict[str, Any] | None = None
if isinstance(raw_ctx, dict):
safe_ctx = {k: v for k, v in raw_ctx.items() if k in _TASK_CONTEXT_SAFE_KEYS}
return {
"id": row.id,
"title": row.title,
"task_context": safe_ctx,
"safe_status": row.safe_status,
"created_at": row.created_at.isoformat() if isinstance(row.created_at, datetime) else row.created_at,
"updated_at": row.updated_at.isoformat() if isinstance(row.updated_at, datetime) else row.updated_at,
"last_stream_seq": row.last_stream_seq,
}
class MafConversationRepository:
"""Owner-scoped CRUD for MAF roundtable conversations."""
def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
self._sf = session_factory
async def create_conversation(self, data: dict[str, Any]) -> dict[str, Any]:
"""Create a new conversation. ``data`` must include ``owner_user_id``."""
now = _now()
row = MafRoundtableConversationRow(
id=data.get("id") or uuid4().hex,
owner_user_id=str(data["owner_user_id"]),
title=str(data.get("title") or ""),
task_context_json=data.get("task_context"),
safe_status="idle",
active_run_id=None,
internal_session_id=None,
last_stream_seq=0,
created_at=now,
updated_at=now,
)
async with self._sf() as session:
session.add(row)
await session.commit()
return conversation_internal_to_dict(row)
async def get_conversation(
self, conversation_id: str, *, user_id: str | None = "REQUIRED"
) -> dict[str, Any] | None:
"""Read one conversation.
``user_id`` scoping:
- ``"REQUIRED"`` (default): enforce owner scope.
- ``None``: bypass owner scope (admin / internal path).
"""
async with self._sf() as session:
stmt = select(MafRoundtableConversationRow).where(
MafRoundtableConversationRow.id == conversation_id
).limit(1)
row = (await session.execute(stmt)).scalars().first()
if row is None:
return None
if user_id is not None and row.owner_user_id != user_id:
return None
return conversation_internal_to_dict(row)
async def list_conversations(
self,
*,
user_id: str | None = None,
safe_status: str | None = None,
limit: int = 50,
offset: int = 0,
) -> list[dict[str, Any]]:
"""List conversations, newest-first.
``user_id=None`` lists across all users (admin / diagnostic).
"""
stmt = select(MafRoundtableConversationRow)
if user_id is not None:
stmt = stmt.where(MafRoundtableConversationRow.owner_user_id == user_id)
if safe_status is not None:
stmt = stmt.where(MafRoundtableConversationRow.safe_status == safe_status)
stmt = stmt.order_by(MafRoundtableConversationRow.updated_at.desc()).limit(limit).offset(offset)
async with self._sf() as session:
rows = (await session.execute(stmt)).scalars().all()
return [conversation_internal_to_dict(r) for r in rows]
async def count_conversations(
self, *, user_id: str | None = None, safe_status: str | None = None
) -> int:
stmt = select(func.count()).select_from(MafRoundtableConversationRow)
if user_id is not None:
stmt = stmt.where(MafRoundtableConversationRow.owner_user_id == user_id)
if safe_status is not None:
stmt = stmt.where(MafRoundtableConversationRow.safe_status == safe_status)
async with self._sf() as session:
return int((await session.execute(stmt)).scalar_one())
async def update_conversation(
self, conversation_id: str, *, user_id: str | None, fields: dict[str, Any]
) -> dict[str, Any] | None:
"""Partial update. Returns ``None`` if missing or wrong owner."""
async with self._sf() as session:
stmt = select(MafRoundtableConversationRow).where(
MafRoundtableConversationRow.id == conversation_id
).limit(1)
row = (await session.execute(stmt)).scalars().first()
if row is None:
return None
if user_id is not None and row.owner_user_id != user_id:
return None
col_map = {"task_context": "task_context_json"}
for key in ("title", "task_context", "safe_status", "active_run_id",
"internal_session_id", "last_stream_seq"):
if key in fields:
col = col_map.get(key, key)
setattr(row, col, fields[key])
row.updated_at = _now()
await session.commit()
return conversation_internal_to_dict(row)
async def delete_conversation(self, conversation_id: str, *, user_id: str | None) -> bool:
"""Delete a conversation (children via FK CASCADE)."""
async with self._sf() as session:
stmt = select(MafRoundtableConversationRow).where(
MafRoundtableConversationRow.id == conversation_id
).limit(1)
row = (await session.execute(stmt)).scalars().first()
if row is None:
return False
if user_id is not None and row.owner_user_id != user_id:
return False
await session.execute(
delete(MafRoundtableConversationRow).where(
MafRoundtableConversationRow.id == conversation_id
)
)
await session.commit()
return True
async def set_status(self, conversation_id: str, safe_status: str) -> None:
"""Internal: update only the safe_status column."""
async with self._sf() as session:
await session.execute(
update(MafRoundtableConversationRow)
.where(MafRoundtableConversationRow.id == conversation_id)
.values(safe_status=safe_status, updated_at=_now())
)
await session.commit()
async def set_active_run(self, conversation_id: str, run_id: str | None, safe_status: str) -> None:
"""Internal: update active_run_id + safe_status together."""
async with self._sf() as session:
await session.execute(
update(MafRoundtableConversationRow)
.where(MafRoundtableConversationRow.id == conversation_id)
.values(active_run_id=run_id, safe_status=safe_status, updated_at=_now())
)
await session.commit()
@@ -0,0 +1,176 @@
"""Message repository for the MAF roundtable V2 (stable conversation history).
Every user-visible bubble (user / manager / seat / system / clarification /
approval / result / tool_progress) has exactly one row here. ``seq`` is a
conversation-global monotonic counter (unique per conversation) allocated via
``SELECT MAX(seq) + 1`` with ``IntegrityError`` retry — the same portable
approach as ``maf_roundtable_events`` (works on sqlite / postgres / mysql).
The message history is the durable record the frontend rebuilds the timeline
from on refresh; the SSE conversation-event stream (§4.3) is the real-time
channel. Both share the conversation-global seq space so a refresh can resume
the SSE cursor from the last persisted message/event seq.
"""
from __future__ import annotations
from datetime import UTC, datetime
from typing import Any
from sqlalchemy import func, select
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from deerflow.persistence.maf_roundtable.model import MafRoundtableMessageRow
def _now() -> datetime:
return datetime.now(UTC)
def message_to_dict(row: MafRoundtableMessageRow) -> dict[str, Any]:
"""Internal serialisation — includes all columns. Never expose to the browser."""
return {
"id": row.id,
"conversation_id": row.conversation_id,
"seq": row.seq,
"message_kind": row.message_kind,
"role": row.role,
"agent_id": row.agent_id,
"run_id": row.run_id,
"message_ref": row.message_ref,
"content": row.content,
"metadata": row.metadata_json,
"created_at": row.created_at.isoformat() if isinstance(row.created_at, datetime) else row.created_at,
}
_METADATA_WHITELIST_BY_KIND: dict[str, frozenset[str]] = {
"user": frozenset(),
"manager": frozenset({"intent_type", "dispatch_plan_summary"}),
"seat": frozenset({"seat_name", "delivery_status", "attempt_number"}),
"system": frozenset({"reason"}),
"clarification": frozenset({"clarification_id", "options", "allow_multiple", "status"}),
"approval": frozenset({"approval_id", "tool_name", "risk_level", "summary", "status"}),
"result": frozenset({"result_type", "has_controlled_gap", "gap_summary"}),
"tool_progress": frozenset({"tool_name", "progress_pct", "status"}),
}
def message_public_to_dict(row: MafRoundtableMessageRow) -> dict[str, Any]:
"""Public DTO — only display-safe fields. No run_id, no unfiltered metadata."""
raw_meta = row.metadata_json
safe_meta: dict[str, Any] | None = None
if isinstance(raw_meta, dict):
allowed = _METADATA_WHITELIST_BY_KIND.get(row.message_kind, frozenset())
safe_meta = {k: v for k, v in raw_meta.items() if k in allowed} or None
return {
"id": row.id,
"conversation_id": row.conversation_id,
"seq": row.seq,
"message_kind": row.message_kind,
"role": row.role,
"agent_id": row.agent_id,
"message_ref": row.message_ref,
"content": row.content,
"metadata": safe_meta,
"created_at": row.created_at.isoformat() if isinstance(row.created_at, datetime) else row.created_at,
}
class MafMessageRepository:
"""Conversation-scoped message history with a monotonic per-conversation seq."""
def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
self._sf = session_factory
async def append_message(
self,
*,
conversation_id: str,
message_kind: str,
role: str,
content: str = "",
agent_id: str | None = None,
run_id: str | None = None,
message_ref: str | None = None,
metadata: dict[str, Any] | None = None,
) -> dict[str, Any]:
"""Reject an unsafe standalone write.
Message and event writes must use
:meth:`MafRoundtableStore.append_conversation_item` inside one
transaction. Separate ``MAX(seq) + 1`` allocators would violate the
conversation's single SSE cursor.
"""
del conversation_id, message_kind, role, content, agent_id, run_id, message_ref, metadata
raise RuntimeError(
"Conversation message writes must use "
"MafRoundtableStore.append_conversation_item"
)
async def list_messages(
self,
conversation_id: str,
*,
after_seq: int = 0,
before_seq: int | None = None,
limit: int = 50,
) -> list[dict[str, Any]]:
"""Paginated message history in ascending seq order.
``after_seq`` / ``before_seq`` implement cursor paging: the frontend
loads the latest page on entry (``after_seq=0`` + reverse via
:meth:`list_messages_desc`) and older pages on scroll-up.
"""
stmt = (
select(MafRoundtableMessageRow)
.where(
MafRoundtableMessageRow.conversation_id == conversation_id,
MafRoundtableMessageRow.seq > after_seq,
)
)
if before_seq is not None:
stmt = stmt.where(MafRoundtableMessageRow.seq < before_seq)
stmt = stmt.order_by(MafRoundtableMessageRow.seq.asc()).limit(limit)
async with self._sf() as session:
rows = (await session.execute(stmt)).scalars().all()
return [message_to_dict(r) for r in rows]
async def list_messages_desc(
self, conversation_id: str, *, limit: int = 50, before_seq: int | None = None
) -> list[dict[str, Any]]:
"""Latest ``limit`` messages, newest-first (for initial page load).
Returned newest-first; callers that want chronological order reverse
the list. ``before_seq`` loads the next older page.
"""
stmt = select(MafRoundtableMessageRow).where(
MafRoundtableMessageRow.conversation_id == conversation_id
)
if before_seq is not None:
stmt = stmt.where(MafRoundtableMessageRow.seq < before_seq)
stmt = stmt.order_by(MafRoundtableMessageRow.seq.desc()).limit(limit)
async with self._sf() as session:
rows = (await session.execute(stmt)).scalars().all()
return [message_to_dict(r) for r in rows]
async def latest_seq(self, conversation_id: str) -> int:
async with self._sf() as session:
max_seq = (
await session.execute(
select(func.max(MafRoundtableMessageRow.seq)).where(
MafRoundtableMessageRow.conversation_id == conversation_id
)
)
).scalar_one()
return int(max_seq or 0)
async def count_messages(self, conversation_id: str) -> int:
async with self._sf() as session:
return int((
await session.execute(
select(func.count()).select_from(MafRoundtableMessageRow).where(
MafRoundtableMessageRow.conversation_id == conversation_id
)
)
).scalar_one())
@@ -437,12 +437,142 @@ class MafRoundtableActionSecretRow(Base):
created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=_now)
# ── 10. conversations (V2: user-visible conversation aggregation) ─────────
class MafRoundtableConversationRow(Base):
"""One user-visible MAF roundtable conversation.
This is the **only** entity the frontend knows about. A conversation can
span multiple user messages, each of which may trigger an internal
``maf_roundtable_runs`` execution. The user never sees session/run/thread
ids — only ``conversation_id``.
``active_run_id`` points to the currently executing internal run (nullable
when idle). ``safe_status`` is a coarse user-facing status derived from
the active run's state (idle / running / waiting_input / waiting_approval
/ completed / failed / cancelled).
"""
__tablename__ = "maf_roundtable_conversations"
id: Mapped[str] = mapped_column(String(64), primary_key=True)
owner_user_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
title: Mapped[str] = mapped_column(String(255), default="")
task_context_json: Mapped[dict | None] = mapped_column(PortableJSON(), nullable=True)
# idle | running | waiting_input | waiting_approval | completed | failed | cancelled
safe_status: Mapped[str] = mapped_column(String(32), default="idle", index=True)
active_run_id: Mapped[str | None] = mapped_column(
String(64),
ForeignKey("maf_roundtable_runs.id", ondelete="SET NULL"),
nullable=True,
)
# Internal session this conversation is linked to (lazy-created on first message).
internal_session_id: Mapped[str | None] = mapped_column(
String(64),
ForeignKey("maf_roundtable_sessions.id", ondelete="SET NULL"),
nullable=True,
)
last_stream_seq: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=_now)
updated_at: Mapped[datetime] = mapped_column(
BeijingDateTime(), nullable=False, default=_now, onupdate=_now
)
# ── 11. conversation messages ─────────────────────────────────────────────
class MafRoundtableMessageRow(Base):
"""Stable message history for a conversation.
Every user-visible bubble (user message, manager message, seat message,
clarification card, approval card, result card) has exactly one row here.
``seq`` is a conversation-global monotonic counter (unique per conversation)
used for SSE cursor and ordering. ``message_kind`` classifies the bubble
type for the frontend reducer.
``run_id`` links the message to the internal run that produced it (nullable
for user messages that haven't started a run yet). ``agent_id`` identifies
the speaking agent (null for user messages).
"""
__tablename__ = "maf_roundtable_messages"
__table_args__ = (
UniqueConstraint("conversation_id", "seq", name="uq_maf_messages_conv_seq"),
)
id: Mapped[str] = mapped_column(String(64), primary_key=True)
conversation_id: Mapped[str] = mapped_column(
String(64), ForeignKey("maf_roundtable_conversations.id", ondelete="CASCADE"),
nullable=False, index=True,
)
seq: Mapped[int] = mapped_column(Integer, nullable=False)
# user | manager | seat | system | clarification | approval | result | tool_progress
message_kind: Mapped[str] = mapped_column(String(32), nullable=False, default="user")
role: Mapped[str] = mapped_column(String(16), nullable=False, default="user")
agent_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
run_id: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
# Stable message identity for SSE delta merging (e.g. LangGraph message id).
message_ref: Mapped[str | None] = mapped_column(String(191), nullable=True, index=True)
content: Mapped[str] = mapped_column(PortableLongText, default="")
metadata_json: Mapped[dict | None] = mapped_column(PortableJSON(), nullable=True)
created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=_now, index=True)
# ── 12. conversation events (SSE stream, conversation-global seq) ─────────
class MafRoundtableConversationEventRow(Base):
"""Conversation-dimension event stream for SSE.
Unlike ``maf_roundtable_events`` (per-run seq), this table uses a
**conversation-global** monotonic ``seq`` so the frontend only needs one
cursor (``after_seq``) regardless of how many internal runs happen.
The SSE hub replays from this table on connect/reconnect, then subscribes
to real-time notifications.
``event_type`` follows the §4.3 contract (conversation.snapshot,
user.message.created, manager.intent, clarification.required, etc.).
``data_json`` is the already-sanitized event payload safe for the browser.
"""
__tablename__ = "maf_roundtable_conversation_events"
__table_args__ = (
UniqueConstraint("conversation_id", "seq", name="uq_maf_conv_events_conv_seq"),
# P0-4: dedup key for projection idempotency. The source audit event's
# stable id (e.g. LangGraph event id / tool_call id) prevents duplicate
# conversation events when the bridge retries or the adapter re-projects
# after a restart. NULL source_event_ids are not deduped (SQL treats
# NULLs as distinct in UNIQUE constraints).
UniqueConstraint("conversation_id", "source_event_id", name="uq_maf_conv_events_conv_source"),
)
id: Mapped[str] = mapped_column(String(64), primary_key=True)
conversation_id: Mapped[str] = mapped_column(
String(64), ForeignKey("maf_roundtable_conversations.id", ondelete="CASCADE"),
nullable=False, index=True,
)
seq: Mapped[int] = mapped_column(Integer, nullable=False)
run_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
# Stable upstream id from the source audit event (maf_roundtable_events.id
# or the LangGraph source_event_id). Used for projection dedup via the
# (conversation_id, source_event_id) unique constraint.
source_event_id: Mapped[str | None] = mapped_column(String(191), nullable=True, index=True)
event_type: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
data_json: Mapped[dict | None] = mapped_column(PortableJSON(), nullable=True)
created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=_now, index=True)
__all__ = [
"MafRoundtableActionRow",
"MafRoundtableActionLeaseRow",
"MafRoundtableActionSecretRow",
"MafRoundtableApprovalRow",
"MafRoundtableConversationEventRow",
"MafRoundtableConversationRow",
"MafRoundtableEventRow",
"MafRoundtableMessageRow",
"MafRoundtableParticipantRow",
"MafRoundtableRunRow",
"MafRoundtableSeatRunRow",
@@ -29,13 +29,20 @@ from deerflow.persistence.maf_roundtable.actions import (
action_to_dict,
)
from deerflow.persistence.maf_roundtable.approvals import MafApprovalRepository
from deerflow.persistence.maf_roundtable.conversation_events import MafConversationEventRepository
from deerflow.persistence.maf_roundtable.conversations import MafConversationRepository
from deerflow.persistence.maf_roundtable.events import MafEventRepository
from deerflow.persistence.maf_roundtable.messages import MafMessageRepository
from deerflow.persistence.maf_roundtable.model import (
MafRoundtableActionLeaseRow,
MafRoundtableActionRow,
MafRoundtableActionSecretRow,
MafRoundtableApprovalRow,
MafRoundtableConversationEventRow,
MafRoundtableConversationRow,
MafRoundtableEventRow,
MafRoundtableMessageRow,
MafRoundtableParticipantRow,
MafRoundtableRunRow,
MafRoundtableSessionRow,
)
@@ -74,6 +81,10 @@ class MafRoundtableStore:
self.approvals = MafApprovalRepository(session_factory)
self.seat_runs = MafSeatRunRepository(session_factory)
self.action_secrets = MafActionSecretRepository(session_factory)
# V2 conversation aggregation (user-visible layer).
self.conversations = MafConversationRepository(session_factory)
self.messages = MafMessageRepository(session_factory)
self.conversation_events = MafConversationEventRepository(session_factory)
@property
def session_factory(self) -> async_sessionmaker[AsyncSession]:
@@ -791,12 +802,277 @@ class MafRoundtableStore:
await db.flush()
return recovered
# ── V2 conversation aggregation: unified seq allocation ─────────────────
async def append_conversation_item(
self,
db: AsyncSession,
*,
conversation: MafRoundtableConversationRow,
event_type: str,
event_data: dict[str, Any],
message: dict[str, Any] | None = None,
run_id: str | None = None,
source_event_id: str | None = None,
) -> dict[str, Any]:
"""Allocate the next conversation-global seq and persist message + event atomically.
MUST be called inside an existing transaction (``db.begin()``). The caller
is responsible for locking the conversation row (``with_for_update``).
1. ``conversation.last_stream_seq += 1`` (CAS via the row lock).
2. If ``message`` is provided, write it at the same seq.
3. Write the conversation event at the same seq.
4. Flush (no commit — caller controls the transaction boundary).
``source_event_id`` (P0-4): stable upstream id for projection dedup.
If the same source_event_id was already projected for this conversation,
the caller should check and skip before calling this method.
Returns ``{"seq": int, "message_id": str | None, "event_id": str}``.
"""
now = _now()
next_seq = int(conversation.last_stream_seq or 0) + 1
conversation.last_stream_seq = next_seq
message_id: str | None = None
if message is not None:
message_id = message.get("id") or uuid4().hex
db.add(MafRoundtableMessageRow(
id=message_id,
conversation_id=conversation.id,
seq=next_seq,
message_kind=message.get("message_kind", "user"),
role=message.get("role", "user"),
agent_id=message.get("agent_id"),
run_id=message.get("run_id") or run_id,
message_ref=message.get("message_ref"),
content=message.get("content", ""),
metadata_json=message.get("metadata"),
created_at=now,
))
event_id = uuid4().hex
db.add(MafRoundtableConversationEventRow(
id=event_id,
conversation_id=conversation.id,
seq=next_seq,
run_id=run_id,
source_event_id=source_event_id,
event_type=event_type,
data_json=event_data,
created_at=now,
))
await db.flush()
return {"seq": next_seq, "message_id": message_id, "event_id": event_id}
# ── V2 conversation aggregation: atomic send-message + run launch ───────
async def send_message_and_start_run(
self,
*,
conversation_id: str,
owner_user_id: str,
content: str,
message_metadata: dict[str, Any] | None = None,
workflow_version: str | None = None,
session_blueprint: dict[str, Any] | None = None,
) -> dict[str, Any] | None:
"""Atomically persist a user message, ensure internal session, and start a run.
Single ``AsyncSession`` + ``begin()`` so all writes share one transaction
— a mid-way failure rolls everything back (MAF-R1 requirement 1):
1. Load the conversation with ``FOR UPDATE``; verify ownership.
2. Reject when an active run is already in flight → ``{"conflict": True}``.
3. If no internal session exists, create one from ``session_blueprint``.
4. Create a ``pending`` run linked to the real internal session.
5. Allocate the next conversation-global seq via ``append_conversation_item``
(message + event share the same seq).
6. Flip conversation to ``safe_status='running'`` + ``active_run_id``.
``session_blueprint`` is provided by the App layer (ConversationService).
If the conversation has no internal session and no blueprint is given,
the method fails closed with ``{"no_session_config": True}``.
Returns ``{"message": {...}, "run": {...}, "conversation_id": ...}`` on
success, ``{"conflict": True}`` when a run is already active,
``{"no_session_config": True}`` when session cannot be created, or
``None`` when the conversation is missing / not owned.
"""
now = _now()
try:
async with self._sf() as db:
async with db.begin():
conv = (
await db.execute(
select(MafRoundtableConversationRow)
.where(MafRoundtableConversationRow.id == conversation_id)
.with_for_update()
)
).scalars().first()
if conv is None or conv.owner_user_id != owner_user_id:
return None
# ``waiting_input`` with no active run is a clarification
# turn. It is intentionally writable so the user can
# answer the clarification; approval/workflow waits keep
# their active run and remain protected by the CAS.
if conv.safe_status in _ACTIVE_SESSION_STATUSES and not (
conv.safe_status == "waiting_input" and conv.active_run_id is None
):
return {"conflict": True}
# 3. Ensure internal session exists.
start_run = True if session_blueprint is None else bool(
session_blueprint.get("start_run", True)
)
participant_blueprint = list(
(session_blueprint or {}).get("participants") or []
)
if conv.internal_session_id is None:
if session_blueprint is None:
return {"no_session_config": True}
session_row = MafRoundtableSessionRow(
id=uuid4().hex,
user_id=owner_user_id,
title=session_blueprint.get("title") or conv.title or "",
task_text=session_blueprint.get("task_text") or content,
task_payload_json=session_blueprint.get("task_payload"),
mode=session_blueprint.get("mode", "structured"),
status="running" if start_run else "waiting_input",
model_name=session_blueprint.get("model_name"),
reasoning_effort=session_blueprint.get("reasoning_effort"),
manager_agent_id=session_blueprint.get("manager_agent_id"),
max_rounds=session_blueprint.get("max_rounds", 8),
write_policy=session_blueprint.get("write_policy", "confirm_high_risk"),
capability_snapshot_json=session_blueprint.get("capability_snapshot"),
created_at=now,
updated_at=now,
)
db.add(session_row)
await db.flush()
conv.internal_session_id = session_row.id
else:
session_row = (
await db.execute(
select(MafRoundtableSessionRow).where(
MafRoundtableSessionRow.id == conv.internal_session_id
)
)
).scalars().first()
if session_row is None or session_row.user_id != owner_user_id:
# Never repair a corrupted private link by guessing
# an id or attaching another user's session.
return {"no_session_config": True}
session_row.status = "running" if start_run else "waiting_input"
session_row.updated_at = now
# Participants are selected by the App-layer trusted
# dispatch catalog and inserted in this same transaction.
# A clarification may create the session before a route is
# selected; the first real dispatch fills that empty set.
existing_participants = (
await db.execute(
select(MafRoundtableParticipantRow.id).where(
MafRoundtableParticipantRow.session_id == session_row.id
)
)
).scalars().all()
if not existing_participants and participant_blueprint:
seen_agents: set[str] = set()
for participant in participant_blueprint:
agent_id = str(participant.get("agent_id") or "").strip()
if not agent_id or agent_id in seen_agents:
continue
seen_agents.add(agent_id)
db.add(MafRoundtableParticipantRow(
id=uuid4().hex,
session_id=session_row.id,
agent_id=agent_id,
display_name=str(participant.get("display_name") or ""),
role=str(participant.get("role") or "seat"),
sort_order=int(participant.get("sort_order", 0)),
thread_id=None,
sandbox_id=None,
status="idle",
last_turn_index=None,
capability_snapshot_json=participant.get("capability_snapshot"),
created_at=now,
updated_at=now,
))
await db.flush()
# 4. Create pending run linked to the real session.
run_row: MafRoundtableRunRow | None = None
if start_run:
run_row = MafRoundtableRunRow(
id=uuid4().hex,
session_id=conv.internal_session_id,
status="pending",
workflow_version=workflow_version,
started_at=None,
created_at=now,
updated_at=now,
)
db.add(run_row)
await db.flush()
# 5. Allocate unified seq: message + event share the same seq.
item_result = await self.append_conversation_item(
db,
conversation=conv,
event_type="user.message.created",
event_data={"content": content},
message={
"message_kind": "user",
"role": "user",
"content": content,
"metadata": message_metadata,
# Conversation messages are public and must not
# carry the internal run id.
"run_id": None,
},
run_id=None,
)
# 6. Claim the conversation.
conv.safe_status = "running" if start_run else "waiting_input"
conv.active_run_id = run_row.id if run_row is not None else None
conv.updated_at = now
await db.flush()
from deerflow.persistence.maf_roundtable.conversations import conversation_internal_to_dict
from deerflow.persistence.maf_roundtable.messages import message_to_dict
msg_row = (
await db.execute(
select(MafRoundtableMessageRow).where(
MafRoundtableMessageRow.id == item_result["message_id"]
)
)
).scalars().first()
return {
"message": message_to_dict(msg_row) if msg_row else None,
"run": run_to_dict(run_row) if run_row is not None else None,
"conversation": conversation_internal_to_dict(conv),
"conversation_id": conversation_id,
"seq": item_result["seq"],
}
except IntegrityError:
return {"conflict": True}
__all__ = [
"MafActionRepository",
"MafActionSecretRepository",
"MafApprovalRepository",
"MafConversationEventRepository",
"MafConversationRepository",
"MafEventRepository",
"MafMessageRepository",
"MafParticipantRepository",
"MafRoundtableStore",
"MafRunRepository",
@@ -30,6 +30,7 @@ _BUILTIN_METADATA: dict[str, tuple[str, str]] = {
"grep": ("read", "R0"),
"glob": ("read", "R0"),
"ls": ("read", "R0"),
"read_peer_delivery": ("read", "R0"),
"invoke_skill": ("skill", "R1"),
"skill_search": ("skill", "R1"),
"task": ("read", "R2"),