feat(maf): add secure roundtable workflow runtime

This commit is contained in:
董宏凯 committed 2026-08-01 17:51:53 +08:00
1 parent e690475e6e
commit bd4131b4e2
52 files changed
+10315 -96

No files matched your search

@@ -14,7 +14,7 @@ from datetime import UTC, datetime
from typing import Any
from uuid import uuid4
from sqlalchemy import select
from sqlalchemy import select, update
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from deerflow.persistence.maf_roundtable.model import MafRoundtableActionRow
@@ -24,7 +24,8 @@ def _now() -> datetime:
return datetime.now(UTC)
def _to_dict(row: MafRoundtableActionRow) -> dict[str, Any]:
def action_to_dict(row: MafRoundtableActionRow) -> dict[str, Any]:
"""Serialise an action ORM row to a plain dict (public — reused by the store facade)."""
return {
"id": row.id,
"session_id": row.session_id,
@@ -32,6 +33,7 @@ def _to_dict(row: MafRoundtableActionRow) -> dict[str, Any]:
"agent_id": row.agent_id,
"tool_name": row.tool_name,
"logical_action_id": row.logical_action_id,
"turn_index": row.turn_index,
"idempotency_key": row.idempotency_key,
"target_key": row.target_key,
"risk_level": row.risk_level,
@@ -48,6 +50,25 @@ def _to_dict(row: MafRoundtableActionRow) -> dict[str, Any]:
}
# Back-compat alias for internal callers that used the old private name.
_to_dict = action_to_dict
class MafActionStateMachineError(RuntimeError):
"""An action was claimed or transitioned from an unexpected state.
Raised when a claim loses the ``approved → running`` CAS and the row is in
a state that is neither ``running`` (in progress elsewhere) nor a recognized
terminal (``succeeded`` / ``failed`` / ``unknown`` / ``rejected``) — e.g.
still ``waiting_approval`` / ``pending`` — meaning the caller tried to
execute an action that was never properly approved.
"""
# Terminal statuses a failed claim may reflect back to the caller.
_TERMINAL_CLAIM_STATUSES = ("succeeded", "failed", "unknown", "rejected")
class MafActionRepository:
def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
self._sf = session_factory
@@ -65,6 +86,7 @@ class MafActionRepository:
agent_id=data.get("agent_id"),
tool_name=str(data["tool_name"]),
logical_action_id=data.get("logical_action_id"),
turn_index=data.get("turn_index"),
idempotency_key=str(data["idempotency_key"]),
target_key=data.get("target_key"),
risk_level=str(data.get("risk_level") or "R0"),
@@ -135,3 +157,131 @@ class MafActionRepository:
row.updated_at = _now()
await session.commit()
return _to_dict(row)
async def claim_for_execution(self, action_id: str) -> str:
"""Atomically transition an action from ``approved`` to ``running``.
Single conditional UPDATE — only the caller whose UPDATE affects
exactly one row wins the right to execute the external write. This
guarantees at-most-once execution even under concurrent ``resume()``
calls or retries after a restart.
Returns the effective claim status (callers must NOT treat a lost claim
as a blanket "skip"):
- ``"claimed"`` — won the CAS; the caller may execute.
- ``"in_progress"`` — another executor already moved it to ``running``.
- ``"succeeded"`` / ``"failed"`` / ``"unknown"`` / ``"rejected"`` — the
action is already in that terminal state.
Raises ``MafActionStateMachineError`` when the row is missing or in any
other state (e.g. still ``waiting_approval`` / ``pending``) — i.e. it was
never properly approved and must not be executed.
"""
now = _now()
async with self._sf() as session:
result = await session.execute(
update(MafRoundtableActionRow)
.where(
MafRoundtableActionRow.id == action_id,
MafRoundtableActionRow.status == "approved",
)
.values(status="running", started_at=now, updated_at=now)
)
await session.commit()
if result.rowcount == 1: # type: ignore[union-attr]
return "claimed"
# Lost the CAS (or never approved) — report the ACTUAL state.
current = await self.get_action(action_id)
if current is None:
raise MafActionStateMachineError(f"action {action_id} not found during claim")
status = current.get("status")
if status == "running":
return "in_progress"
if status in _TERMINAL_CLAIM_STATUSES:
return str(status)
raise MafActionStateMachineError(
f"action {action_id} cannot be claimed from state '{status}'"
)
async def mark_approved(self, action_id: str) -> bool:
"""Conditionally transition ``waiting_approval → approved``.
Returns True only if this call performed the transition (``rowcount==1``).
A concurrent decider or an already-terminal action yields False — the
caller must NOT overwrite a terminal state via a generic update.
"""
now = _now()
async with self._sf() as session:
result = await session.execute(
update(MafRoundtableActionRow)
.where(
MafRoundtableActionRow.id == action_id,
MafRoundtableActionRow.status == "waiting_approval",
)
.values(status="approved", updated_at=now)
)
await session.commit()
return result.rowcount == 1 # type: ignore[union-attr]
async def mark_rejected(self, action_id: str) -> bool:
"""Conditionally transition ``waiting_approval → rejected`` (+ finished_at).
Returns True only if this call performed the transition. Terminal states
are never overwritten.
"""
now = _now()
async with self._sf() as session:
result = await session.execute(
update(MafRoundtableActionRow)
.where(
MafRoundtableActionRow.id == action_id,
MafRoundtableActionRow.status == "waiting_approval",
)
.values(status="rejected", finished_at=now, updated_at=now)
)
await session.commit()
return result.rowcount == 1 # type: ignore[union-attr]
async def record_terminal_result(
self,
action_id: str,
*,
status: str,
result: dict[str, Any] | None = None,
external_object_id: str | None = None,
) -> dict[str, Any] | None:
"""Record the terminal outcome of an action execution.
State-machine constrained: only a ``running`` action may transition
to a terminal status (``succeeded`` / ``failed`` / ``unknown``).
A concurrent caller that lost the race (or a replay after restart)
finds the row already terminal and its UPDATE is a no-op
(``rowcount == 0``) — it must NOT overwrite the real result.
"""
if status not in ("succeeded", "failed", "unknown"):
raise ValueError(f"invalid action result status: {status}")
now = _now()
async with self._sf() as session:
result_q = await session.execute(
update(MafRoundtableActionRow)
.where(
MafRoundtableActionRow.id == action_id,
MafRoundtableActionRow.status == "running",
)
.values(
status=status,
result_redacted_json=result,
external_object_id=external_object_id,
finished_at=now,
updated_at=now,
)
)
await session.commit()
# Use rowcount instead of .returning() for cross-DB compatibility
# (SQLite, PostgreSQL, MySQL).
if result_q.rowcount != 1: # type: ignore[union-attr]
# Lost the race or not in running state — do not overwrite.
return None
return await self.get_action(action_id)