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:
1 parent
a0a75a9964
commit
e690475e6e
27 files changed
+5369
-101
No files matched your search
+290
@@ -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",
|
||||
]
|
||||
Reference in new issue
Block a user