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

@@ -30,11 +30,15 @@ reserved / not-yet-executing state) rather than pretending to be ``running``.
from __future__ import annotations
import logging
from typing import Any
from app.maf_roundtable.sanitize import sanitize, sanitize_payload
from deerflow.config.maf_roundtable_config import MafRoundtableConfig
from deerflow.persistence.maf_roundtable.store import MafRoundtableStore
logger = logging.getLogger(__name__)
class MafDisabledError(RuntimeError):
"""Raised when a write is attempted while the feature flag is off."""
@@ -64,11 +68,67 @@ class MafForbiddenError(PermissionError):
self.ident = ident
class MafConfigurationError(RuntimeError):
"""MAF is enabled but a required safety prerequisite is missing.
Raised by :func:`validate_maf_prerequisites` on the startup path so the
feature can never come up in a half-safe state ("MAF on, approval guard not
mounted"). The gateway lifespan catches this and forces the feature OFF
(clearly logged) rather than aborting the whole (experimental, opt-in)
service.
"""
def validate_maf_prerequisites() -> None:
"""Fail loudly if MAF is enabled without its full safety stack in place.
Checks, in order:
1. ``write_guard.enabled`` is true (the approval guard is mounted);
2. ``write_guard.provider`` is complete (``policy_use`` + ``interceptor_use``);
3. the bridge factories actually resolve (the app-layer guard is importable);
4. ``MAF_ACTION_SECRET_KEY`` is set (action params are encrypted with it).
Raises ``MafConfigurationError`` on the first unmet condition. Callers on
the startup path treat that as "force the feature off"; direct unit-test
construction of :class:`MafRoundtableService` does NOT call this.
"""
import os
from deerflow.config.write_guard_config import get_write_guard_config
from deerflow.reflection import resolve_variable
wg = get_write_guard_config()
if not wg.enabled:
raise MafConfigurationError(
"maf_roundtable.enabled=true requires write_guard.enabled=true "
"(the approval guard must be mounted)"
)
provider = wg.provider
if provider is None or not provider.policy_use or not provider.interceptor_use:
raise MafConfigurationError(
"maf_roundtable.enabled=true requires a complete write_guard.provider "
"(policy_use + interceptor_use)"
)
try:
resolve_variable(provider.policy_use)
resolve_variable(provider.interceptor_use)
except Exception as exc: # noqa: BLE001
raise MafConfigurationError(
f"write_guard bridge factories are not resolvable: {exc}"
) from exc
if not (os.getenv("MAF_ACTION_SECRET_KEY") or "").strip():
raise MafConfigurationError(
"maf_roundtable.enabled=true requires the MAF_ACTION_SECRET_KEY env var"
)
# 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"}
# ``cancel_failed`` blocks edits because the cancel cascade is incomplete and
# the may still have active sub-runs.
_RUNNING_STATUSES = {"starting", "running", "waiting_approval", "waiting_input", "cancelling", "cancel_failed"}
class MafRoundtableService:
@@ -79,14 +139,37 @@ class MafRoundtableService:
enabled: bool,
admin_diagnostic_access: bool,
config: MafRoundtableConfig | None = None,
agent_store: Any | None = None,
app_config: Any | None = None,
) -> None:
self._store = store
self._enabled = enabled
self._admin_diagnostic_access = admin_diagnostic_access
self._agent_store = agent_store
self._app_config = app_config
# 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()
# Startup validation: if the MAF feature is enabled, the
# ``MAF_ACTION_SECRET_KEY`` env var MUST be set — external-write
# action params are encrypted with it and there is no default key.
# A missing key forces the feature off (write paths then return 503)
# rather than running with a publicly-known key. This never aborts
# Gateway startup (the feature is experimental / opt-in).
if enabled:
import os
key = os.getenv("MAF_ACTION_SECRET_KEY", "")
if not key or not key.strip():
logger.error(
"[maf-roundtable] MAF_ACTION_SECRET_KEY is not set — "
"disabling the feature (write paths will return 503). "
"Set a 32+ char random string before enabling "
"maf_roundtable.enabled."
)
enabled = False
self._enabled = enabled
@property
def store(self) -> MafRoundtableStore:
return self._store
@@ -132,8 +215,52 @@ class MafRoundtableService:
) -> 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.
from app.maf_roundtable.capability_snapshot import (
AgentNotAccessibleError,
InvalidExcludedToolsError,
build_trusted_capability_snapshot,
seat_snapshot_for_agent,
)
from deerflow.config import get_app_config
app_config = self._app_config or get_app_config()
raw_participants = list(body.get("participants") or [])
# Strip any client-supplied snapshot / tool metadata — never trusted.
participants: list[dict[str, Any]] = []
for p in raw_participants:
participants.append(
{
"agent_id": p.get("agent_id"),
"display_name": p.get("display_name", ""),
"role": p.get("role", "seat"),
"sort_order": p.get("sort_order", 0),
"thread_id": p.get("thread_id"),
"excluded_tools": p.get("excluded_tools") or [],
}
)
try:
trusted_snapshot = await build_trusted_capability_snapshot(
user_id=user_id,
participants=participants,
app_config=app_config,
agent_store=self._agent_store,
session_model_name=body.get("model_name"),
session_reasoning_effort=body.get("reasoning_effort"),
session_excluded_tools=body.get("excluded_tools"),
)
except AgentNotAccessibleError as exc:
raise MafForbiddenError("agent", exc.agent_id) from exc
except InvalidExcludedToolsError as exc:
raise MafConflictError(
f"excluded_tools not allowed for agent {exc.agent_id}: {exc.tools}"
) from exc
for p in participants:
aid = p.get("agent_id")
if aid:
p["capability_snapshot"] = seat_snapshot_for_agent(trusted_snapshot, str(aid))
session_data: dict[str, Any] = {
"user_id": user_id,
"title": body.get("title", ""),
@@ -146,10 +273,9 @@ class MafRoundtableService:
"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"),
"capability_snapshot": trusted_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)
@@ -287,6 +413,76 @@ class MafRoundtableService:
raise MafForbiddenError("run", run_id)
raise MafNotFoundError("run", run_id)
async def start_cancel(self, *, run_id: str, user_id: str | None, is_admin: bool = False) -> dict[str, Any]:
"""Phase 1 of two-phase cancel: atomically set run+session to ``cancelling``.
The caller (router) then calls ``dispatcher.cancel(run_id)`` to
cascade to DeerFlow, then calls ``cancel_run`` to finalize to
``cancelled``.
"""
self._require_enabled()
if not user_id:
raise MafNotFoundError("run", run_id)
result = await self._store.start_cancel_atomically(run_id=run_id, owner_user_id=user_id)
if result is not None:
return result
# Classify the miss.
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)
async def finalize_cancel(self, *, run_id: str, user_id: str | None, is_admin: bool = False) -> dict[str, Any]:
"""Phase 2 of two-phase cancel: finalize ``cancelling`` → ``cancelled``."""
return await self.cancel_run(run_id=run_id, user_id=user_id, is_admin=is_admin)
async def mark_cancel_failed(
self,
*,
run_id: str,
user_id: str | None,
is_admin: bool = False,
reason: str = "",
) -> dict[str, Any]:
"""Mark a cancelling run as ``cancel_failed`` (non-terminal).
Used when the dispatcher's cancel cascade could not confirm all
DeerFlow sub-runs were cancelled. The run AND session both enter
``cancel_failed`` atomically so their statuses never diverge.
The user can retry cancel later — ``cancel_run_atomically``
accepts ``cancel_failed`` as a valid input state.
A failed cancel must NEVER masquerade as ``cancelled``.
"""
self._require_enabled()
if not user_id:
raise MafNotFoundError("run", run_id)
scope = self._write_scope_user(user_id, is_admin)
run = await self._store.runs.get_run(run_id)
if run is None:
raise MafNotFoundError("run", run_id)
# Owner (or admin) check.
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)
safe_reason = str(sanitize(reason))[:500] if reason else "one or more sub-runs could not be cancelled"
updated = await self._store.mark_cancel_failed_atomically(
run_id=run_id,
owner_user_id=user_id,
error_code="CancelCascadeIncomplete",
error_message=safe_reason,
)
if updated is None:
raise MafNotFoundError("run", run_id)
return updated
# ── events ─────────────────────────────────────────────────────────────
async def append_event(
@@ -298,6 +494,7 @@ class MafRoundtableService:
agent_id: str | None = None,
turn_index: int | None = None,
payload: dict[str, Any] | None = None,
source_event_id: str | None = None,
is_admin: bool = False,
) -> dict[str, Any]:
"""Append an event to a run's stream (internal / executor only).
@@ -324,7 +521,8 @@ class MafRoundtableService:
event_type=event_type,
agent_id=agent_id,
turn_index=turn_index,
payload=payload,
payload=sanitize_payload(payload),
source_event_id=source_event_id,
)
async def list_events(