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

@@ -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",