feat(maf): add secure roundtable workflow runtime
This commit is contained in:
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(
|
||||
|
||||
Reference in new issue
Block a user