feat(maf): Phase 5 - action coordinator, approval flow, frontend MAF roundtable pages

- Backend: action_coordinator, capability_snapshot, event_normalizer, tool_executor updates
- Backend: approved_tool_executor with write guard, action leases, migration script
- Frontend: maf-roundtable module (API client, event timeline, approval cards, fact flow panel)
- Frontend: MafRoutes, MafSessionsPage, MafRunDetailPage
- Tests: action_leases, migration_phase5, phase5_entry_e2e, real_write_e2e/http_e2e
- Docs: update implementation plan

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
董宏凯andCursor committed 2026-08-02 13:07:21 +08:00
1 parent 21c4c898e7
commit f82363d81f
55 files changed
+6304 -167

No files matched your search

@@ -79,6 +79,56 @@ class MafConfigurationError(RuntimeError):
"""
def get_maf_write_guard_readiness(*, app_config: Any | None = None) -> dict[str, Any]:
"""Return non-sensitive WriteGuard readiness information for MAF health.
A missing secret intentionally does not disable read-only MAF work:
WriteGuard fails closed before any external write can execute. ``ready``
is therefore the signal that the complete approval + encryption path is
usable, while ``enabled`` describes whether the middleware is mounted.
"""
import os
from deerflow.config.write_guard_config import get_write_guard_config
from deerflow.reflection import resolve_variable
wg = getattr(app_config, "write_guard", None) if app_config is not None else None
if wg is None:
wg = get_write_guard_config()
provider = getattr(wg, "provider", None)
provider_configured = bool(
provider
and getattr(provider, "policy_use", "")
and getattr(provider, "interceptor_use", "")
)
bridge_resolvable = False
if provider_configured:
try:
resolve_variable(provider.policy_use)
resolve_variable(provider.interceptor_use)
bridge_resolvable = True
except Exception: # noqa: BLE001 - health must remain safe and non-fatal
bridge_resolvable = False
secret_configured = bool((os.getenv("MAF_ACTION_SECRET_KEY") or "").strip())
if not getattr(wg, "enabled", False):
status = "disabled"
elif not provider_configured or not bridge_resolvable:
status = "provider_unavailable"
elif not secret_configured:
status = "missing_secret"
else:
status = "ready"
return {
"enabled": bool(getattr(wg, "enabled", False)),
"ready": status == "ready",
"secret_configured": secret_configured,
"status": status,
}
def validate_maf_prerequisites() -> None:
"""Fail loudly if MAF is enabled without its full safety stack in place.
@@ -86,14 +136,13 @@ def validate_maf_prerequisites() -> None:
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).
4. secret readiness is reported separately; a missing secret must not
disable read-only MAF work, while writes fail closed before execution.
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
@@ -116,10 +165,6 @@ def validate_maf_prerequisites() -> None:
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).
@@ -150,24 +195,10 @@ class MafRoundtableService:
# 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
# A missing MAF_ACTION_SECRET_KEY does not disable read-only MAF
# operation. The action coordinator raises before creating or
# executing an external-write action, so writes fail closed until the
# deployment injects the secret through the environment.
self._enabled = enabled
@property
@@ -539,10 +570,17 @@ class MafRoundtableService:
async def list_actions(
self, *, run_id: str, user_id: str | None, is_admin: bool = False
) -> list[dict[str, Any]]:
from deerflow.persistence.maf_roundtable.actions import action_to_public_dict
run = await self.get_run(run_id=run_id, user_id=user_id, is_admin=is_admin)
return await self._store.actions.list_actions(run_id=run["id"])
return [
action_to_public_dict(action)
for action in await self._store.actions.list_actions(run_id=run["id"])
]
async def get_action(self, *, action_id: str, user_id: str | None, is_admin: bool = False) -> dict[str, Any]:
from deerflow.persistence.maf_roundtable.actions import action_to_public_dict
action = await self._store.actions.get_action(action_id)
if action is None:
raise MafNotFoundError("action", action_id)
@@ -550,7 +588,7 @@ class MafRoundtableService:
session = await self._store.sessions.get_session(action["session_id"], user_id=scope)
if session is None:
raise MafNotFoundError("action", action_id)
return action
return action_to_public_dict(action)
# ── approvals ──────────────────────────────────────────────────────────
@@ -558,6 +596,8 @@ class MafRoundtableService:
self, *, run_id: str, user_id: str | None, is_admin: bool = False
) -> list[dict[str, Any]]:
run = await self.get_run(run_id=run_id, user_id=user_id, is_admin=is_admin)
# Reads are observational. Expiry is performed by the dedicated
# scanner; decision/resume paths retain the fail-closed pre-CAS check.
return await self._store.approvals.list_approvals(run_id=run["id"])
async def decide_approval(
@@ -579,6 +619,11 @@ class MafRoundtableService:
if is_admin and await self._store.sessions.get_session(approval["session_id"], user_id=None) is not None:
raise MafForbiddenError("approval", approval_id)
raise MafNotFoundError("approval", approval_id)
# The timeout transition is server-owned and happens before the
# decision CAS, so an expired approval can never be revived by a late
# browser request.
if approval.get("run_id"):
await self._store.expire_due_approvals(run_id=approval["run_id"])
try:
updated = await self._store.approvals.decide(approval_id, decision=decision, decided_by=user_id)
except ValueError as exc: