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>
291 lines
15 KiB
Python
291 lines
15 KiB
Python
"""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",
|
||
]
|