feat(maf-roundtable): add Phase-1 multi-agent roundtable infrastructure

Ship an independent, feature-flag-gated MAF roundtable skeleton with six
isolated tables, atomic single-transaction run launch/cancel, owner-scoped
read/write split, shared config enums, and HTTP/concurrency regression tests.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
董宏凯andCursor committed 2026-08-01 01:07:05 +08:00
1 parent a0a75a9964
commit e690475e6e
27 files changed
+5369 -101

No files matched your search

@@ -11,9 +11,9 @@ from pydantic import BaseModel, ConfigDict, Field
from deerflow.config.acp_config import ACPAgentConfig, load_acp_config_from_dict
from deerflow.config.agents_api_config import AgentsApiConfig, load_agents_api_config_from_dict
from deerflow.config.browser_context_config import BrowserContextConfig
from deerflow.config.checkpointer_config import CheckpointerConfig, load_checkpointer_config_from_dict
from deerflow.config.concurrency_config import ConcurrencyConfig
from deerflow.config.database_config import DatabaseConfig
from deerflow.config.checkpointer_config import CheckpointerConfig, load_checkpointer_config_from_dict
from deerflow.config.concurrency_config import ConcurrencyConfig
from deerflow.config.database_config import DatabaseConfig
from deerflow.config.extensions_config import ExtensionsConfig
from deerflow.config.gateway_config import GatewayConfig
from deerflow.config.guardrails_config import GuardrailsConfig, load_guardrails_config_from_dict
@@ -21,6 +21,7 @@ from deerflow.config.knowledge_config import KnowledgeConfig
from deerflow.config.knowledge_ingest_config import KnowledgeIngestConfig
from deerflow.config.log_system_config import LogSystemConfig
from deerflow.config.login_config import AuthLoginConfig
from deerflow.config.maf_roundtable_config import MafRoundtableConfig
from deerflow.config.memory_config import MemoryConfig, load_memory_config_from_dict
from deerflow.config.model_config import ModelConfig
from deerflow.config.run_events_config import RunEventsConfig
@@ -138,13 +139,14 @@ class AppConfig(BaseModel):
gateway: GatewayConfig = Field(default_factory=GatewayConfig, description="Gateway FastAPI listening port (used by intra-process loopback)")
run_events: RunEventsConfig = Field(default_factory=RunEventsConfig, description="Run event storage configuration")
checkpointer: CheckpointerConfig | None = Field(default=None, description="Checkpointer configuration")
stream_bridge: StreamBridgeConfig | None = Field(default=None, description="Stream bridge configuration")
concurrency: ConcurrencyConfig = Field(default_factory=ConcurrencyConfig, description="Optional cross-worker concurrency coordination")
browser_context: BrowserContextConfig = Field(default_factory=BrowserContextConfig, description="Optional browser page capture integration")
stream_bridge: StreamBridgeConfig | None = Field(default=None, description="Stream bridge configuration")
concurrency: ConcurrencyConfig = Field(default_factory=ConcurrencyConfig, description="Optional cross-worker concurrency coordination")
browser_context: BrowserContextConfig = Field(default_factory=BrowserContextConfig, description="Optional browser page capture integration")
knowledge: KnowledgeConfig = Field(default_factory=KnowledgeConfig, description="Product knowledge base (obsidian-wiki compatible vault) configuration")
knowledge_ingest: KnowledgeIngestConfig = Field(default_factory=KnowledgeIngestConfig, description="External knowledge-ingest endpoint configuration")
task_deeplink: TaskDeeplinkConfig = Field(default_factory=TaskDeeplinkConfig, description="任务深链(rwfx)目的树闸门与跳转地址配置(前端经 /api/public/config/task-deeplink 读取)")
y_log: YLogConfig = Field(default_factory=YLogConfig, description="操作日志上报配置(前端经 /api/public/config/y-log 读取)")
maf_roundtable: MafRoundtableConfig = Field(default_factory=MafRoundtableConfig, description="Microsoft Agent Framework 多智能体会商实验功能开关(部署级,默认关闭;关闭时 SDK 延迟不加载,写接口返回 503)")
@classmethod
def resolve_config_path(cls, config_path: str | None = None) -> Path:
@@ -0,0 +1,72 @@
"""Microsoft Agent Framework 多智能体会商实验功能开关配置。
本段为**部署级**特性开关:默认关闭。关闭时:
- Gateway 启动**不**加载 MAF SDK(SDK 延迟导入,仅在实际启用并触发会商 run
时才在 ``app.maf_roundtable`` 内 import)。
- ``/api/maf-roundtable/*`` 路由仍注册,但所有写接口与健康检查返回 ``503
Service Disabled``;只读的会话列表/详情可继续工作以便管理员查看历史。
- 前端入口由 ``GET /api/maf-roundtable/health`` 的 ``enabled`` 字段决定是否
显示。
段内只有开关与运行参数,无密钥,可公开只读(仿 ``y_log_config`` 的写法)。
``MafMode`` / ``MafWritePolicy`` 是部署配置与 API schema 共用的单一来源枚举,
避免两处各自维护一套合法值。
"""
from __future__ import annotations
from typing import Literal
from pydantic import BaseModel, Field
# ── shared enums (config + API schemas) ───────────────────────────────────
MafMode = Literal["structured", "group_chat"]
MafWritePolicy = Literal["auto", "confirm_high_risk", "confirm_all_writes"]
MafParticipantRole = Literal["manager", "seat"]
class MafRoundtableConfig(BaseModel):
"""Microsoft Agent Framework 多智能体会商实验功能开关。
默认 ``enabled=False``:这是一个独立于现有 ``RoundtablePlanningPage`` 的
实验性功能,不替换旧会商;首期仅管理员/白名单可见,关闭时完全不影响
Gateway 启动与旧功能行为。
"""
enabled: bool = Field(
default=False,
description="是否启用 MAF 多智能体会商实验功能;关闭时 SDK 延迟不加载,写接口返回 503。",
)
# 默认编排模式(用户可在创建会商时覆盖)。
default_mode: MafMode = Field(
default="structured",
description="默认编排模式:structured(固定流程)| group_chat(动态群聊)",
)
# 默认写入策略(auto / confirm_high_risk / confirm_all_writes)。
default_write_policy: MafWritePolicy = Field(
default="confirm_high_risk",
description="默认外部写入策略:auto / confirm_high_risk / confirm_all_writes",
)
# 默认最大轮次(群聊硬上限)。
default_max_rounds: int = Field(
default=8,
ge=1,
le=64,
description="默认最大轮次上限(群聊模式硬上限,避免弱模型无限讨论)",
)
# 管理员诊断是否可见所有用户的会商(true=管理员跨用户读,false=管理员也只能看自己的)。
admin_diagnostic_access: bool = Field(
default=True,
description="管理员是否可跨用户读取所有 MAF 会商用于诊断(仅读,不含写)",
)
__all__ = [
"MafMode",
"MafParticipantRole",
"MafRoundtableConfig",
"MafWritePolicy",
]
@@ -0,0 +1,72 @@
"""Microsoft Agent Framework (MAF) roundtable experiment persistence.
Six independent tables — **no foreign keys to the legacy ``roundtable_*``
tables** — so the existing multi-agent roundtable keeps its current behavior,
schema, and recovery semantics untouched. The MAF experiment is fully
isolated: it has its own session / participant / run / event / action /
approval tables.
Boundary: this package lives in the harness layer (``deerflow.*``) and never
imports from ``app.*`` or the MAF SDK. The MAF SDK is loaded lazily inside
``app.maf_roundtable`` only when the feature flag is on and a run is actually
started (Phase 2+).
Tables (see the implementation plan §8):
- ``maf_roundtable_sessions`` — one MAF roundtable session (task + mode + capability snapshot)
- ``maf_roundtable_participants`` — manager + seat agents bound to a session
- ``maf_roundtable_runs`` — one execution run of a session
- ``maf_roundtable_events`` — monotonic per-run event stream (``(run_id, seq)`` unique)
- ``maf_roundtable_actions`` — external write / tool actions (idempotency-keyed)
- ``maf_roundtable_approvals`` — pending human-approval requests
"""
from __future__ import annotations
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from deerflow.persistence.maf_roundtable.actions import MafActionRepository
from deerflow.persistence.maf_roundtable.approvals import MafApprovalRepository
from deerflow.persistence.maf_roundtable.events import MafEventRepository
from deerflow.persistence.maf_roundtable.model import (
MafRoundtableActionRow,
MafRoundtableApprovalRow,
MafRoundtableEventRow,
MafRoundtableParticipantRow,
MafRoundtableRunRow,
MafRoundtableSessionRow,
)
from deerflow.persistence.maf_roundtable.participants import MafParticipantRepository
from deerflow.persistence.maf_roundtable.runs import MafRunRepository
from deerflow.persistence.maf_roundtable.sessions import MafSessionRepository
from deerflow.persistence.maf_roundtable.store import MafRoundtableStore
__all__ = [
"MafActionRepository",
"MafApprovalRepository",
"MafEventRepository",
"MafParticipantRepository",
"MafRoundtableActionRow",
"MafRoundtableApprovalRow",
"MafRoundtableEventRow",
"MafRoundtableParticipantRow",
"MafRoundtableRunRow",
"MafRoundtableSessionRow",
"MafRoundtableStore",
"MafRunRepository",
"MafSessionRepository",
"make_maf_roundtable_store",
]
def make_maf_roundtable_store(session_factory: async_sessionmaker[AsyncSession] | None) -> MafRoundtableStore | None:
"""Construct the MAF roundtable facade store.
Returns ``None`` when no DB session factory is configured (memory mode) —
the router then surfaces ``503 Service Disabled`` so the feature is
cleanly off rather than silently dropping data. The lifespan logs the
initialization and any failure (MAF-01-03).
"""
if session_factory is None:
return None
return MafRoundtableStore(session_factory)
@@ -0,0 +1,137 @@
"""Action repository for the MAF roundtable experiment (external writes).
Records every external write / tool action with an idempotency key so the
Action Coordinator (Phase 5) can guarantee at-most-once execution across
retries / restarts. Phase 1 ships the storage + CRUD; the Coordinator itself
is Phase 5. ``arguments_redacted_json`` / ``result_redacted_json`` must
already have credentials / tokens / cookies stripped by the writer — the
store does not re-redact.
"""
from __future__ import annotations
from datetime import UTC, datetime
from typing import Any
from uuid import uuid4
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from deerflow.persistence.maf_roundtable.model import MafRoundtableActionRow
def _now() -> datetime:
return datetime.now(UTC)
def _to_dict(row: MafRoundtableActionRow) -> dict[str, Any]:
return {
"id": row.id,
"session_id": row.session_id,
"run_id": row.run_id,
"agent_id": row.agent_id,
"tool_name": row.tool_name,
"logical_action_id": row.logical_action_id,
"idempotency_key": row.idempotency_key,
"target_key": row.target_key,
"risk_level": row.risk_level,
"status": row.status,
"arguments": row.arguments_redacted_json,
"result": row.result_redacted_json,
"external_object_id": row.external_object_id,
"approval_id": row.approval_id,
"attempt_count": row.attempt_count,
"started_at": row.started_at.isoformat() if isinstance(row.started_at, datetime) else row.started_at,
"finished_at": row.finished_at.isoformat() if isinstance(row.finished_at, datetime) else row.finished_at,
"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,
}
class MafActionRepository:
def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
self._sf = session_factory
async def create_action(self, data: dict[str, Any]) -> dict[str, Any]:
"""Create an action. Raises ``IntegrityError`` if the ``idempotency_key``
already exists (caller should treat that as "already submitted" and
fetch the existing row via ``get_by_idempotency_key``).
"""
now = _now()
row = MafRoundtableActionRow(
id=data.get("id") or uuid4().hex,
session_id=str(data["session_id"]),
run_id=data.get("run_id"),
agent_id=data.get("agent_id"),
tool_name=str(data["tool_name"]),
logical_action_id=data.get("logical_action_id"),
idempotency_key=str(data["idempotency_key"]),
target_key=data.get("target_key"),
risk_level=str(data.get("risk_level") or "R0"),
status=str(data.get("status") or "pending"),
arguments_redacted_json=data.get("arguments"),
result_redacted_json=data.get("result"),
external_object_id=data.get("external_object_id"),
approval_id=data.get("approval_id"),
attempt_count=int(data.get("attempt_count", 0)),
started_at=data.get("started_at"),
finished_at=data.get("finished_at"),
created_at=now,
updated_at=now,
)
async with self._sf() as session:
session.add(row)
await session.commit()
return await self.get_action(row.id) # type: ignore[arg-type]
async def get_action(self, action_id: str) -> dict[str, Any] | None:
async with self._sf() as session:
stmt = select(MafRoundtableActionRow).where(MafRoundtableActionRow.id == action_id).limit(1)
row = (await session.execute(stmt)).scalars().first()
return _to_dict(row) if row is not None else None
async def get_by_idempotency_key(self, key: str) -> dict[str, Any] | None:
async with self._sf() as session:
stmt = select(MafRoundtableActionRow).where(MafRoundtableActionRow.idempotency_key == key).limit(1)
row = (await session.execute(stmt)).scalars().first()
return _to_dict(row) if row is not None else None
async def list_actions(
self, *, session_id: str | None = None, run_id: str | None = None, status: str | None = None
) -> list[dict[str, Any]]:
stmt = select(MafRoundtableActionRow)
if session_id is not None:
stmt = stmt.where(MafRoundtableActionRow.session_id == session_id)
if run_id is not None:
stmt = stmt.where(MafRoundtableActionRow.run_id == run_id)
if status is not None:
stmt = stmt.where(MafRoundtableActionRow.status == status)
stmt = stmt.order_by(MafRoundtableActionRow.created_at.asc())
async with self._sf() as session:
rows = (await session.execute(stmt)).scalars().all()
return [_to_dict(r) for r in rows]
async def update_action(self, action_id: str, fields: dict[str, Any]) -> dict[str, Any] | None:
async with self._sf() as session:
stmt = select(MafRoundtableActionRow).where(MafRoundtableActionRow.id == action_id).limit(1)
row = (await session.execute(stmt)).scalars().first()
if row is None:
return None
col_map = {
"status": "status",
"risk_level": "risk_level",
"arguments": "arguments_redacted_json",
"result": "result_redacted_json",
"external_object_id": "external_object_id",
"approval_id": "approval_id",
"attempt_count": "attempt_count",
"started_at": "started_at",
"finished_at": "finished_at",
}
for key, value in fields.items():
col = col_map.get(key)
if col is not None:
setattr(row, col, value)
row.updated_at = _now()
await session.commit()
return _to_dict(row)
@@ -0,0 +1,132 @@
"""Approval repository for the MAF roundtable experiment.
Pending human-approval requests for high-risk external writes. Phase 1 ships
the storage + CRUD + decision transition; the actual pause/resume wiring
(checkpoint restore after a decision) is Phase 5.
"""
from __future__ import annotations
from datetime import UTC, datetime
from typing import Any
from uuid import uuid4
from sqlalchemy import select, update
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from deerflow.persistence.maf_roundtable.model import MafRoundtableApprovalRow
def _now() -> datetime:
return datetime.now(UTC)
def _to_dict(row: MafRoundtableApprovalRow) -> dict[str, Any]:
return {
"id": row.id,
"session_id": row.session_id,
"run_id": row.run_id,
"action_id": row.action_id,
"requested_by_agent_id": row.requested_by_agent_id,
"status": row.status,
"summary": row.summary,
"payload": row.payload_redacted_json,
"decided_by": row.decided_by,
"decided_at": row.decided_at.isoformat() if isinstance(row.decided_at, datetime) else row.decided_at,
"expires_at": row.expires_at.isoformat() if isinstance(row.expires_at, datetime) else row.expires_at,
"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,
}
class MafApprovalRepository:
def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
self._sf = session_factory
async def create_approval(self, data: dict[str, Any]) -> dict[str, Any]:
now = _now()
row = MafRoundtableApprovalRow(
id=data.get("id") or uuid4().hex,
session_id=str(data["session_id"]),
run_id=data.get("run_id"),
action_id=data.get("action_id"),
requested_by_agent_id=data.get("requested_by_agent_id"),
status=str(data.get("status") or "pending"),
summary=str(data.get("summary") or ""),
payload_redacted_json=data.get("payload"),
decided_by=data.get("decided_by"),
decided_at=data.get("decided_at"),
expires_at=data.get("expires_at"),
created_at=now,
updated_at=now,
)
async with self._sf() as session:
session.add(row)
await session.commit()
return await self.get_approval(row.id) # type: ignore[arg-type]
async def get_approval(self, approval_id: str) -> dict[str, Any] | None:
async with self._sf() as session:
stmt = select(MafRoundtableApprovalRow).where(MafRoundtableApprovalRow.id == approval_id).limit(1)
row = (await session.execute(stmt)).scalars().first()
return _to_dict(row) if row is not None else None
async def list_approvals(
self, *, run_id: str | None = None, status: str | None = None
) -> list[dict[str, Any]]:
stmt = select(MafRoundtableApprovalRow)
if run_id is not None:
stmt = stmt.where(MafRoundtableApprovalRow.run_id == run_id)
if status is not None:
stmt = stmt.where(MafRoundtableApprovalRow.status == status)
stmt = stmt.order_by(MafRoundtableApprovalRow.created_at.asc())
async with self._sf() as session:
rows = (await session.execute(stmt)).scalars().all()
return [_to_dict(r) for r in rows]
async def decide(
self,
approval_id: str,
*,
decision: str,
decided_by: str | None = None,
) -> dict[str, Any] | None:
"""Record a decision atomically. ``decision`` is ``approved`` /
``rejected`` / ``expired``.
The transition is a single conditional UPDATE:
``UPDATE … SET status=:decision … WHERE id=:id AND status='pending'``.
``rowcount == 1`` means this caller won the race; ``rowcount == 0``
means the approval is missing **or** was already decided by someone
else, which the caller surfaces as a conflict. This guarantees a
decision can never be overwritten by a concurrent (or later) request,
and the winning approver + timestamp are the ones persisted.
"""
if decision not in ("approved", "rejected", "expired"):
raise ValueError(f"invalid approval decision: {decision}")
now = _now()
async with self._sf() as session:
result = await session.execute(
update(MafRoundtableApprovalRow)
.where(
MafRoundtableApprovalRow.id == approval_id,
MafRoundtableApprovalRow.status == "pending",
)
.values(
status=decision,
decided_by=decided_by,
decided_at=now,
updated_at=now,
)
)
await session.commit()
if result.rowcount == 1: # type: ignore[union-attr]
# This caller won the race — the decision is persisted.
return await self.get_approval(approval_id)
# rowcount == 0: either the approval is missing, or it was already
# decided by a concurrent request. Distinguish so the service layer can
# map missing→404 and already-decided→409.
existing = await self.get_approval(approval_id)
if existing is None:
return None
raise ValueError(f"approval already decided: {existing['status']}")
@@ -0,0 +1,168 @@
"""Event repository for the MAF roundtable experiment — monotonic per-run seq.
``(run_id, seq)`` is unique. The store allocates seq via ``SELECT MAX(seq) +
1`` and retries on ``IntegrityError`` so concurrent appends from parallel
seats cannot collide or skip seq values. This is the standard portable
approach (works on sqlite / postgres / mysql — no ``RETURNING`` / ``UPSERT``
dialect differences).
Pull API: ``list_events(run_id, after_seq=N)`` returns events with ``seq > N``
in ascending seq order — the断线补拉 contract. The router exposes this both
as a one-shot ``GET /runs/{run_id}/events?after_seq=N`` and as an SSE
``GET /runs/{run_id}/stream?after_seq=N`` (Phase 6 wires the SSE reducer;
Phase 1 ships the storage + one-shot pull).
"""
from __future__ import annotations
from datetime import UTC, datetime
from typing import Any
from uuid import uuid4
from sqlalchemy import func, select
from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from deerflow.persistence.maf_roundtable.model import MafRoundtableEventRow
from deerflow.persistence.maf_roundtable.runs import MafRunRepository
# Retry budget for the MAX+1 race: a parallel seat that wins the INSERT between
# our SELECT and our INSERT forces one retry. 8 is far more than the realistic
# concurrency (one run has at most ~8 seats), so a true deadlock here would
# indicate a bug, not contention.
_SEQ_INSERT_RETRIES = 8
def _now() -> datetime:
return datetime.now(UTC)
def _to_dict(row: MafRoundtableEventRow) -> dict[str, Any]:
return {
"id": row.id,
"session_id": row.session_id,
"run_id": row.run_id,
"seq": row.seq,
"event_type": row.event_type,
"agent_id": row.agent_id,
"turn_index": row.turn_index,
"payload": row.payload_json,
"created_at": row.created_at.isoformat() if isinstance(row.created_at, datetime) else row.created_at,
}
class MafEventRepository:
def __init__(
self,
session_factory: async_sessionmaker[AsyncSession],
run_repo: MafRunRepository | None = None,
) -> None:
self._sf = session_factory
self._run_repo = run_repo
async def append_event(
self,
*,
session_id: str,
run_id: str,
event_type: str,
agent_id: str | None = None,
turn_index: int | None = None,
payload: dict[str, Any] | None = None,
) -> dict[str, Any]:
"""Append one event with a monotonic per-run seq.
Concurrent appends are safe: each attempts ``MAX(seq)+1`` and retries
on the ``(run_id, seq)`` unique violation. The run's
``last_event_seq`` cache is bumped forward (max wins) so pollers can
cheaply check ``runs.last_event_seq`` without scanning the events
table.
"""
last_exc: Exception | None = None
for _ in range(_SEQ_INSERT_RETRIES):
async with self._sf() as session:
max_seq = (
await session.execute(
select(func.max(MafRoundtableEventRow.seq)).where(
MafRoundtableEventRow.run_id == run_id
)
)
).scalar_one()
next_seq = int(max_seq or 0) + 1
row = MafRoundtableEventRow(
id=uuid4().hex,
session_id=session_id,
run_id=run_id,
seq=next_seq,
event_type=event_type,
agent_id=agent_id,
turn_index=turn_index,
payload_json=payload,
created_at=_now(),
)
session.add(row)
try:
await session.commit()
except IntegrityError as exc: # noqa: PERF203 - retry path
last_exc = exc
await session.rollback()
continue
if self._run_repo is not None:
# best-effort cache bump; never let a cache failure abort
# an event the user already sees.
try:
await self._run_repo.bump_last_event_seq(run_id, next_seq)
except Exception: # noqa: BLE001
pass
return _to_dict(row)
raise IntegrityError(
"Could not append MAF event after retries (run_id seq race)",
params=None,
orig=last_exc,
)
async def append_events(
self, *, session_id: str, run_id: str, events: list[dict[str, Any]]
) -> list[dict[str, Any]]:
"""Append a batch in order. Each event is appended sequentially so the
per-run seq stays monotonic; a parallel writer can interleave but never
reorder within this batch.
"""
out: list[dict[str, Any]] = []
for ev in events:
out.append(
await self.append_event(
session_id=session_id,
run_id=run_id,
event_type=str(ev["event_type"]),
agent_id=ev.get("agent_id"),
turn_index=ev.get("turn_index"),
payload=ev.get("payload"),
)
)
return out
async def list_events(
self, run_id: str, *, after_seq: int = 0, limit: int = 1000
) -> list[dict[str, Any]]:
"""断线补拉: events with ``seq > after_seq`` in ascending seq order."""
stmt = (
select(MafRoundtableEventRow)
.where(MafRoundtableEventRow.run_id == run_id, MafRoundtableEventRow.seq > after_seq)
.order_by(MafRoundtableEventRow.seq.asc())
.limit(limit)
)
async with self._sf() as session:
rows = (await session.execute(stmt)).scalars().all()
return [_to_dict(r) for r in rows]
async def latest_seq(self, run_id: str) -> int:
async with self._sf() as session:
max_seq = (
await session.execute(
select(func.max(MafRoundtableEventRow.seq)).where(
MafRoundtableEventRow.run_id == run_id
)
)
).scalar_one()
return int(max_seq or 0)
@@ -0,0 +1,290 @@
"""ORM models for the MAF (Microsoft Agent Framework) roundtable experiment.
Six independent tables — **no foreign keys to the legacy ``roundtable_*``
tables** (``roundtable_jobs`` / ``roundtable_drafts`` /
``roundtable_task_drafts``). The MAF experiment is fully isolated: it has its
own session / participant / run / event / action / approval tables, keyed by
its own surrogate ids, so the legacy multi-agent roundtable keeps its current
behavior, schema, and recovery semantics untouched.
Tables (see the implementation plan §8):
- ``maf_roundtable_sessions`` — one MAF roundtable session (task + mode + capability snapshot)
- ``maf_roundtable_participants`` — manager + seat agents bound to a session
- ``maf_roundtable_runs`` — one execution run of a session
- ``maf_roundtable_events`` — monotonic per-run event stream (``(run_id, seq)`` unique)
- ``maf_roundtable_actions`` — external write / tool actions (idempotency-keyed)
- ``maf_roundtable_approvals`` — pending human-approval requests
User isolation: ``maf_roundtable_sessions.user_id`` is the owner; all child
rows are filtered through the owning session. ``user_id`` on child tables
(``actions``) is audit-only. Admins bypass the owner filter when
``maf_roundtable.admin_diagnostic_access`` is true.
All JSON / large-text columns use the portable types so the schema is identical
across sqlite / postgres / mysql (see ``deerflow.persistence.types``).
"""
from __future__ import annotations
from datetime import UTC, datetime
from sqlalchemy import (
ForeignKey,
Integer,
String,
UniqueConstraint,
)
from sqlalchemy.orm import Mapped, mapped_column
from deerflow.persistence.base import Base
from deerflow.persistence.types import BeijingDateTime, PortableJSON, PortableLongText
def _now() -> datetime:
return datetime.now(UTC)
# ── 1. sessions ───────────────────────────────────────────────────────────
class MafRoundtableSessionRow(Base):
"""One MAF roundtable session (the user's task + chosen mode + frozen capability snapshot).
Owner-scoped by ``user_id``. ``capability_snapshot_json`` freezes the
agents / tools / skills configuration at creation time so a run can be
reproduced even if the agent config changes later. ``fact_ledger_json``
holds the shared fact ledger (confirmed facts / tool results / pending /
failed actions) updated as the run progresses.
"""
__tablename__ = "maf_roundtable_sessions"
id: Mapped[str] = mapped_column(String(64), primary_key=True)
user_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
title: Mapped[str] = mapped_column(String(255), default="")
task_text: Mapped[str] = mapped_column(PortableLongText, nullable=False)
task_payload_json: Mapped[dict | None] = mapped_column(PortableJSON(), nullable=True)
# structured | group_chat
mode: Mapped[str] = mapped_column(String(16), default="structured", index=True)
# draft | running | waiting_approval | waiting_input | completed | failed | cancelled
status: Mapped[str] = mapped_column(String(32), default="draft", index=True)
model_name: Mapped[str | None] = mapped_column(String(128), nullable=True)
reasoning_effort: Mapped[str | None] = mapped_column(String(32), nullable=True)
manager_agent_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
max_rounds: Mapped[int] = mapped_column(Integer, default=8)
# auto | confirm_high_risk | confirm_all_writes
write_policy: Mapped[str] = mapped_column(String(32), default="confirm_high_risk")
capability_snapshot_json: Mapped[dict | None] = mapped_column(PortableJSON(), nullable=True)
fact_ledger_json: Mapped[dict | None] = mapped_column(PortableJSON(), nullable=True)
final_result_json: Mapped[dict | None] = mapped_column(PortableJSON(), nullable=True)
created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=_now)
updated_at: Mapped[datetime] = mapped_column(
BeijingDateTime(), nullable=False, default=_now, onupdate=_now
)
# ── 2. participants ──────────────────────────────────────────────────────
class MafRoundtableParticipantRow(Base):
"""Manager + seat agents bound to a session.
One row per participant agent. ``role`` is ``manager`` / ``seat``.
``thread_id`` / ``sandbox_id`` bind the participant to its own DeerFlow
thread / sandbox (one seat = one thread = one sandbox). ``capability_snapshot_json``
freezes the agent's tools / skills at session creation time.
"""
__tablename__ = "maf_roundtable_participants"
__table_args__ = (
UniqueConstraint("session_id", "agent_id", name="uq_maf_participants_session_agent"),
)
id: Mapped[str] = mapped_column(String(64), primary_key=True)
session_id: Mapped[str] = mapped_column(
String(64), ForeignKey("maf_roundtable_sessions.id", ondelete="CASCADE"), nullable=False, index=True
)
agent_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
display_name: Mapped[str] = mapped_column(String(255), default="")
# manager | seat
role: Mapped[str] = mapped_column(String(16), default="seat")
sort_order: Mapped[int] = mapped_column(Integer, default=0)
thread_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
sandbox_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
# idle | running | done | failed | cancelled
status: Mapped[str] = mapped_column(String(16), default="idle")
last_turn_index: Mapped[int | None] = mapped_column(Integer, nullable=True)
capability_snapshot_json: Mapped[dict | None] = mapped_column(PortableJSON(), nullable=True)
created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=_now)
updated_at: Mapped[datetime] = mapped_column(
BeijingDateTime(), nullable=False, default=_now, onupdate=_now
)
# ── 3. runs ───────────────────────────────────────────────────────────────
class MafRoundtableRunRow(Base):
"""One execution run of a session.
``maf_checkpoint_json`` stores the MAF workflow checkpoint (or a reference)
for resume-after-restart. ``last_event_seq`` is a denormalized cache of the
latest event seq for fast polling (the authoritative seq lives in
``maf_roundtable_events``). ``token_usage_json`` accumulates per-run token
usage. ``latency_ms`` is the wall-clock duration.
"""
__tablename__ = "maf_roundtable_runs"
id: Mapped[str] = mapped_column(String(64), primary_key=True)
session_id: Mapped[str] = mapped_column(
String(64), ForeignKey("maf_roundtable_sessions.id", ondelete="CASCADE"), nullable=False, index=True
)
# pending | running | waiting_approval | waiting_input | completed | failed | cancelled
status: Mapped[str] = mapped_column(String(32), default="pending", index=True)
workflow_version: Mapped[str | None] = mapped_column(String(64), nullable=True)
maf_checkpoint_json: Mapped[dict | None] = mapped_column(PortableJSON(), nullable=True)
last_event_seq: Mapped[int] = mapped_column(Integer, default=0)
started_at: Mapped[datetime | None] = mapped_column(BeijingDateTime(), nullable=True)
finished_at: Mapped[datetime | None] = mapped_column(BeijingDateTime(), nullable=True)
error_code: Mapped[str | None] = mapped_column(String(64), nullable=True)
error_message_safe: Mapped[str | None] = mapped_column(PortableLongText, nullable=True)
token_usage_json: Mapped[dict | None] = mapped_column(PortableJSON(), nullable=True)
latency_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=_now)
updated_at: Mapped[datetime] = mapped_column(
BeijingDateTime(), nullable=False, default=_now, onupdate=_now
)
# ── 4. events ─────────────────────────────────────────────────────────────
class MafRoundtableEventRow(Base):
"""Monotonic per-run event stream.
``(run_id, seq)`` is unique — seq is monotonically increasing per run. The
store allocates seq by ``SELECT MAX(seq) + 1`` and retries on
``IntegrityError`` so concurrent appends from parallel seats cannot collide
or skip seq values. ``payload_json`` carries the event-specific body (tool
result, agent message delta, fact-recorded, etc.); sensitive fields must
already be redacted by the writer.
"""
__tablename__ = "maf_roundtable_events"
__table_args__ = (
UniqueConstraint("run_id", "seq", name="uq_maf_events_run_seq"),
)
id: Mapped[str] = mapped_column(String(64), primary_key=True)
session_id: Mapped[str] = mapped_column(
String(64), ForeignKey("maf_roundtable_sessions.id", ondelete="CASCADE"), nullable=False, index=True
)
run_id: Mapped[str] = mapped_column(
String(64), ForeignKey("maf_roundtable_runs.id", ondelete="CASCADE"), nullable=False, index=True
)
seq: Mapped[int] = mapped_column(Integer, nullable=False)
# run.started | run.status_changed | workflow.checkpointed | manager.decision |
# agent.turn_started | agent.message.delta | agent.message.completed |
# skill.selected | skill.started | skill.completed | tool.requested | tool.started |
# tool.progress | tool.completed | tool.failed | action.waiting_approval |
# action.approved | action.rejected | artifact.created | fact.recorded |
# run.completed | run.failed
event_type: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
agent_id: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
turn_index: Mapped[int | None] = mapped_column(Integer, nullable=True)
payload_json: Mapped[dict | None] = mapped_column(PortableJSON(), nullable=True)
created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=_now, index=True)
# ── 5. actions ─────────────────────────────────────────────────────────────
class MafRoundtableActionRow(Base):
"""External write / tool action record (idempotency-keyed).
The Action Coordinator (Phase 5) uses ``idempotency_key`` to guarantee
at-most-once execution across retries / restarts. ``target_key`` carries a
per-business-object lease so parallel seats writing the same object are
serialized. ``risk_level`` is R0–R4. ``status`` is the action state machine:
pending | running | succeeded | failed | unknown | waiting_approval |
approved | rejected | compensated. ``arguments_redacted_json`` /
``result_redacted_json`` must already have credentials / tokens / cookies
stripped by the writer.
"""
__tablename__ = "maf_roundtable_actions"
__table_args__ = (
UniqueConstraint("idempotency_key", name="uq_maf_actions_idempotency"),
)
id: Mapped[str] = mapped_column(String(64), primary_key=True)
session_id: Mapped[str] = mapped_column(
String(64), ForeignKey("maf_roundtable_sessions.id", ondelete="CASCADE"), nullable=False, index=True
)
run_id: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
agent_id: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
tool_name: Mapped[str] = mapped_column(String(128), nullable=False, index=True)
logical_action_id: Mapped[str | None] = mapped_column(String(128), nullable=True)
idempotency_key: Mapped[str] = mapped_column(String(191), nullable=False, unique=True)
target_key: Mapped[str | None] = mapped_column(String(255), nullable=True, index=True)
# R0 | R1 | R2 | R3 | R4
risk_level: Mapped[str] = mapped_column(String(8), default="R0")
# pending | running | succeeded | failed | unknown | waiting_approval | approved | rejected | compensated
status: Mapped[str] = mapped_column(String(32), default="pending", index=True)
arguments_redacted_json: Mapped[dict | None] = mapped_column(PortableJSON(), nullable=True)
result_redacted_json: Mapped[dict | None] = mapped_column(PortableJSON(), nullable=True)
external_object_id: Mapped[str | None] = mapped_column(String(255), nullable=True)
approval_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
attempt_count: Mapped[int] = mapped_column(Integer, default=0)
started_at: Mapped[datetime | None] = mapped_column(BeijingDateTime(), nullable=True)
finished_at: Mapped[datetime | None] = mapped_column(BeijingDateTime(), nullable=True)
created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=_now)
updated_at: Mapped[datetime] = mapped_column(
BeijingDateTime(), nullable=False, default=_now, onupdate=_now
)
# ── 6. approvals ──────────────────────────────────────────────────────────
class MafRoundtableApprovalRow(Base):
"""Pending human-approval request for a high-risk external write.
``status`` is ``pending | approved | rejected | expired``. ``payload_redacted_json``
carries the action summary the user sees (redacted). ``expires_at`` is the
deadline after which the approval auto-expires and the action is marked
``rejected`` (or ``unknown`` if it may already have been sent).
"""
__tablename__ = "maf_roundtable_approvals"
id: Mapped[str] = mapped_column(String(64), primary_key=True)
session_id: Mapped[str] = mapped_column(
String(64), ForeignKey("maf_roundtable_sessions.id", ondelete="CASCADE"), nullable=False, index=True
)
run_id: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
action_id: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
requested_by_agent_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
# pending | approved | rejected | expired
status: Mapped[str] = mapped_column(String(16), default="pending", index=True)
summary: Mapped[str] = mapped_column(PortableLongText, default="")
payload_redacted_json: Mapped[dict | None] = mapped_column(PortableJSON(), nullable=True)
decided_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
decided_at: Mapped[datetime | None] = mapped_column(BeijingDateTime(), nullable=True)
expires_at: Mapped[datetime | None] = mapped_column(BeijingDateTime(), nullable=True, index=True)
created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=_now)
updated_at: Mapped[datetime] = mapped_column(
BeijingDateTime(), nullable=False, default=_now, onupdate=_now
)
__all__ = [
"MafRoundtableActionRow",
"MafRoundtableApprovalRow",
"MafRoundtableEventRow",
"MafRoundtableParticipantRow",
"MafRoundtableRunRow",
"MafRoundtableSessionRow",
]
@@ -0,0 +1,122 @@
"""Participant repository for the MAF roundtable experiment.
Participants are the manager + seat agents bound to a session. They are
created together with the session (``replace_participants`` is the atomic
full-replacement API mirroring ``task_buttons``) and read via the session.
``capability_snapshot_json`` freezes each agent's tools / skills at session
creation time.
"""
from __future__ import annotations
from datetime import UTC, datetime
from typing import Any
from uuid import uuid4
from sqlalchemy import delete, select
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from deerflow.persistence.maf_roundtable.model import MafRoundtableParticipantRow
def _now() -> datetime:
return datetime.now(UTC)
def _to_dict(row: MafRoundtableParticipantRow) -> dict[str, Any]:
return {
"id": row.id,
"session_id": row.session_id,
"agent_id": row.agent_id,
"display_name": row.display_name,
"role": row.role,
"sort_order": row.sort_order,
"thread_id": row.thread_id,
"sandbox_id": row.sandbox_id,
"status": row.status,
"last_turn_index": row.last_turn_index,
"capability_snapshot": row.capability_snapshot_json,
"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,
}
class MafParticipantRepository:
def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
self._sf = session_factory
async def list_participants(self, session_id: str) -> list[dict[str, Any]]:
stmt = (
select(MafRoundtableParticipantRow)
.where(MafRoundtableParticipantRow.session_id == session_id)
.order_by(MafRoundtableParticipantRow.sort_order.asc())
)
async with self._sf() as session:
rows = (await session.execute(stmt)).scalars().all()
return [_to_dict(r) for r in rows]
async def replace_participants(
self, session_id: str, participants: list[dict[str, Any]]
) -> list[dict[str, Any]]:
"""Atomically replace all participants of a session.
Each item: ``{agent_id, display_name?, role?, sort_order?, thread_id?,
sandbox_id?, capability_snapshot?}``. De-dupes by ``agent_id`` (last
wins) to honor the ``(session_id, agent_id)`` unique constraint.
"""
by_agent: dict[str, dict[str, Any]] = {}
for p in participants:
agent_id = str(p.get("agent_id") or "")
if not agent_id:
continue
by_agent[agent_id] = p
now = _now()
new_rows = [
MafRoundtableParticipantRow(
id=uuid4().hex,
session_id=session_id,
agent_id=agent_id,
display_name=str(p.get("display_name") or ""),
role=str(p.get("role") or "seat"),
sort_order=int(p.get("sort_order", 0)),
thread_id=p.get("thread_id"),
sandbox_id=p.get("sandbox_id"),
status=str(p.get("status") or "idle"),
last_turn_index=p.get("last_turn_index"),
capability_snapshot_json=p.get("capability_snapshot"),
created_at=now,
updated_at=now,
)
for agent_id, p in by_agent.items()
]
async with self._sf() as session:
await session.execute(
delete(MafRoundtableParticipantRow).where(
MafRoundtableParticipantRow.session_id == session_id
)
)
session.add_all(new_rows)
await session.commit()
return [_to_dict(r) for r in new_rows]
async def update_participant_status(
self, session_id: str, agent_id: str, *, status: str, last_turn_index: int | None = None
) -> dict[str, Any] | None:
async with self._sf() as session:
stmt = (
select(MafRoundtableParticipantRow)
.where(
MafRoundtableParticipantRow.session_id == session_id,
MafRoundtableParticipantRow.agent_id == agent_id,
)
.limit(1)
)
row = (await session.execute(stmt)).scalars().first()
if row is None:
return None
row.status = status
if last_turn_index is not None:
row.last_turn_index = last_turn_index
row.updated_at = _now()
await session.commit()
return _to_dict(row)
@@ -0,0 +1,129 @@
"""Run repository for the MAF roundtable experiment.
A run is one execution of a session. Phase 1 only persists the run row and its
status lifecycle — actual workflow execution (MAF SDK) is Phase 2+. The run
row carries the MAF checkpoint (for resume-after-restart) and a denormalized
``last_event_seq`` cache for fast polling; the authoritative seq lives in
``maf_roundtable_events``.
"""
from __future__ import annotations
from datetime import UTC, datetime
from typing import Any
from uuid import uuid4
from sqlalchemy import select, update
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from deerflow.persistence.maf_roundtable.model import MafRoundtableRunRow
def _now() -> datetime:
return datetime.now(UTC)
def run_to_dict(row: MafRoundtableRunRow) -> dict[str, Any]:
"""Serialise a run ORM row to a plain dict (public — reused by the store facade)."""
return {
"id": row.id,
"session_id": row.session_id,
"status": row.status,
"workflow_version": row.workflow_version,
"maf_checkpoint": row.maf_checkpoint_json,
"last_event_seq": row.last_event_seq,
"started_at": row.started_at.isoformat() if isinstance(row.started_at, datetime) else row.started_at,
"finished_at": row.finished_at.isoformat() if isinstance(row.finished_at, datetime) else row.finished_at,
"error_code": row.error_code,
"error_message_safe": row.error_message_safe,
"token_usage": row.token_usage_json,
"latency_ms": row.latency_ms,
"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,
}
# Back-compat alias for internal callers that used the old private name.
_to_dict = run_to_dict
class MafRunRepository:
def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
self._sf = session_factory
async def create_run(self, session_id: str, *, workflow_version: str | None = None) -> dict[str, Any]:
now = _now()
row = MafRoundtableRunRow(
id=uuid4().hex,
session_id=session_id,
status="pending",
workflow_version=workflow_version,
started_at=None, # pending = queued, not yet handed to the executor
created_at=now,
updated_at=now,
)
async with self._sf() as session:
session.add(row)
await session.commit()
return await self.get_run(row.id) # type: ignore[arg-type]
async def get_run(self, run_id: str) -> dict[str, Any] | None:
async with self._sf() as session:
stmt = select(MafRoundtableRunRow).where(MafRoundtableRunRow.id == run_id).limit(1)
row = (await session.execute(stmt)).scalars().first()
return _to_dict(row) if row is not None else None
async def list_runs(self, session_id: str) -> list[dict[str, Any]]:
stmt = (
select(MafRoundtableRunRow)
.where(MafRoundtableRunRow.session_id == session_id)
.order_by(MafRoundtableRunRow.created_at.desc())
)
async with self._sf() as session:
rows = (await session.execute(stmt)).scalars().all()
return [_to_dict(r) for r in rows]
async def update_run(self, run_id: str, fields: dict[str, Any]) -> dict[str, Any] | None:
async with self._sf() as session:
stmt = select(MafRoundtableRunRow).where(MafRoundtableRunRow.id == run_id).limit(1)
row = (await session.execute(stmt)).scalars().first()
if row is None:
return None
col_map = {
"status": "status",
"workflow_version": "workflow_version",
"maf_checkpoint": "maf_checkpoint_json",
"last_event_seq": "last_event_seq",
"started_at": "started_at",
"finished_at": "finished_at",
"error_code": "error_code",
"error_message_safe": "error_message_safe",
"token_usage": "token_usage_json",
"latency_ms": "latency_ms",
}
for key, value in fields.items():
col = col_map.get(key)
if col is not None:
setattr(row, col, value)
row.updated_at = _now()
await session.commit()
return _to_dict(row)
async def set_status(self, run_id: str, status: str) -> None:
async with self._sf() as session:
await session.execute(
update(MafRoundtableRunRow)
.where(MafRoundtableRunRow.id == run_id)
.values(status=status, updated_at=_now())
)
await session.commit()
async def bump_last_event_seq(self, run_id: str, seq: int) -> None:
"""Denormalized cache update — only bumps forward (max wins)."""
async with self._sf() as session:
await session.execute(
update(MafRoundtableRunRow)
.where(MafRoundtableRunRow.id == run_id, MafRoundtableRunRow.last_event_seq < seq)
.values(last_event_seq=seq, updated_at=_now())
)
await session.commit()
@@ -0,0 +1,201 @@
"""Session repository for the MAF roundtable experiment (owner-scoped CRUD).
Owner-scoped by ``user_id``: every read / update / delete checks the session's
owner against the caller. Admins bypass the owner filter when
``admin_diagnostic_access`` is true (handled in the service / router layer, not
here — the repo exposes both scoped and unscoped lookups).
Capability snapshot: ``capability_snapshot_json`` is frozen at creation time
(``create_session``) and never mutated by later updates — it is the audit /
reproducibility record of which agents / tools / skills were configured when
the session started. ``fact_ledger_json`` / ``final_result_json`` are mutable
and updated as the run progresses.
"""
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 MafRoundtableSessionRow
def _now() -> datetime:
return datetime.now(UTC)
def _to_dict(row: MafRoundtableSessionRow) -> dict[str, Any]:
return {
"id": row.id,
"user_id": row.user_id,
"title": row.title,
"task_text": row.task_text,
"task_payload": row.task_payload_json,
"mode": row.mode,
"status": row.status,
"model_name": row.model_name,
"reasoning_effort": row.reasoning_effort,
"manager_agent_id": row.manager_agent_id,
"max_rounds": row.max_rounds,
"write_policy": row.write_policy,
"capability_snapshot": row.capability_snapshot_json,
"fact_ledger": row.fact_ledger_json,
"final_result": row.final_result_json,
"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,
}
class MafSessionRepository:
"""Owner-scoped CRUD for MAF roundtable sessions."""
def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
self._sf = session_factory
async def create_session(self, data: dict[str, Any]) -> dict[str, Any]:
"""Create a new session. ``data`` must include ``user_id`` and ``task_text``."""
now = _now()
row = MafRoundtableSessionRow(
id=data.get("id") or uuid4().hex,
user_id=str(data["user_id"]),
title=str(data.get("title") or ""),
task_text=str(data["task_text"]),
task_payload_json=data.get("task_payload"),
mode=str(data.get("mode") or "structured"),
status=str(data.get("status") or "draft"),
model_name=data.get("model_name"),
reasoning_effort=data.get("reasoning_effort"),
manager_agent_id=data.get("manager_agent_id"),
max_rounds=int(data.get("max_rounds", 8)),
write_policy=str(data.get("write_policy") or "confirm_high_risk"),
capability_snapshot_json=data.get("capability_snapshot"),
fact_ledger_json=data.get("fact_ledger"),
final_result_json=data.get("final_result"),
created_at=now,
updated_at=now,
)
async with self._sf() as session:
session.add(row)
await session.commit()
return await self.get_session(row.id, user_id=None) # type: ignore[arg-type]
async def get_session(
self, session_id: str, *, user_id: str | None = "REQUIRED"
) -> dict[str, Any] | None:
"""Read one session.
``user_id`` scoping:
- ``"REQUIRED"`` (default): enforce owner scope — returns ``None`` if the
session is missing **or** owned by another user.
- ``None``: bypass owner scope (admin / internal path) — returns the
row regardless of owner.
"""
async with self._sf() as session:
stmt = select(MafRoundtableSessionRow).where(MafRoundtableSessionRow.id == session_id).limit(1)
row = (await session.execute(stmt)).scalars().first()
if row is None:
return None
if user_id is not None and row.user_id != user_id:
return None
return _to_dict(row)
async def list_sessions(
self,
*,
user_id: str | None = None,
status: str | None = None,
mode: str | None = None,
limit: int = 100,
offset: int = 0,
) -> list[dict[str, Any]]:
"""List sessions, newest-first.
``user_id=None`` lists across all users (admin / diagnostic). Otherwise
scoped to the caller. ``status`` / ``mode`` are optional filters.
"""
stmt = select(MafRoundtableSessionRow)
if user_id is not None:
stmt = stmt.where(MafRoundtableSessionRow.user_id == user_id)
if status is not None:
stmt = stmt.where(MafRoundtableSessionRow.status == status)
if mode is not None:
stmt = stmt.where(MafRoundtableSessionRow.mode == mode)
stmt = stmt.order_by(MafRoundtableSessionRow.created_at.desc()).limit(limit).offset(offset)
async with self._sf() as session:
rows = (await session.execute(stmt)).scalars().all()
return [_to_dict(r) for r in rows]
async def count_sessions(
self, *, user_id: str | None = None, status: str | None = None, mode: str | None = None
) -> int:
stmt = select(func.count()).select_from(MafRoundtableSessionRow)
if user_id is not None:
stmt = stmt.where(MafRoundtableSessionRow.user_id == user_id)
if status is not None:
stmt = stmt.where(MafRoundtableSessionRow.status == status)
if mode is not None:
stmt = stmt.where(MafRoundtableSessionRow.mode == mode)
async with self._sf() as session:
return int((await session.execute(stmt)).scalar_one())
async def update_session(
self, session_id: str, *, user_id: str | None, fields: dict[str, Any]
) -> dict[str, Any] | None:
"""Partial update. Only allowed when the session is not yet ``running``
(enforced by the service layer). ``capability_snapshot`` is **never**
mutated here — it is frozen at creation. Returns ``None`` if the session
is missing or owned by another user.
"""
async with self._sf() as session:
stmt = select(MafRoundtableSessionRow).where(MafRoundtableSessionRow.id == session_id).limit(1)
row = (await session.execute(stmt)).scalars().first()
if row is None:
return None
if user_id is not None and row.user_id != user_id:
return None
for key in ("title", "task_text", "task_payload", "mode", "status", "model_name",
"reasoning_effort", "manager_agent_id", "max_rounds", "write_policy",
"fact_ledger", "final_result"):
if key in fields:
value = fields[key]
col = {
"task_payload": "task_payload_json",
"capability_snapshot": "capability_snapshot_json",
"fact_ledger": "fact_ledger_json",
"final_result": "final_result_json",
}.get(key, key)
setattr(row, col, value)
row.updated_at = _now()
await session.commit()
return _to_dict(row)
async def delete_session(self, session_id: str, *, user_id: str | None) -> bool:
"""Delete a session (and its children via FK CASCADE). Returns ``True``
if a row was deleted, ``False`` if missing or owned by another user.
"""
async with self._sf() as session:
stmt = select(MafRoundtableSessionRow).where(MafRoundtableSessionRow.id == session_id).limit(1)
row = (await session.execute(stmt)).scalars().first()
if row is None:
return False
if user_id is not None and row.user_id != user_id:
return False
await session.execute(
delete(MafRoundtableSessionRow).where(MafRoundtableSessionRow.id == session_id)
)
await session.commit()
return True
async def set_status(self, session_id: str, status: str) -> None:
"""Internal: update only the status column (used by the run lifecycle)."""
async with self._sf() as session:
await session.execute(
update(MafRoundtableSessionRow)
.where(MafRoundtableSessionRow.id == session_id)
.values(status=status, updated_at=_now())
)
await session.commit()
@@ -0,0 +1,192 @@
"""Facade combining all six MAF roundtable repositories into one store.
The router / service layer talks to this facade rather than the individual
repositories, so the wiring in ``deps.py`` is a single ``app.state.maf_roundtable_store``.
The facade also enforces the cross-repo invariant that an event / action /
approval's ``session_id`` must belong to a session the caller owns (or admin
bypass) — the individual repos are session-id-agnostic and trust the caller.
Cross-table atomic operations (e.g. claim session + create run, cancel run +
repair session) live here so they share a single ``AsyncSession`` / transaction
— individual repos each open their own session and cannot participate in one
another's transactions.
"""
from __future__ import annotations
from datetime import UTC, datetime
from typing import Any
from uuid import uuid4
from sqlalchemy import select, update
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from deerflow.persistence.maf_roundtable.actions import MafActionRepository
from deerflow.persistence.maf_roundtable.approvals import MafApprovalRepository
from deerflow.persistence.maf_roundtable.events import MafEventRepository
from deerflow.persistence.maf_roundtable.model import MafRoundtableRunRow, MafRoundtableSessionRow
from deerflow.persistence.maf_roundtable.participants import MafParticipantRepository
from deerflow.persistence.maf_roundtable.runs import MafRunRepository, run_to_dict
from deerflow.persistence.maf_roundtable.sessions import MafSessionRepository
# Session statuses that mean a run is in flight — the CAS claim refuses these.
_ACTIVE_SESSION_STATUSES = ("starting", "running", "waiting_approval", "waiting_input")
# Run statuses that are still in flight (cancellable).
_ACTIVE_RUN_STATUSES = ("pending", "running", "waiting_approval", "waiting_input")
# Run statuses that are terminal (cannot be re-cancelled).
_TERMINAL_RUN_STATUSES = ("completed", "failed", "cancelled")
def _now() -> datetime:
return datetime.now(UTC)
class MafRoundtableStore:
"""Combined MAF roundtable persistence facade.
Each sub-repo is independently constructed from the same session factory
so they share the engine / pool. The facade exposes them as attributes so
the service layer can do ``store.sessions.create_session(...)`` etc.
"""
def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
self._sf = session_factory
self.sessions = MafSessionRepository(session_factory)
self.participants = MafParticipantRepository(session_factory)
self.runs = MafRunRepository(session_factory)
self.events = MafEventRepository(session_factory, run_repo=self.runs)
self.actions = MafActionRepository(session_factory)
self.approvals = MafApprovalRepository(session_factory)
@property
def session_factory(self) -> async_sessionmaker[AsyncSession]:
return self._sf
async def claim_and_create_pending_run(
self,
*,
session_id: str,
owner_user_id: str,
workflow_version: str | None = None,
) -> dict[str, Any] | None:
"""Atomically claim a session and create a ``pending`` run in one transaction.
Single ``AsyncSession`` + ``begin()``:
1. Conditional UPDATE: set ``status='running'`` only when the session
matches ``id`` + ``user_id`` and is not already active.
2. If ``rowcount != 1``, return ``None`` (caller maps to 404/403/409) —
no run is inserted.
3. Insert a ``pending`` run, ``flush`` to materialise the id, commit.
Any exception during insert / flush / commit rolls the whole transaction
back — the session never stays in a half-claimed ``starting`` state
(we never write ``starting``; the claim lands directly on ``running``).
Concurrent callers are serialised by the database UPDATE.
"""
now = _now()
async with self._sf() as db:
async with db.begin():
result = await db.execute(
update(MafRoundtableSessionRow)
.where(
MafRoundtableSessionRow.id == session_id,
MafRoundtableSessionRow.user_id == owner_user_id,
MafRoundtableSessionRow.status.notin_(_ACTIVE_SESSION_STATUSES),
)
.values(status="running", updated_at=now)
)
if result.rowcount != 1: # type: ignore[union-attr]
# Claim lost or session missing/wrong-owner — no run created.
return None
run_row = MafRoundtableRunRow(
id=uuid4().hex,
session_id=session_id,
status="pending",
workflow_version=workflow_version,
started_at=None, # pending = queued, not yet handed to executor
created_at=now,
updated_at=now,
)
db.add(run_row)
await db.flush()
# Build the dict before the transaction exits (expire-on-commit
# would otherwise wipe attributes after commit).
return run_to_dict(run_row)
async def cancel_run_atomically(
self,
*,
run_id: str,
owner_user_id: str,
) -> dict[str, Any] | None:
"""Atomically cancel a run and reconcile its session in one transaction.
Single ``AsyncSession`` + ``begin()``:
1. SELECT run JOIN session WHERE ``run.id`` + ``session.user_id``
(``with_for_update`` on PG/MySQL; SQLite accepts the no-op lock).
2. Run missing or not owned → return ``None`` (no writes).
3. Active run (``pending``/``running``/``waiting_*``): set run to
``cancelled`` + ``finished_at``, session to ``cancelled``.
4. Already-``cancelled`` run: repair session if still active
(fixes historical half-completed data).
5. Terminal run (``completed``/``failed``): do NOT change the run;
repair session to the run's terminal state only if session is
still active (never overwrite an already-terminal session).
6. Flush + commit; any exception rolls both run and session back.
"""
now = _now()
async with self._sf() as db:
async with db.begin():
stmt = (
select(MafRoundtableRunRow, MafRoundtableSessionRow)
.join(
MafRoundtableSessionRow,
MafRoundtableRunRow.session_id == MafRoundtableSessionRow.id,
)
.where(
MafRoundtableRunRow.id == run_id,
MafRoundtableSessionRow.user_id == owner_user_id,
)
.with_for_update()
)
row = (await db.execute(stmt)).first()
if row is None:
return None
run_row, session_row = row
if run_row.status in _ACTIVE_RUN_STATUSES:
# Normal cancel: run + session → cancelled.
run_row.status = "cancelled"
run_row.finished_at = now
run_row.updated_at = now
session_row.status = "cancelled"
session_row.updated_at = now
elif run_row.status == "cancelled":
# Already cancelled — repair session if still active.
if session_row.status in _ACTIVE_SESSION_STATUSES:
session_row.status = "cancelled"
session_row.updated_at = now
else:
# completed / failed — do NOT change the run's status.
# Repair session only if it is still active.
if session_row.status in _ACTIVE_SESSION_STATUSES:
session_row.status = run_row.status
session_row.updated_at = now
await db.flush()
return run_to_dict(run_row)
__all__ = [
"MafActionRepository",
"MafApprovalRepository",
"MafEventRepository",
"MafParticipantRepository",
"MafRoundtableStore",
"MafRunRepository",
"MafSessionRepository",
]
@@ -42,6 +42,14 @@ from deerflow.persistence.embed_sessions.model import EmbedSessionRow
from deerflow.persistence.feedback.model import FeedbackRow
from deerflow.persistence.light_apps.model import LightAppRow
from deerflow.persistence.llm_metrics.model import LlmCallMetricRow
from deerflow.persistence.maf_roundtable.model import (
MafRoundtableActionRow,
MafRoundtableApprovalRow,
MafRoundtableEventRow,
MafRoundtableParticipantRow,
MafRoundtableRunRow,
MafRoundtableSessionRow,
)
from deerflow.persistence.memory_config.model import UserMemoryConfigRow
from deerflow.persistence.menu_overrides.model import MenuOverrideRow
from deerflow.persistence.models.run_event import RunEventRow
@@ -108,6 +116,12 @@ __all__ = [
"KnowledgeTagRow",
"LightAppRow",
"LlmCallMetricRow",
"MafRoundtableActionRow",
"MafRoundtableApprovalRow",
"MafRoundtableEventRow",
"MafRoundtableParticipantRow",
"MafRoundtableRunRow",
"MafRoundtableSessionRow",
"MenuOverrideRow",
"NotificationRow",
"ParallelAgentTaskRow",