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

@@ -0,0 +1,390 @@
"""Service layer for the MAF roundtable experiment.
Enforces the cross-cutting policies the individual repositories don't:
- **User isolation (MAF-01-07)**: every read / write is scoped to the caller's
``user_id``. Read and write scopes are deliberately **separate**:
``admin_diagnostic_access`` only widens the *read* scope (cross-user
diagnostics) — it never grants cross-user *writes*. Every mutating operation
(update / delete session, start / cancel run, append event, decide approval)
is owner-checked via ``_write_scope_user`` regardless of the diagnostic flag.
- **Run gating + atomic launch**: a session may have at most one active run
(``starting`` / ``running`` / ``waiting_*``). The launch is a **single
database transaction** (``store.claim_and_create_pending_run``) that
conditionally updates the session to ``running`` and inserts a ``pending``
run together — not a multi-step claim/create/set_status dance, and not a
Python lock. Concurrent callers cannot both win; a mid-transaction failure
rolls everything back so the session never sticks in a half-claimed state.
- **Feature flag**: when ``maf_roundtable.enabled`` is off, write paths raise
``MafDisabledError`` (the router maps it to 503); reads stay open so admins
can review history.
- **Config-driven defaults**: ``mode`` / ``write_policy`` / ``max_rounds``
default to the deployed ``MafRoundtableConfig`` values when the create
request omits them; an explicit request value always wins.
The service does **not** load the MAF SDK — that is Phase 2+ (the
``DeerFlowAgentAdapter``). Phase 1 ships the persistence + API skeleton; until
a real executor exists, a launched run is parked in ``pending`` (clearly a
reserved / not-yet-executing state) rather than pretending to be ``running``.
"""
from __future__ import annotations
from typing import Any
from deerflow.config.maf_roundtable_config import MafRoundtableConfig
from deerflow.persistence.maf_roundtable.store import MafRoundtableStore
class MafDisabledError(RuntimeError):
"""Raised when a write is attempted while the feature flag is off."""
class MafNotFoundError(KeyError):
"""Raised when a session / run / action / approval is missing or out of scope."""
def __init__(self, what: str, ident: str) -> None:
super().__init__(f"{what} not found or out of scope: {ident}")
self.what = what
self.ident = ident
class MafConflictError(RuntimeError):
"""Raised when a session is in a state that rejects the requested edit."""
class MafForbiddenError(PermissionError):
"""Raised when a caller is authenticated but not the owner of the target
resource (e.g. an admin trying to *write* another user's session while
only holding cross-user *read* via the diagnostic flag)."""
def __init__(self, what: str, ident: str) -> None:
super().__init__(f"not the owner of {what}: {ident}")
self.what = what
self.ident = ident
# Session statuses that may be edited (config changes).
_EDITABLE_STATUSES = {"draft", "completed", "failed", "cancelled"}
# Session statuses that mean a run is in flight (no config edits). ``starting``
# is the transient CAS-claim state between "claimed" and "run row created".
_RUNNING_STATUSES = {"starting", "running", "waiting_approval", "waiting_input"}
class MafRoundtableService:
def __init__(
self,
store: MafRoundtableStore,
*,
enabled: bool,
admin_diagnostic_access: bool,
config: MafRoundtableConfig | None = None,
) -> None:
self._store = store
self._enabled = enabled
self._admin_diagnostic_access = admin_diagnostic_access
# Defaults source for create_session; falls back to the pydantic
# defaults when no config is injected (keeps unit tests lightweight).
self._config = config or MafRoundtableConfig()
@property
def store(self) -> MafRoundtableStore:
return self._store
@property
def enabled(self) -> bool:
return self._enabled
@property
def config(self) -> MafRoundtableConfig:
return self._config
def _require_enabled(self) -> None:
if not self._enabled:
raise MafDisabledError("MAF roundtable feature is disabled")
# ── permission scopes ──────────────────────────────────────────────────
def _read_scope_user(self, user_id: str | None, is_admin: bool) -> str | None:
"""User id to scope **read** queries by.
- Admin with diagnostic access: ``None`` (cross-user read for diagnostics).
- Anyone else: their own ``user_id`` (enforced).
"""
if is_admin and self._admin_diagnostic_access:
return None
return user_id
def _write_scope_user(self, user_id: str | None, is_admin: bool) -> str | None:
"""User id to scope **write** operations by.
The diagnostic flag is read-only — it never widens the write scope.
Every mutating operation is owner-checked against the caller's own
``user_id`` (admin or not). A future explicit operator/admin force-stop
would be a separate, audited code path, not a reuse of this flag.
"""
return user_id
# ── sessions ──────────────────────────────────────────────────────────
async def create_session(
self, *, user_id: str, body: dict[str, Any], is_admin: bool = False
) -> dict[str, Any]:
self._require_enabled()
cfg = self._config
# Config-driven defaults: an omitted field falls back to the deployed
# MafRoundtableConfig value; an explicit request value always wins.
session_data: dict[str, Any] = {
"user_id": user_id,
"title": body.get("title", ""),
"task_text": body["task_text"],
"task_payload": body.get("task_payload"),
"mode": body.get("mode") or cfg.default_mode,
"status": "draft",
"model_name": body.get("model_name"),
"reasoning_effort": body.get("reasoning_effort"),
"manager_agent_id": body.get("manager_agent_id"),
"max_rounds": body.get("max_rounds") if body.get("max_rounds") is not None else cfg.default_max_rounds,
"write_policy": body.get("write_policy") or cfg.default_write_policy,
"capability_snapshot": body.get("capability_snapshot"),
}
session = await self._store.sessions.create_session(session_data)
participants = body.get("participants") or []
if participants:
await self._store.participants.replace_participants(session["id"], participants)
return await self.get_session(session_id=session["id"], user_id=user_id, is_admin=is_admin)
async def get_session(self, *, session_id: str, user_id: str | None, is_admin: bool = False) -> dict[str, Any]:
scope = self._read_scope_user(user_id, is_admin)
session = await self._store.sessions.get_session(session_id, user_id=scope)
if session is None:
raise MafNotFoundError("session", session_id)
participants = await self._store.participants.list_participants(session_id)
session["participants"] = participants
return session
async def list_sessions(
self,
*,
user_id: str | None,
is_admin: bool = False,
status: str | None = None,
mode: str | None = None,
limit: int = 100,
offset: int = 0,
) -> tuple[list[dict[str, Any]], int]:
scope = self._read_scope_user(user_id, is_admin)
rows = await self._store.sessions.list_sessions(
user_id=scope, status=status, mode=mode, limit=limit, offset=offset
)
total = await self._store.sessions.count_sessions(user_id=scope, status=status, mode=mode)
# Attach participants to each row (cheap — Phase 1 lists are bounded).
for row in rows:
row["participants"] = await self._store.participants.list_participants(row["id"])
return rows, total
async def update_session(
self, *, session_id: str, user_id: str | None, fields: dict[str, Any], is_admin: bool = False
) -> dict[str, Any]:
self._require_enabled()
# Writes are owner-scoped even for admins (diagnostic access is read-only).
scope = self._write_scope_user(user_id, is_admin)
existing = await self._store.sessions.get_session(session_id, user_id=scope)
if existing is None:
# Distinguish "missing" from "owned by someone else" so an admin
# (who can read cross-user) gets a clear 403 rather than a 404.
if is_admin and await self._store.sessions.get_session(session_id, user_id=None) is not None:
raise MafForbiddenError("session", session_id)
raise MafNotFoundError("session", session_id)
if existing["status"] in _RUNNING_STATUSES:
raise MafConflictError(
f"session {session_id} is running ({existing['status']}); config edits not allowed"
)
# capability_snapshot is frozen — never accept it on update.
fields.pop("capability_snapshot", None)
updated = await self._store.sessions.update_session(session_id, user_id=scope, fields=fields)
if updated is None:
raise MafNotFoundError("session", session_id)
if "participants" in fields and fields["participants"] is not None:
await self._store.participants.replace_participants(session_id, fields["participants"])
return await self.get_session(session_id=session_id, user_id=user_id, is_admin=is_admin)
async def delete_session(self, *, session_id: str, user_id: str | None, is_admin: bool = False) -> None:
self._require_enabled()
scope = self._write_scope_user(user_id, is_admin)
# Pre-check existence cross-user so an admin gets 403, not 404.
if await self._store.sessions.get_session(session_id, user_id=scope) is None:
if is_admin and await self._store.sessions.get_session(session_id, user_id=None) is not None:
raise MafForbiddenError("session", session_id)
raise MafNotFoundError("session", session_id)
ok = await self._store.sessions.delete_session(session_id, user_id=scope)
if not ok:
raise MafNotFoundError("session", session_id)
# ── runs ────────────────────────────────────────────────────────────────
async def create_run(
self, *, session_id: str, user_id: str | None, workflow_version: str | None = None, is_admin: bool = False
) -> dict[str, Any]:
self._require_enabled()
# Owner-only write: an admin cannot start another user's run. The
# owner_user_id also rides in the atomic SQL (not just this pre-check).
if not user_id:
raise MafNotFoundError("session", session_id)
run = await self._store.claim_and_create_pending_run(
session_id=session_id,
owner_user_id=user_id,
workflow_version=workflow_version,
)
if run is not None:
return run
# Classify the failed claim: missing / wrong-owner / already active.
any_session = await self._store.sessions.get_session(session_id, user_id=None)
if any_session is None:
raise MafNotFoundError("session", session_id)
if any_session["user_id"] != user_id:
if is_admin:
raise MafForbiddenError("session", session_id)
raise MafNotFoundError("session", session_id)
raise MafConflictError(
f"session {session_id} already has an active run; concurrent launch rejected"
)
async def get_run(self, *, run_id: str, user_id: str | None, is_admin: bool = False) -> dict[str, Any]:
run = await self._store.runs.get_run(run_id)
if run is None:
raise MafNotFoundError("run", run_id)
# Enforce session owner scope (read scope — admins may diagnose).
scope = self._read_scope_user(user_id, is_admin)
session = await self._store.sessions.get_session(run["session_id"], user_id=scope)
if session is None:
raise MafNotFoundError("run", run_id)
return run
async def list_runs(self, *, session_id: str, user_id: str | None, is_admin: bool = False) -> list[dict[str, Any]]:
scope = self._read_scope_user(user_id, is_admin)
session = await self._store.sessions.get_session(session_id, user_id=scope)
if session is None:
raise MafNotFoundError("session", session_id)
return await self._store.runs.list_runs(session_id)
async def cancel_run(self, *, run_id: str, user_id: str | None, is_admin: bool = False) -> dict[str, Any]:
self._require_enabled()
if not user_id:
raise MafNotFoundError("run", run_id)
result = await self._store.cancel_run_atomically(run_id=run_id, owner_user_id=user_id)
if result is not None:
return result
# Classify the miss: missing vs wrong-owner.
run = await self._store.runs.get_run(run_id)
if run is None:
raise MafNotFoundError("run", run_id)
if is_admin:
raise MafForbiddenError("run", run_id)
raise MafNotFoundError("run", run_id)
# ── events ─────────────────────────────────────────────────────────────
async def append_event(
self,
*,
run_id: str,
user_id: str | None,
event_type: str,
agent_id: str | None = None,
turn_index: int | None = None,
payload: dict[str, Any] | None = None,
is_admin: bool = False,
) -> dict[str, Any]:
"""Append an event to a run's stream (internal / executor only).
There is **no** public HTTP write endpoint for events — Phase-1 audit
integrity requires that only the backend Workflow executor (Phase 2+)
call this method. Frontend联调 mocks belong in tests / scripts, not in
a production-reachable route.
"""
self._require_enabled()
# Owner-only write: an admin cannot forge events into another user's run.
run = await self._store.runs.get_run(run_id)
if run is None:
raise MafNotFoundError("run", run_id)
scope = self._write_scope_user(user_id, is_admin)
session = await self._store.sessions.get_session(run["session_id"], user_id=scope)
if session is None:
if is_admin and await self._store.sessions.get_session(run["session_id"], user_id=None) is not None:
raise MafForbiddenError("run", run_id)
raise MafNotFoundError("run", run_id)
return await self._store.events.append_event(
session_id=run["session_id"],
run_id=run_id,
event_type=event_type,
agent_id=agent_id,
turn_index=turn_index,
payload=payload,
)
async def list_events(
self, *, run_id: str, user_id: str | None, after_seq: int = 0, limit: int = 1000, is_admin: bool = False
) -> tuple[list[dict[str, Any]], int]:
# get_run enforces owner read-scope (raises MafNotFoundError if out of scope).
await self.get_run(run_id=run_id, user_id=user_id, is_admin=is_admin)
events = await self._store.events.list_events(run_id, after_seq=after_seq, limit=limit)
latest = await self._store.events.latest_seq(run_id)
return events, latest
# ── actions ────────────────────────────────────────────────────────────
async def list_actions(
self, *, run_id: str, user_id: str | None, is_admin: bool = False
) -> list[dict[str, Any]]:
run = await self.get_run(run_id=run_id, user_id=user_id, is_admin=is_admin)
return await self._store.actions.list_actions(run_id=run["id"])
async def get_action(self, *, action_id: str, user_id: str | None, is_admin: bool = False) -> dict[str, Any]:
action = await self._store.actions.get_action(action_id)
if action is None:
raise MafNotFoundError("action", action_id)
scope = self._read_scope_user(user_id, is_admin)
session = await self._store.sessions.get_session(action["session_id"], user_id=scope)
if session is None:
raise MafNotFoundError("action", action_id)
return action
# ── approvals ──────────────────────────────────────────────────────────
async def list_approvals(
self, *, run_id: str, user_id: str | None, is_admin: bool = False
) -> list[dict[str, Any]]:
run = await self.get_run(run_id=run_id, user_id=user_id, is_admin=is_admin)
return await self._store.approvals.list_approvals(run_id=run["id"])
async def decide_approval(
self,
*,
approval_id: str,
decision: str,
user_id: str | None,
is_admin: bool = False,
) -> dict[str, Any]:
self._require_enabled()
approval = await self._store.approvals.get_approval(approval_id)
if approval is None:
raise MafNotFoundError("approval", approval_id)
# Owner-only write: an admin cannot decide another user's approval.
scope = self._write_scope_user(user_id, is_admin)
session = await self._store.sessions.get_session(approval["session_id"], user_id=scope)
if session is None:
if is_admin and await self._store.sessions.get_session(approval["session_id"], user_id=None) is not None:
raise MafForbiddenError("approval", approval_id)
raise MafNotFoundError("approval", approval_id)
try:
updated = await self._store.approvals.decide(approval_id, decision=decision, decided_by=user_id)
except ValueError as exc:
raise MafConflictError(str(exc)) from exc
if updated is None:
raise MafNotFoundError("approval", approval_id)
return updated