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