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

@@ -328,13 +328,41 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
maf_admin_diag = (
bool(getattr(maf_cfg, "admin_diagnostic_access", True)) if maf_cfg is not None else True
)
# P0-4: when MAF is switched on, its full safety stack must be in
# place (write_guard mounted + provider complete + bridge resolvable
# + MAF_ACTION_SECRET_KEY set). If any prerequisite is missing the
# feature is forced OFF (clearly logged) — never "MAF on, approval
# guard not mounted". Reads stay open for admin history review.
if maf_enabled:
from app.maf_roundtable.service import (
MafConfigurationError,
validate_maf_prerequisites,
)
try:
validate_maf_prerequisites()
except MafConfigurationError as cfg_exc:
logger.error(
"[maf-roundtable] enabled but prerequisites unmet — "
"forcing the feature OFF: %s",
cfg_exc,
)
maf_enabled = False
if app.state.maf_roundtable_store is not None:
app.state.maf_roundtable_service = MafRoundtableService(
app.state.maf_roundtable_store,
enabled=maf_enabled,
admin_diagnostic_access=maf_admin_diag,
config=maf_cfg,
agent_store=getattr(app.state, "agent_store", None),
app_config=config,
)
# Wire the WriteGuard bridge so the harness middleware can reach
# the service when intercepting external-write tool calls.
if app.state.maf_roundtable_service is not None:
from app.maf_roundtable.write_guard_bridge import register_write_guard_service
register_write_guard_service(app.state.maf_roundtable_service)
else:
app.state.maf_roundtable_service = None
except Exception: # noqa: BLE001 — experimental feature must never abort startup
@@ -198,12 +198,31 @@ async def delete_session(request: Request, session_id: str) -> dict[str, Any]:
async def create_run(request: Request, session_id: str, body: CreateRunRequest) -> RunResponse:
svc = _require_service(request)
user_id, is_admin = _user_ctx(request)
# Check MAF SDK availability BEFORE creating the run — so the user gets a
# clean 503 rather than a run that will immediately fail.
from app.maf_roundtable.dispatcher import MafSdkNotAvailableError, get_dispatcher
dispatcher = get_dispatcher(request.app)
try:
dispatcher.check_sdk_available()
except MafSdkNotAvailableError as exc:
raise HTTPException(status_code=503, detail=str(exc)) from exc
try:
run = await svc.create_run(
session_id=session_id, user_id=user_id, workflow_version=body.workflow_version, is_admin=is_admin
)
except (MafDisabledError, MafForbiddenError, MafNotFoundError, MafConflictError) as exc:
raise _map_service_error(exc) from exc
# Launch the workflow in the background. The run is already persisted as
# "pending"; the dispatcher transitions it to "running" then completes/fails it.
# Auto-dispatch can be disabled (e.g. in tests) via app.state.maf_auto_dispatch=False.
if getattr(request.app.state, "maf_auto_dispatch", True):
session = await svc.get_session(session_id=session_id, user_id=user_id, is_admin=is_admin)
await dispatcher.dispatch(session, run, user_id=user_id or "default")
return RunResponse(**run)
@@ -233,11 +252,43 @@ async def get_run(request: Request, run_id: str) -> RunResponse:
async def cancel_run(request: Request, run_id: str) -> RunResponse:
svc = _require_service(request)
user_id, is_admin = _user_ctx(request)
# Phase 1: atomically set run+session to cancelling (not yet cancelled).
try:
run = await svc.cancel_run(run_id=run_id, user_id=user_id, is_admin=is_admin)
await svc.start_cancel(run_id=run_id, user_id=user_id, is_admin=is_admin)
except (MafDisabledError, MafForbiddenError, MafNotFoundError) as exc:
raise _map_service_error(exc) from exc
return RunResponse(**run)
# Phase 2: cascade cancel to the background task + DeerFlow sub-runs.
from app.maf_roundtable.dispatcher import get_dispatcher
dispatcher = get_dispatcher(request.app)
result = await dispatcher.cancel(run_id)
# Phase 3: finalize based on the structured cancel result.
# - all_cancelled → finalize to ``cancelled`` (terminal).
# - some sub-runs failed/still active → mark ``cancel_failed`` (non-terminal)
# so the failure is visible and retryable. A failed cancel must NEVER
# masquerade as cancelled.
try:
if result.get("all_cancelled"):
final_run = await svc.finalize_cancel(run_id=run_id, user_id=user_id, is_admin=is_admin)
else:
failed = result.get("failed_run_ids") or []
still_active = result.get("still_active_run_ids") or []
detail = []
if failed:
detail.append(f"{len(failed)} sub-run(s) failed to cancel")
if still_active:
detail.append(f"{len(still_active)} sub-run(s) had no DeerFlow run id")
reason = "; ".join(detail) or "cancel cascade incomplete"
final_run = await svc.mark_cancel_failed(
run_id=run_id, user_id=user_id, is_admin=is_admin, reason=reason
)
except (MafDisabledError, MafForbiddenError, MafNotFoundError) as exc:
raise _map_service_error(exc) from exc
return RunResponse(**final_run)
# ── events ─────────────────────────────────────────────────────────────────
@@ -310,4 +361,25 @@ async def decide_approval(request: Request, approval_id: str, body: ApprovalDeci
)
except (MafDisabledError, MafForbiddenError, MafNotFoundError, MafConflictError) as exc:
raise _map_service_error(exc) from exc
# P1: after a successful approval decision, resume the workflow from its
# checkpoint. Only the owner can resume (decide_approval already enforced
# owner-only write). The resume loads the checkpoint, restores
# RoundtableState.from_dict(), and executes the approved action (at-most-once).
run_id = approval.get("run_id")
if run_id and body.decision in ("approved", "rejected"):
from app.maf_roundtable.dispatcher import get_dispatcher
dispatcher = get_dispatcher(request.app)
try:
await dispatcher.resume(run_id, user_id=user_id or "default")
except Exception:
# Resume failure should not fail the approval response itself —
# the approval is already persisted. Log for observability.
import logging
logging.getLogger(__name__).exception(
"MAF resume failed for run %s after approval %s", run_id, approval_id
)
return ApprovalResponse(**approval)
@@ -0,0 +1,386 @@
"""Action Coordinator for the MAF roundtable experiment (Phase 2 P1).
Intercepts external-write tool calls **before** they reach the real external
system. The current problem (pre-fix) was that seats executed DeerFlow tools
first and the ApprovalGate only inspected ``tool_calls`` afterwards — too
late. The ActionCoordinator fixes this by:
1. **Classification**: reads per-tool risk metadata from the frozen
capability snapshot (``side_effect: read|write``, ``risk_level: R0–R4``).
Tools without metadata use a **safe default** (treated as write/R3 →
requires approval). Classification never relies on name-prefix heuristics
like ``create_`` / ``delete_``.
2. **Pre-execution interception (Phase-2)**: write tools are NO LONGER
excluded from the seat run — the model sees the full tool schema and can
propose writes. A harness-level ``WriteGuardMiddleware`` intercepts each
write tool call at ``wrap_tool_call``/``awrap_tool_call`` time (activated
per-run by a ``maf_run_id`` flag in the run context) and records a pending
action before the real tool ever runs. The AI's proposed call is turned
into an ``approval_required`` ToolMessage instead of the tool's real result.
3. **Post-turn capture**: after the seat turn, the seat executor reads the
run's ``tool_calls`` to surface the pending approval in workflow state so
the ApprovalGate can pause. Action creation itself happens inside the
WriteGuard interceptor (single transaction — see point 5).
For each intercepted write tool call, the coordinator creates — in a
**single logical transaction** (``store.create_pending_action_bundle``):
- an ``action`` row with idempotency key ``run_id:agent_id:turn_index:tool_call_id``
- the **sanitized** arguments (for audit / API visibility)
- the **encrypted** actual arguments (server-only, for restart recovery)
- an ``approval`` row (pending)
- an ``action.waiting_approval`` critical audit event
If the critical audit event write fails, the action stays **unexecuted**
— the external system is never called.
4. **Post-approval execution**: after the user approves:
- Only an ``approved`` ``action_id`` may re-enter the tool executor.
- Before execution, the action is atomically occupied (``approved → running``).
- A second entry for the same action returns the existing result or is
rejected — **never** a second write.
- Success → ``succeeded``, failure → ``failed``, network-unknown →
``unknown`` (``unknown`` prohibits auto-retry).
Encryption: uses ``cryptography.fernet.Fernet`` with a key derived from the
``MAF_ACTION_SECRET_KEY`` env var. There is **no default key** — the var is
required whenever the MAF feature is enabled (validated at startup). The
ciphertext is opaque to the store and is **never** returned from any API,
event, log, or frontend query.
"""
from __future__ import annotations
import base64
import hashlib
import logging
import os
from typing import Any
from app.maf_roundtable.sanitize import sanitize, sanitize_payload
logger = logging.getLogger(__name__)
# ── Risk classification ───────────────────────────────────────────────────
# Tools whose side_effect is explicitly "read" or "skill" are never intercepted.
# Everything else (including "unknown" / missing metadata) is treated as a
# potential write and subject to the write policy.
_SAFE_SIDE_EFFECTS = frozenset({"read", "skill"})
# Default risk level for tools without metadata — safe default requires approval.
_DEFAULT_RISK_LEVEL = "R3"
_DEFAULT_SIDE_EFFECT = "write"
def classify_tool(
tool_name: str,
capability_snapshot: dict[str, Any] | None,
agent_id: str | None = None,
) -> tuple[str, str]:
"""Classify a tool's side-effect and risk level from the capability snapshot.
Returns ``(side_effect, risk_level)``. Tools without explicit metadata
use a **safe default**: ``("write", "R3")`` — meaning they are treated as
high-risk writes requiring approval. This is intentional: we never guess
risk from the tool name.
"""
if not capability_snapshot:
return (_DEFAULT_SIDE_EFFECT, _DEFAULT_RISK_LEVEL)
tools = capability_snapshot.get("tools")
if isinstance(tools, list):
for t in tools:
if isinstance(t, dict) and t.get("name") == tool_name:
side = t.get("side_effect") or _DEFAULT_SIDE_EFFECT
risk = t.get("risk_level") or _DEFAULT_RISK_LEVEL
return (side, risk)
agents = capability_snapshot.get("agents")
if isinstance(agents, list) and agent_id:
for a in agents:
if isinstance(a, dict) and a.get("agent_id") == agent_id:
agent_tools = a.get("tools")
if isinstance(agent_tools, list):
for t in agent_tools:
if isinstance(t, dict) and t.get("name") == tool_name:
side = t.get("side_effect") or _DEFAULT_SIDE_EFFECT
risk = t.get("risk_level") or _DEFAULT_RISK_LEVEL
return (side, risk)
return (_DEFAULT_SIDE_EFFECT, _DEFAULT_RISK_LEVEL)
def tool_needs_approval(
tool_name: str,
write_policy: str,
capability_snapshot: dict[str, Any] | None,
agent_id: str | None = None,
) -> bool:
"""Determine whether a tool call needs approval before execution.
- ``auto``: no approval needed (but the tool is still classified for audit).
- ``confirm_high_risk``: approval needed for R3+ tools.
- ``confirm_all_writes``: approval needed for any write tool.
"""
if write_policy == "auto":
return False
side_effect, risk_level = classify_tool(tool_name, capability_snapshot, agent_id)
if side_effect in _SAFE_SIDE_EFFECTS:
return False
if write_policy == "confirm_all_writes":
return True
# confirm_high_risk: R3 and above
risk_order = {"R0": 0, "R1": 1, "R2": 2, "R3": 3, "R4": 4}
risk_val = risk_order.get(risk_level, 3)
return risk_val >= 3
# ── Encryption ─────────────────────────────────────────────────────────────
class MafActionSecretKeyError(RuntimeError):
"""Raised when ``MAF_ACTION_SECRET_KEY`` is missing or empty.
There is no default key: the env var is required whenever the MAF feature
is enabled (validated at startup). Using a baked-in default would let a
deployment silently encrypt all action params with a publicly-known key.
"""
class ActionSecretUnavailableError(RuntimeError):
"""The approved action's parameters cannot be produced — execution MUST fail.
Raised (instead of returning ``None``) whenever the server-only secret is
missing, cannot be decrypted, or does not decrypt to a JSON object. Callers
must treat this as a hard execution failure: record the action ``failed``,
fail the parent run, and NEVER invoke the tool — they must NOT coerce the
failure into empty params (``params or {}``) and execute anyway.
Carries a machine-readable ``reason`` (``missing`` / ``decrypt_failed`` /
``invalid_type``) and a ``detail`` that is always safe to log/persist — it
never contains the ciphertext, the key, or raw exception bodies.
"""
def __init__(self, action_id: str, reason: str, detail: str) -> None:
self.action_id = action_id
self.reason = reason
self.detail = detail
super().__init__(f"action secret unavailable for {action_id}: {reason} — {detail}")
def _get_fernet_key() -> bytes:
"""Derive a Fernet key from the ``MAF_ACTION_SECRET_KEY`` env var.
Raises ``MafActionSecretKeyError`` if the var is missing or empty — there
is deliberately **no default key**. Callers must ensure the var is set
before the MAF feature is used (the service validates this at startup).
"""
raw = os.getenv("MAF_ACTION_SECRET_KEY", "")
if not raw or not raw.strip():
raise MafActionSecretKeyError(
"MAF_ACTION_SECRET_KEY environment variable is not set. "
"It is required to encrypt external-write action parameters. "
"Set it (e.g. a 32+ char random string) before enabling "
"maf_roundtable.enabled."
)
digest = hashlib.sha256(raw.encode()).digest()
return base64.urlsafe_b64encode(digest)
def encrypt_params(params: dict[str, Any]) -> str:
"""Encrypt tool-call arguments for server-only storage."""
import json
from cryptography.fernet import Fernet
plaintext = json.dumps(params, ensure_ascii=False).encode()
return Fernet(_get_fernet_key()).encrypt(plaintext).decode()
def decrypt_params(ciphertext: str) -> dict[str, Any]:
"""Decrypt tool-call arguments at execution time (server-only)."""
import json
from cryptography.fernet import Fernet
plaintext = Fernet(_get_fernet_key()).decrypt(ciphertext.encode()).decode()
return json.loads(plaintext)
# ── Action Coordinator ────────────────────────────────────────────────────
class ActionCoordinator:
"""Manages the intercept-approve-execute lifecycle for external writes.
Used by the DeerFlowAgentAdapter and WorkflowRunner to:
- Determine which tools to exclude before a seat turn.
- Capture intercepted write tool calls after a seat turn.
- Create actions + approvals + audit events in one logical transaction.
- Atomically occupy an approved action for execution (at-most-once).
"""
def __init__(self, service: Any, *, user_id: str = "") -> None:
self._service = service
self._store = service.store
self._user_id = user_id
# ── Post-turn: capture intercepted write tool calls ──────────────────
async def intercept_write_tool_calls(
self,
*,
run_id: str,
session_id: str,
agent_id: str,
turn_index: int,
tool_calls: list[dict[str, Any]],
capability_snapshot: dict[str, Any] | None,
write_policy: str,
) -> list[dict[str, Any]]:
"""Process the AI's tool_calls and create actions+approvals for writes.
For each tool call that needs approval, create the action + encrypted
params + approval + audit event in a **single transaction**
(``store.create_pending_action_bundle``). If any step fails, the whole
bundle rolls back — the DB never holds a half-finished action.
Idempotency: ``idempotency_key`` is DB-unique. A concurrent duplicate
submission re-reads and returns the already-stored action instead of
raising, so a retry never fails the run.
Returns a list of created (or pre-existing) action dicts.
"""
created: list[dict[str, Any]] = []
for tc in tool_calls:
tool_name = tc.get("name", "")
tool_call_id = tc.get("id", "")
raw_args = tc.get("args") or {}
if not tool_needs_approval(tool_name, write_policy, capability_snapshot, agent_id):
continue
_side_effect, risk_level = classify_tool(tool_name, capability_snapshot, agent_id)
idempotency_key = f"{run_id}:{agent_id}:{turn_index}:{tool_call_id or tool_name}"
# Sanitize args for audit visibility (never expose raw args).
sanitized_args = sanitize(raw_args)
if not isinstance(sanitized_args, dict):
sanitized_args = {"value": str(sanitized_args)}
# Encrypt actual args for server-only recovery.
encrypted_args = encrypt_params(
raw_args if isinstance(raw_args, dict) else {"value": str(raw_args)}
)
# Single-transaction bundle: action + secret + approval + event.
# The store retries internally (up to 8 attempts) on (run_id, seq)
# collisions, re-computing MAX(seq)+1 each time.
action = await self._store.create_pending_action_bundle(
session_id=session_id,
run_id=run_id,
agent_id=agent_id,
tool_name=tool_name,
logical_action_id=tool_call_id or None,
idempotency_key=idempotency_key,
risk_level=risk_level,
target_key=None,
turn_index=turn_index,
arguments_sanitized=sanitized_args,
arguments_encrypted=encrypted_args,
approval_summary=f"外部写操作需要审批: {tool_name}(第{turn_index}轮)",
approval_payload={
"tool_name": tool_name,
"risk_level": risk_level,
"turn_index": turn_index,
"arguments_redacted": sanitized_args,
},
audit_event_agent_id=agent_id,
audit_event_turn_index=turn_index,
)
created.append(action)
return created
# ── Post-approval: atomic occupy + execution ─────────────────────────
async def occupy_for_execution(self, action_id: str) -> str:
"""Atomically transition an action from ``approved`` to ``running``.
Returns the effective claim status (never a blanket bool):
``"claimed"`` (won — execute), ``"in_progress"`` (another executor is
running it), or a terminal status ``succeeded`` / ``failed`` /
``unknown`` / ``rejected`` (already finished elsewhere). Raises
``MafActionStateMachineError`` when the action was never properly
approved. This guarantees at-most-once execution under concurrent
``resume()`` / retries / restart.
"""
return await self._store.actions.claim_for_execution(action_id)
async def record_result(
self,
action_id: str,
*,
status: str,
result: dict[str, Any] | None = None,
external_object_id: str | None = None,
) -> None:
"""Record the outcome of an action execution.
``status`` must be ``succeeded``, ``failed``, or ``unknown``.
``unknown`` prohibits auto-retry — the action stays in ``unknown``
until a human reconciles it.
State-machine constrained: only a ``running`` action may transition
to a terminal status. A concurrent caller that lost the race (or a
replay after restart) finds the row already terminal and its UPDATE
is a no-op — it must NOT overwrite the real result.
"""
sanitized_result = sanitize_payload(result) if result else None
await self._store.actions.record_terminal_result(
action_id,
status=status,
result=sanitized_result,
external_object_id=external_object_id,
)
async def get_approved_action_params(self, action_id: str) -> dict[str, Any]:
"""Decrypt and return the actual execution parameters for an approved action.
Server-only: called only by the tool executor at execution time. The
decrypted params never reach API, events, logs, or frontend.
Raises ``ActionSecretUnavailableError`` (never returns ``None``) when
the params cannot be produced — missing secret row, undecryptable
ciphertext, or a non-object plaintext. The caller MUST treat this as a
hard failure (record ``failed``, fail the parent run, never execute the
tool); it must NOT fall back to empty params.
"""
ciphertext = await self._store.action_secrets.get_by_action(action_id)
if ciphertext is None:
raise ActionSecretUnavailableError(
action_id, "missing", "no encrypted action secret is stored for this action"
)
try:
params = decrypt_params(ciphertext)
except Exception as exc:
# Log a sanitized reason only — never the ciphertext, key, or raw body.
logger.error(
"Failed to decrypt action params for %s: %s",
action_id, sanitize(str(exc)),
)
raise ActionSecretUnavailableError(
action_id, "decrypt_failed", "encrypted action params could not be decrypted"
) from exc
if not isinstance(params, dict):
raise ActionSecretUnavailableError(
action_id, "invalid_type", "decrypted action params are not a JSON object"
)
return params
@@ -0,0 +1,168 @@
"""Build server-trusted, frozen MAF capability snapshots.
Clients must not supply tool metadata or full snapshots — only participant
``agent_id`` and optional per-seat ``excluded_tools`` (subtractive only).
"""
from __future__ import annotations
import logging
from typing import Any
from deerflow.config.agents_config import load_agent_config
from deerflow.config.app_config import AppConfig
from deerflow.tools.tool_metadata import resolve_tool_metadata
from deerflow.tools.tools import get_available_tools
logger = logging.getLogger(__name__)
class CapabilitySnapshotError(Exception):
"""Invalid participant / tool selection when building a trusted snapshot."""
class AgentNotAccessibleError(CapabilitySnapshotError):
def __init__(self, agent_id: str) -> None:
super().__init__(f"agent not accessible: {agent_id}")
self.agent_id = agent_id
class InvalidExcludedToolsError(CapabilitySnapshotError):
def __init__(self, agent_id: str, tools: list[str]) -> None:
super().__init__(f"invalid excluded_tools for {agent_id}: {tools}")
self.agent_id = agent_id
self.tools = tools
async def _assert_user_may_use_agent(
*,
agent_store: Any | None,
user_id: str,
agent_id: str,
) -> None:
"""Ensure the user may run this agent (visible in catalog)."""
if agent_store is not None:
visible = await agent_store.get_visible(agent_id, user_id)
if visible is None:
raise AgentNotAccessibleError(agent_id)
return
cfg = load_agent_config(agent_id)
if cfg is None:
raise AgentNotAccessibleError(agent_id)
def _config_extra_for_tool(app_config: AppConfig, tool_name: str) -> dict[str, Any] | None:
for tc in app_config.tools:
if tc.name == tool_name:
extra = dict(getattr(tc, "model_extra", None) or {})
return extra or None
return None
def _seat_tools_for_agent(
*,
app_config: AppConfig,
agent_id: str,
session_model_name: str | None,
session_reasoning_effort: str | None,
requested_excluded: list[str],
) -> tuple[list[str], list[str], list[dict[str, str]]]:
"""Resolve allowed names, effective excluded, and tool metadata for one seat."""
agent_config = load_agent_config(agent_id)
tool_groups = getattr(agent_config, "tool_groups", None) if agent_config else None
model_name = (
getattr(agent_config, "model", None) if agent_config else None
) or session_model_name
available = get_available_tools(
groups=tool_groups,
model_name=model_name,
excluded_tools=[],
app_config=app_config,
)
allowed_set = {t.name for t in available}
excluded_set = set(requested_excluded or [])
unknown_excluded = excluded_set - allowed_set
if unknown_excluded:
raise InvalidExcludedToolsError(agent_id, sorted(unknown_excluded))
effective_excluded = sorted(excluded_set & allowed_set)
effective_allowed = sorted(allowed_set - set(effective_excluded))
tools_meta: list[dict[str, str]] = []
for name in effective_allowed:
extra = _config_extra_for_tool(app_config, name)
tools_meta.append(resolve_tool_metadata(name, config_extra=extra))
return effective_allowed, effective_excluded, tools_meta
async def build_trusted_capability_snapshot(
*,
user_id: str,
participants: list[dict[str, Any]],
app_config: AppConfig,
agent_store: Any | None = None,
session_model_name: str | None = None,
session_reasoning_effort: str | None = None,
session_excluded_tools: list[str] | None = None,
) -> dict[str, Any]:
"""Build the frozen snapshot stored on the session and used by WriteGuard."""
agents_out: list[dict[str, Any]] = []
flat_tools: dict[str, dict[str, str]] = {}
for p in participants:
agent_id = str(p.get("agent_id") or "")
if not agent_id:
continue
await _assert_user_may_use_agent(
agent_store=agent_store, user_id=user_id, agent_id=agent_id
)
agent_config = load_agent_config(agent_id)
seat_excluded = list(p.get("excluded_tools") or [])
if session_excluded_tools:
seat_excluded = sorted(set(seat_excluded) | set(session_excluded_tools))
allowed, excluded, tools_meta = _seat_tools_for_agent(
app_config=app_config,
agent_id=agent_id,
session_model_name=session_model_name,
session_reasoning_effort=session_reasoning_effort,
requested_excluded=seat_excluded,
)
for meta in tools_meta:
flat_tools[meta["tool_name"]] = meta
agents_out.append(
{
"agent_id": agent_id,
"role": p.get("role", "seat"),
"model_name": getattr(agent_config, "model", None) if agent_config else session_model_name,
"reasoning_effort": session_reasoning_effort,
"thinking_enabled": True,
"subagent_enabled": bool(getattr(agent_config, "subagent_enabled", False))
if agent_config
else False,
"tool_groups": list(getattr(agent_config, "tool_groups", None) or [])
if agent_config
else None,
"allowed_tool_names": allowed,
"excluded_tools": excluded,
"tools": tools_meta,
"memory_recall_disabled": None,
"memory_injection_enabled": None,
}
)
return {
"version": 1,
"agents": agents_out,
"tools": list(flat_tools.values()),
}
def seat_snapshot_for_agent(full_snapshot: dict[str, Any], agent_id: str) -> dict[str, Any]:
"""Per-participant slice persisted on ``maf_roundtable_participants``."""
for a in full_snapshot.get("agents") or []:
if isinstance(a, dict) and a.get("agent_id") == agent_id:
return dict(a)
return {}
@@ -0,0 +1,160 @@
"""Build bounded, traceable seat input from MAF roundtable context.
Converts the shared roundtable state (task, previous turns, fact ledger,
stage instructions) into a single human message for a seat's DeerFlow thread.
Design constraints (MAF-02-06):
- Bounded: total output STRICTLY never exceeds ``max_context_chars``.
- Trimmable: each section is independently truncatable.
- Traceable: includes turn references so the seat can cite prior work.
- Never injects credentials, tokens, or raw binary content.
- All content is sanitized before inclusion.
"""
from __future__ import annotations
from typing import Any
from app.maf_roundtable.sanitize import sanitize
_DEFAULT_MAX_CONTEXT_CHARS = 12000
_DEFAULT_MAX_TURN_CHARS = 2000
_DEFAULT_MAX_FACT_CHARS = 3000
def build_seat_input(
*,
task_text: str,
stage_instruction: str,
role_description: str,
prior_turns: list[dict[str, Any]],
fact_ledger: dict[str, Any] | None = None,
max_context_chars: int = _DEFAULT_MAX_CONTEXT_CHARS,
max_turn_chars: int = _DEFAULT_MAX_TURN_CHARS,
max_fact_chars: int = _DEFAULT_MAX_FACT_CHARS,
) -> str:
"""Assemble the human message for a seat's DeerFlow run.
The total output length is STRICTLY <= max_context_chars. Truncation
happens per-section first, then a final hard cap ensures no overflow.
"""
sections: list[str] = []
sections.append(f"【任务】\n{task_text}")
if role_description:
sections.append(f"【你的角色】\n{role_description}")
if stage_instruction:
sections.append(f"【本阶段要求】\n{stage_instruction}")
if prior_turns:
turns_text = _format_prior_turns(prior_turns, max_turn_chars)
if turns_text:
sections.append(f"【已有讨论】\n{turns_text}")
if fact_ledger:
sanitized_ledger = sanitize(fact_ledger)
if isinstance(sanitized_ledger, dict):
facts_text = _format_fact_ledger(sanitized_ledger, max_fact_chars)
if facts_text:
sections.append(f"【共享事实账本】\n{facts_text}")
result = "\n\n".join(sections)
if len(result) > max_context_chars:
result = result[:max_context_chars]
return result
def build_manager_synthesis_input(
*,
task_text: str,
seat_results: list[dict[str, Any]],
fact_ledger: dict[str, Any] | None = None,
max_context_chars: int = _DEFAULT_MAX_CONTEXT_CHARS,
) -> str:
"""Build the manager's final synthesis prompt."""
sections: list[str] = []
sections.append(f"【原始任务】\n{task_text}")
sections.append("【各席位分析结果】")
for r in seat_results:
agent_id = r.get("agent_id", "unknown")
content = str(r.get("content", ""))
if len(content) > 3000:
content = content[:3000] + "..."
sections.append(f"--- {agent_id} ---\n{content}")
if fact_ledger:
sanitized_ledger = sanitize(fact_ledger)
if isinstance(sanitized_ledger, dict):
facts_text = _format_fact_ledger(sanitized_ledger, _DEFAULT_MAX_FACT_CHARS)
if facts_text:
sections.append(f"【共享事实账本】\n{facts_text}")
sections.append(
"【综合要求】\n"
"请基于以上各席位分析和事实账本,生成最终结论。要求:\n"
"1. 明确标注共识点和分歧点\n"
"2. 区分「建议动作」和「已实际执行的动作」\n"
"3. 引用具体证据来源\n"
"4. 列出失败或状态不确定的动作"
)
result = "\n\n".join(sections)
if len(result) > max_context_chars:
result = result[:max_context_chars]
return result
# ── internal helpers ──────────────────────────────────────────────────────────
def _format_prior_turns(turns: list[dict[str, Any]], max_per_turn: int) -> str:
lines: list[str] = []
for t in turns:
agent_id = t.get("agent_id", "unknown")
turn_idx = t.get("turn_index", "?")
summary = str(t.get("summary", ""))
if len(summary) > max_per_turn:
summary = summary[:max_per_turn] + "..."
lines.append(f"[轮次{turn_idx}] {agent_id}: {summary}")
return "\n".join(lines)
def _format_fact_ledger(ledger: dict[str, Any], max_chars: int) -> str:
parts: list[str] = []
facts = ledger.get("confirmed_facts")
if facts and isinstance(facts, list):
parts.append("已确认事实:")
for f in facts[:20]:
parts.append(f" - {f}")
tool_results = ledger.get("tool_results")
if tool_results and isinstance(tool_results, list):
parts.append("工具执行结果:")
for tr in tool_results[:10]:
if isinstance(tr, dict):
parts.append(f" - {tr.get('tool_name', '?')}: {tr.get('status', '?')}")
else:
parts.append(f" - {tr}")
conflicts = ledger.get("conflicts")
if conflicts and isinstance(conflicts, list):
parts.append("未解决冲突:")
for c in conflicts[:5]:
parts.append(f" - {c}")
pending = ledger.get("pending_actions")
if pending and isinstance(pending, list):
parts.append("等待确认动作:")
for p in pending[:5]:
parts.append(f" - {p}")
result = "\n".join(parts)
if len(result) > max_chars:
result = result[:max_chars]
return result
@@ -0,0 +1,513 @@
"""DeerFlow Agent Adapter for the MAF roundtable experiment (Phase 2).
Drives each MAF seat's actual execution through the existing DeerFlow Agent
Runtime, preserving tools / skills / MCP / sandbox / identity / middleware
semantics. The adapter does NOT wrap individual LangChain tools — it invokes
a full agent run per seat turn via ``DeerFlowRuntimeClient``.
Architecture:
- One DeerFlow thread per seat (bound at session start, reused across turns).
- In-process ``start_run`` via DeerFlowRuntimeClient (no fake Request).
- User context injected via ExecutionPrincipal (server-generated, never from body).
- StreamBridge subscription translates runtime SSE → MAF events in real time.
- Cancellation propagates from MAF run → DeerFlow run via RunManager.cancel.
- All seat runs persisted to ``maf_roundtable_seat_runs`` (survives restart).
- Critical audit events (tool.*, skill.*, approval.*, artifact.*) MUST persist;
failure stops external writes and marks the run as failed.
Boundary: lives in ``app.maf_roundtable`` (may import ``deerflow.*`` and
``app.gateway.*``); never imported by ``deerflow.*``.
"""
from __future__ import annotations
import asyncio
import logging
import os
import time
from dataclasses import dataclass, field
from typing import Any
from app.maf_roundtable.context_builder import build_seat_input
from app.maf_roundtable.event_normalizer import (
make_run_cancelled,
make_run_failed,
make_turn_completed,
make_turn_started,
normalize_stream_event,
)
from app.maf_roundtable.runtime_client import DeerFlowRuntimeClient, ExecutionPrincipal
from app.maf_roundtable.sanitize import sanitize
from deerflow.runtime.stream_bridge.base import END_SENTINEL, HEARTBEAT_SENTINEL
logger = logging.getLogger(__name__)
_IDLE_TIMEOUT_S = int(os.getenv("MAF_SEAT_IDLE_TIMEOUT_SECONDS", "1200") or "1200")
_IDLE_CHECK_INTERVAL_S = 10.0
_MAX_CONTEXT_CHARS = int(os.getenv("MAF_MAX_CONTEXT_CHARS", "12000") or "12000")
_CRITICAL_EVENT_TYPES = frozenset({
"tool.requested", "tool.started", "tool.completed", "tool.failed",
"skill.selected", "skill.started", "skill.completed", "skill.failed",
"artifact.created",
"action.waiting_approval", "action.approved", "action.rejected",
"run.completed", "run.failed", "run.cancelled",
})
class AuditEventError(RuntimeError):
"""Raised when a critical audit event fails to persist."""
@dataclass
class SeatResponse:
"""Standardized response from a seat turn (MAF-02-08)."""
agent_id: str
turn_index: int
content: str
tool_calls: list[dict[str, Any]] = field(default_factory=list)
usage: dict[str, Any] | None = None
metadata: dict[str, Any] | None = None
error: str | None = None
latency_ms: int | None = None
class DeerFlowAgentAdapter:
"""Drives MAF seat execution through the DeerFlow Agent Runtime.
Usage::
client = DeerFlowRuntimeClient(app)
adapter = DeerFlowAgentAdapter(client, service=svc, user_id="u1")
await adapter.ensure_threads(session_id, participants)
response = await adapter.run_seat_turn(...)
"""
def __init__(
self,
runtime_client: DeerFlowRuntimeClient,
*,
service: Any,
user_id: str,
) -> None:
self._client = runtime_client
self._service = service
self._user_id = user_id
self._seen_source_ids: set[str] = set()
# ── MAF-02-01: thread lifecycle ─────────────────────────────────────────
async def ensure_threads(
self, session_id: str, run_id: str, participants: list[dict[str, Any]]
) -> dict[str, str]:
"""Create and bind a DeerFlow thread for each participant that lacks one.
Thread creation is wrapped in set_current_user so thread_meta.user_id
matches the MAF session owner. Returns ``{agent_id: thread_id}``.
"""
principal = ExecutionPrincipal(user_id=self._user_id, session_id=session_id, run_id=run_id)
thread_map: dict[str, str] = {}
for p in participants:
agent_id = p.get("agent_id", "")
existing = p.get("thread_id")
if existing:
thread_map[agent_id] = existing
continue
thread_id = await self._client.create_thread(principal)
await self._service.store.participants.bind_thread(
session_id, agent_id, thread_id=thread_id
)
thread_map[agent_id] = thread_id
return thread_map
# ── MAF-02-02/03/04/05: seat turn execution ─────────────────────────────
async def run_seat_turn(
self,
*,
session_id: str,
run_id: str,
agent_id: str,
turn_index: int,
message: str,
thread_id: str,
model_name: str | None = None,
reasoning_effort: str | None = None,
thinking_enabled: bool = True,
subagent_enabled: bool = False,
excluded_tools: list[str] | None = None,
stage_instruction: str = "",
prior_turns: list[dict[str, Any]] | None = None,
fact_ledger: dict[str, Any] | None = None,
role_description: str = "",
task_text: str = "",
memory_recall_disabled: bool | None = None,
memory_injection_enabled: bool | None = None,
capability_snapshot: dict[str, Any] | None = None,
write_policy: str = "confirm_high_risk",
approved_tool: str | None = None,
) -> SeatResponse:
"""Execute one seat turn through the DeerFlow Agent Runtime."""
t0 = time.perf_counter()
seat_message = build_seat_input(
task_text=task_text or message,
stage_instruction=stage_instruction,
role_description=role_description,
prior_turns=prior_turns or [],
fact_ledger=fact_ledger,
max_context_chars=_MAX_CONTEXT_CHARS,
)
if not task_text:
seat_message = message
await self._emit_critical(run_id, make_turn_started(agent_id, turn_index, {"thread_id": thread_id}))
principal = ExecutionPrincipal(user_id=self._user_id, session_id=session_id, run_id=run_id)
seat_run = await self._service.store.seat_runs.create_seat_run(
maf_run_id=run_id, agent_id=agent_id, turn_index=turn_index, deerflow_thread_id=thread_id
)
seat_run_id = seat_run["id"]
try:
response = await self._execute_run(
principal=principal,
seat_run_id=seat_run_id,
run_id=run_id,
agent_id=agent_id,
turn_index=turn_index,
thread_id=thread_id,
message=seat_message,
model_name=model_name,
reasoning_effort=reasoning_effort,
thinking_enabled=thinking_enabled,
subagent_enabled=subagent_enabled,
excluded_tools=excluded_tools or [],
memory_recall_disabled=memory_recall_disabled,
memory_injection_enabled=memory_injection_enabled,
capability_snapshot=capability_snapshot,
write_policy=write_policy,
approved_tool=approved_tool,
)
except asyncio.CancelledError:
await self._service.store.seat_runs.mark_cancelled(seat_run_id)
await self._emit_critical(run_id, make_run_cancelled(agent_id, turn_index))
raise
except Exception as exc:
latency = int((time.perf_counter() - t0) * 1000)
# Sanitize before persisting / emitting — the raw exception body may
# embed params or credentials; only the redacted text is stored.
safe_error = str(sanitize(str(exc)))[:500]
await self._service.store.seat_runs.mark_failed(seat_run_id, error=safe_error)
await self._emit_critical(run_id, make_run_failed(agent_id, turn_index, error_code=type(exc).__name__, message=safe_error))
return SeatResponse(
agent_id=agent_id,
turn_index=turn_index,
content="",
error=safe_error,
latency_ms=latency,
)
await self._service.store.seat_runs.mark_completed(seat_run_id)
response.latency_ms = int((time.perf_counter() - t0) * 1000)
await self._emit_critical(run_id, make_turn_completed(
agent_id, turn_index,
content=response.content,
usage=response.usage,
metadata=response.metadata,
))
return response
async def _execute_run(
self,
*,
principal: ExecutionPrincipal,
seat_run_id: str,
run_id: str,
agent_id: str,
turn_index: int,
thread_id: str,
message: str,
model_name: str | None,
reasoning_effort: str | None,
thinking_enabled: bool,
subagent_enabled: bool,
excluded_tools: list[str],
memory_recall_disabled: bool | None,
memory_injection_enabled: bool | None,
capability_snapshot: dict[str, Any] | None = None,
write_policy: str = "confirm_high_risk",
approved_tool: str | None = None,
) -> SeatResponse:
record = await self._client.start_agent_run(
principal,
thread_id=thread_id,
agent_id=agent_id,
message=message,
model_name=model_name,
reasoning_effort=reasoning_effort,
thinking_enabled=thinking_enabled,
subagent_enabled=subagent_enabled,
excluded_tools=excluded_tools,
memory_recall_disabled=memory_recall_disabled,
memory_injection_enabled=memory_injection_enabled,
turn_index=turn_index,
capability_snapshot=capability_snapshot,
write_policy=write_policy,
approved_tool=approved_tool,
)
deerflow_run_id = getattr(record, "run_id", None)
if deerflow_run_id:
await self._service.store.seat_runs.mark_running(seat_run_id, deerflow_run_id=deerflow_run_id)
await self._await_with_event_translation(
record, deerflow_run_id, run_id=run_id, agent_id=agent_id, turn_index=turn_index
)
messages = await self._client.read_thread_messages(principal, thread_id)
content = self._latest_ai_text(messages)
tool_calls = self._tool_calls_since_last_human(messages)
usage = self._extract_usage(messages)
return SeatResponse(
agent_id=agent_id,
turn_index=turn_index,
content=content,
tool_calls=tool_calls,
usage=usage,
metadata={"thread_id": thread_id, "deerflow_run_id": deerflow_run_id},
)
# ── MAF-02-07: real-time event translation ──────────────────────────────
async def _await_with_event_translation(
self,
record: Any,
deerflow_run_id: str | None,
*,
run_id: str,
agent_id: str,
turn_index: int,
) -> None:
"""Await the DeerFlow run while translating StreamBridge events to MAF events.
P1.5 fix: ``if task in done: await task`` so exceptions propagate.
"""
task = getattr(record, "task", None)
if task is None:
return
bridge = getattr(self._client.app.state, "stream_bridge", None)
if bridge is None or deerflow_run_id is None:
await task
return
loop = asyncio.get_running_loop()
last_activity = loop.time()
stuck = asyncio.Event()
async def _watch() -> None:
nonlocal last_activity
async for ev in bridge.subscribe(deerflow_run_id, heartbeat_interval=_IDLE_CHECK_INTERVAL_S):
if ev is END_SENTINEL:
return
now = loop.time()
if ev is HEARTBEAT_SENTINEL:
if now - last_activity >= _IDLE_TIMEOUT_S:
stuck.set()
return
else:
last_activity = now
maf_events = normalize_stream_event(
ev.event, ev.data, agent_id=agent_id, turn_index=turn_index
)
for me in maf_events:
await self._emit(run_id, me)
watch = asyncio.create_task(_watch())
try:
done, _ = await asyncio.wait({task, watch}, return_when=asyncio.FIRST_COMPLETED)
if task in done:
await task
return
if not stuck.is_set():
await task
return
idle_elapsed = loop.time() - last_activity
logger.error(
"MAF seat '%s' stalled: no output for %.0fs on run %s",
agent_id, idle_elapsed, deerflow_run_id,
)
await self._client.cancel_run(deerflow_run_id)
try:
await asyncio.wait_for(asyncio.shield(task), timeout=10.0)
except (TimeoutError, asyncio.CancelledError, Exception):
logger.warning("DeerFlow task did not finish after cancel for run %s", deerflow_run_id)
raise RuntimeError(f"MAF seat '{agent_id}' stalled (no output for {_IDLE_TIMEOUT_S}s)")
finally:
if not watch.done():
watch.cancel()
try:
await watch
except BaseException:
pass
# ── MAF-02-09: cancellation ─────────────────────────────────────────────
async def cancel(self, maf_run_id: str) -> dict[str, Any]:
"""Cancel all active DeerFlow runs for a MAF run (two-phase cascade).
Phase 1: mark all active seat runs as ``cancelling``.
Phase 2: actually cancel each DeerFlow run, then mark the seat run
as ``cancelled`` (success) or ``cancel_failed`` (failure).
Returns a structured result so the caller (dispatcher → router) can
decide whether to finalize the parent run as ``cancelled`` or leave it
in a non-terminal ``cancelling`` / ``cancel_failed`` state. A failed
cancel must NEVER masquerade as cancelled.
Result shape::
{
"all_cancelled": bool,
"cancelled_run_ids": [...], # seat_run_ids that succeeded
"failed_run_ids": [...], # seat_run_ids where cancel failed
"still_active_run_ids": [...], # seat_run_ids with no deerflow id
}
"""
seat_infos = await self._service.store.seat_runs.cancel_all_active(maf_run_id)
cancelled_run_ids: list[str] = []
failed_run_ids: list[str] = []
still_active_run_ids: list[str] = []
for info in seat_infos:
seat_run_id = info["seat_run_id"]
deerflow_run_id = info.get("deerflow_run_id")
if not deerflow_run_id:
# No DeerFlow run to cancel — record as still-active/unknown.
await self._service.store.seat_runs.mark_cancel_unknown(
seat_run_id, error="no deerflow_run_id recorded"
)
still_active_run_ids.append(seat_run_id)
continue
if await self._client.cancel_run(deerflow_run_id):
await self._service.store.seat_runs.mark_cancelled(seat_run_id)
cancelled_run_ids.append(seat_run_id)
else:
await self._service.store.seat_runs.mark_cancel_failed(
seat_run_id, error="DeerFlow cancel_run returned False"
)
failed_run_ids.append(seat_run_id)
all_cancelled = not failed_run_ids and not still_active_run_ids and bool(seat_infos)
# If there were no active seat runs at all, treat as fully cancelled
# (nothing left to cancel).
if not seat_infos:
all_cancelled = True
return {
"all_cancelled": all_cancelled,
"cancelled_run_ids": cancelled_run_ids,
"failed_run_ids": failed_run_ids,
"still_active_run_ids": still_active_run_ids,
}
# ── P1.6: audit event persistence ───────────────────────────────────────
async def _emit_critical(self, run_id: str, event: dict[str, Any]) -> None:
"""Emit a critical audit event. Failure raises AuditEventError."""
try:
await self._service.append_event(
run_id=run_id,
user_id=self._user_id,
event_type=event["event_type"],
agent_id=event.get("agent_id"),
turn_index=event.get("turn_index"),
payload=event.get("payload"),
)
except Exception as exc:
logger.error("CRITICAL audit event %s failed to persist for run %s", event.get("event_type"), run_id, exc_info=True)
raise AuditEventError(
f"Critical audit event '{event.get('event_type')}' failed to persist: {exc}"
) from exc
async def _emit(self, run_id: str, event: dict[str, Any]) -> None:
"""Emit a non-critical event (agent.message.delta). Failure degrades gracefully.
Dedup: events with a source_event_id are deduped at the DB level via
the (run_id, source_event_id) unique constraint — durable across restarts.
The in-memory _seen_source_ids set is a fast-path cache only.
"""
source_id = event.get("source_event_id")
if source_id:
if source_id in self._seen_source_ids:
return
self._seen_source_ids.add(source_id)
event_type = event.get("event_type", "")
if event_type in _CRITICAL_EVENT_TYPES:
await self._emit_critical(run_id, event)
return
try:
await self._service.append_event(
run_id=run_id,
user_id=self._user_id,
event_type=event_type,
agent_id=event.get("agent_id"),
turn_index=event.get("turn_index"),
payload=event.get("payload"),
source_event_id=source_id,
)
except Exception:
logger.warning("non-critical event %s failed for run %s (degraded)", event_type, run_id, exc_info=True)
# ── internal helpers ────────────────────────────────────────────────────
def _latest_ai_text(self, messages: list[dict[str, Any]]) -> str:
for m in reversed(messages):
if not isinstance(m, dict):
continue
if (m.get("type") or m.get("role")) not in {"ai", "assistant"}:
continue
text = self._message_text(m)
if text.strip():
return text
return ""
def _message_text(self, message: dict[str, Any]) -> str:
content = message.get("content")
if isinstance(content, str):
return content
if isinstance(content, list):
parts = [p.get("text", "") for p in content if isinstance(p, dict) and p.get("type") == "text"]
return "\n".join(parts)
return ""
def _tool_calls_since_last_human(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
last_human = -1
for i, m in enumerate(messages):
if isinstance(m, dict) and (m.get("type") or m.get("role")) in {"human", "user"}:
last_human = i
out: list[dict[str, Any]] = []
for m in messages[last_human + 1:]:
if not isinstance(m, dict):
continue
if (m.get("type") or m.get("role")) not in {"ai", "assistant"}:
continue
for tc in m.get("tool_calls") or []:
if not isinstance(tc, dict):
continue
name = tc.get("name") or ""
if not name:
continue
out.append({"name": name, "args": tc.get("args") or {}, "id": tc.get("id") or ""})
return out
def _extract_usage(self, messages: list[dict[str, Any]]) -> dict[str, Any] | None:
for m in reversed(messages):
if not isinstance(m, dict):
continue
usage = m.get("usage_metadata") or m.get("usage")
if isinstance(usage, dict) and usage:
return usage
return None
@@ -0,0 +1,171 @@
"""MAF run dispatcher — launches WorkflowRunner after create_run succeeds.
The dispatcher is the bridge between the HTTP layer (router) and the workflow
execution layer (WorkflowRunner). It:
1. Checks MAF SDK availability BEFORE creating the run (so the user gets a
clean 503 rather than a run that will fail).
2. Launches ``WorkflowRunner.execute`` as a background asyncio task.
3. Tracks task handles for cancellation.
4. **Resume**: after an approval decision, the router calls
``dispatcher.resume(run_id, user_id)`` to restore the workflow from its
checkpoint.
5. **Cancel cascade**: ``dispatcher.cancel(run_id)`` cancels both the
background task AND the DeerFlow sub-runs. If the task handle is gone
(process restart), it rebuilds a runner from persisted ``seat_runs`` and
cascades cancel to DeerFlow.
6. Never silently degrades to sequential DeerFlow execution — if the SDK is
missing or the workflow fails, the run is marked ``failed``.
Usage (from the router)::
from app.maf_roundtable.dispatcher import get_dispatcher
dispatcher = get_dispatcher(request.app)
await dispatcher.dispatch(session, run, user_id=user_id)
"""
from __future__ import annotations
import asyncio
import logging
from typing import Any
logger = logging.getLogger(__name__)
class MafSdkNotAvailableError(RuntimeError):
"""Raised when the MAF SDK is not installed and a run is requested."""
class MafRunDispatcher:
"""Manages background MAF workflow execution tasks."""
def __init__(self, app: Any) -> None:
self._app = app
self._tasks: dict[str, asyncio.Task] = {}
def check_sdk_available(self) -> None:
"""Raise MafSdkNotAvailableError if the MAF SDK is not installed."""
try:
import agent_framework # noqa: F401
except ImportError as exc:
raise MafSdkNotAvailableError(
"agent_framework SDK is not installed; run 'uv sync --extra maf' to enable MAF workflows"
) from exc
async def dispatch(self, session: dict[str, Any], run: dict[str, Any], *, user_id: str) -> None:
"""Launch the workflow for a newly created run as a background task.
The task is tracked so it can be cancelled via ``cancel(run_id)``.
"""
from app.maf_roundtable.workflow_runner import WorkflowRunner
run_id = run["id"]
service = getattr(self._app.state, "maf_roundtable_service", None)
if service is None:
raise MafSdkNotAvailableError("MAF roundtable service not available")
runner = WorkflowRunner(self._app, service=service, user_id=user_id)
task = asyncio.create_task(self._execute(runner, session, run, run_id))
self._tasks[run_id] = task
task.add_done_callback(lambda t, rid=run_id: self._tasks.pop(rid, None))
async def _execute(self, runner: Any, session: dict[str, Any], run: dict[str, Any], run_id: str) -> None:
"""Execute the workflow, catching all exceptions (they're already persisted by the runner)."""
try:
await runner.execute(session, run)
except Exception:
# The runner already persists the failure. Log for observability.
logger.exception("MAF workflow execution failed for run %s", run_id)
async def resume(self, run_id: str, *, user_id: str) -> dict[str, Any] | None:
"""Resume a workflow from its checkpoint after an approval decision.
Called by the router after ``decide_approval`` succeeds. Loads the
runner (rebuilding if the process restarted), then calls
``runner.resume(run_id)`` which restores ``RoundtableState.from_dict()``
and executes the approved action (at-most-once).
"""
from app.maf_roundtable.workflow_runner import WorkflowRunner
service = getattr(self._app.state, "maf_roundtable_service", None)
if service is None:
raise MafSdkNotAvailableError("MAF roundtable service not available")
runner = WorkflowRunner(self._app, service=service, user_id=user_id)
return await runner.resume(run_id)
async def cancel(self, run_id: str) -> dict[str, Any]:
"""Cancel a running workflow AND cascade to DeerFlow sub-runs.
Returns a structured cancel result so the router can decide whether to
finalize the parent run as ``cancelled`` (all sub-runs confirmed
cancelled / already terminal) or leave it non-terminal (some sub-runs
failed to cancel — must not masquerade as cancelled).
Result shape::
{
"all_cancelled": bool,
"cancelled_run_ids": [...],
"failed_run_ids": [...],
"still_active_run_ids": [...],
}
"""
from app.maf_roundtable.workflow_runner import WorkflowRunner
_EMPTY = {"all_cancelled": False, "cancelled_run_ids": [], "failed_run_ids": [], "still_active_run_ids": []}
# P1c cancel order: the parent run is already in ``cancelling`` (the
# router sets it before calling here). We then (1) cascade-cancel the
# DeerFlow seat runs first and confirm/record the outcome, and only
# (2) cancel the local MAF asyncio task LAST. The router finalizes the
# parent run as ``cancelled`` only when every sub-run confirmed
# cancelled — a failed cascade must never masquerade as cancelled.
service = getattr(self._app.state, "maf_roundtable_service", None)
if service is None:
return _EMPTY
run = await service.store.runs.get_run(run_id)
if run is None:
return _EMPTY
session = await service.store.sessions.get_session(run["session_id"], user_id=None)
if session is None:
return _EMPTY
user_id = session.get("user_id", "default")
runner = WorkflowRunner(self._app, service=service, user_id=user_id)
# Step 1: cascade cancel to DeerFlow sub-runs (works even after a
# process restart — the runner reads persisted seat_runs).
try:
result = await runner.cancel(run_id)
except Exception: # noqa: BLE001
logger.exception("MAF cancel cascade failed for run %s", run_id)
result = dict(_EMPTY)
# Step 2: cancel the local MAF asyncio task LAST (after the external
# sub-runs have been addressed), so we never drop the orchestrator
# before its sub-runs are cancelled/recorded.
task = self._tasks.get(run_id)
if task is not None and not task.done():
task.cancel()
try:
await task
except (asyncio.CancelledError, Exception): # noqa: BLE001
pass
return result
_dispatchers: dict[int, MafRunDispatcher] = {}
def get_dispatcher(app: Any) -> MafRunDispatcher:
"""Get or create the dispatcher for an app instance (keyed by id)."""
app_id = id(app)
if app_id not in _dispatchers:
_dispatchers[app_id] = MafRunDispatcher(app)
return _dispatchers[app_id]
@@ -0,0 +1,286 @@
"""Translate DeerFlow runtime SSE events into MAF roundtable event types.
Maps raw StreamBridge chunks (LangGraph Platform-aligned: ``metadata``,
``values``, ``updates``, ``messages``, ``error``, ``end``) into the durable
MAF event taxonomy persisted to ``maf_roundtable_events``.
Design constraints:
- Pure functions only (no I/O, no state).
- Never fabricates events: only emits what the runtime actually produced.
- Skill events come ONLY from structured tool/skill metadata, never from
guessing based on AI text content.
- All payloads are sanitized (credentials/tokens/cookies stripped).
- Supports source_event_id for dedup (messages + updates may overlap).
"""
from __future__ import annotations
from typing import Any
from app.maf_roundtable.sanitize import sanitize_payload
def normalize_stream_event(
sse_event: str,
data: Any,
*,
agent_id: str,
turn_index: int,
) -> list[dict[str, Any]]:
"""Convert a single DeerFlow SSE frame into zero or more MAF event dicts.
Each returned dict has:
``{event_type, agent_id, turn_index, payload, source_event_id?}``.
"""
if sse_event == "metadata":
return [_make("run.started", agent_id, turn_index, {"run_id": _get(data, "run_id"), "thread_id": _get(data, "thread_id")})]
if sse_event == "messages":
return _normalize_messages(data, agent_id, turn_index)
if sse_event == "updates":
return _normalize_updates(data, agent_id, turn_index)
if sse_event == "error":
return [_make("run.failed", agent_id, turn_index, {"message": _get(data, "message", ""), "name": _get(data, "name", "")})]
# Structured skill lifecycle events (emitted by DeerFlow skill middleware,
# never guessed from AI text content).
if sse_event in ("invoke_skill", "skill_search_step"):
skill_name = _get(data, "skill_name", "") or ""
if sse_event == "invoke_skill":
return [_make("skill.started", agent_id, turn_index, {"skill_name": skill_name, "message": _get(data, "message", "")})]
return [_make("skill.selected", agent_id, turn_index, {"skill_name": skill_name, "message": _get(data, "message", "")})]
if sse_event == "skill_result":
return [_make("skill.completed", agent_id, turn_index, {"skill_name": _get(data, "skill_name", ""), "message": _get(data, "message", "")})]
if sse_event == "skill_error":
return [_make("skill.failed", agent_id, turn_index, {"skill_name": _get(data, "skill_name", ""), "error": _get(data, "reason", "") or _get(data, "message", "")})]
if sse_event == "artifact_created":
return [_make("artifact.created", agent_id, turn_index, {"artifact_type": _get(data, "artifact_type", ""), "artifact_id": _get(data, "artifact_id", ""), "title": _get(data, "title", "")})]
return []
def make_turn_started(agent_id: str, turn_index: int, payload: dict[str, Any] | None = None) -> dict[str, Any]:
return _make("agent.turn_started", agent_id, turn_index, payload or {})
def make_turn_completed(
agent_id: str,
turn_index: int,
*,
content: str,
usage: dict[str, Any] | None = None,
metadata: dict[str, Any] | None = None,
) -> dict[str, Any]:
payload: dict[str, Any] = {"content": content}
if usage:
payload["usage"] = usage
if metadata:
payload["metadata"] = metadata
return _make("agent.message.completed", agent_id, turn_index, payload)
def make_run_completed(agent_id: str | None, turn_index: int, payload: dict[str, Any] | None = None) -> dict[str, Any]:
return _make("run.completed", agent_id or "", turn_index, payload or {})
def make_run_failed(agent_id: str | None, turn_index: int, *, error_code: str, message: str) -> dict[str, Any]:
return _make("run.failed", agent_id or "", turn_index, {"error_code": error_code, "message": message})
def make_run_cancelled(agent_id: str | None, turn_index: int) -> dict[str, Any]:
return _make("run.cancelled", agent_id or "", turn_index, {})
# ── skill lifecycle events ─────────────────────────────────────────────────
def make_skill_selected(agent_id: str, turn_index: int, *, skill_name: str, skill_id: str = "") -> dict[str, Any]:
return _make("skill.selected", agent_id, turn_index, {"skill_name": skill_name, "skill_id": skill_id})
def make_skill_started(agent_id: str, turn_index: int, *, skill_name: str, skill_id: str = "") -> dict[str, Any]:
return _make("skill.started", agent_id, turn_index, {"skill_name": skill_name, "skill_id": skill_id})
def make_skill_completed(agent_id: str, turn_index: int, *, skill_name: str, result_preview: str = "") -> dict[str, Any]:
return _make("skill.completed", agent_id, turn_index, {"skill_name": skill_name, "result_preview": _truncate(result_preview, 500)})
def make_skill_failed(agent_id: str, turn_index: int, *, skill_name: str, error: str = "") -> dict[str, Any]:
return _make("skill.failed", agent_id, turn_index, {"skill_name": skill_name, "error": _truncate(error, 500)})
# ── artifact events ────────────────────────────────────────────────────────
def make_artifact_created(agent_id: str, turn_index: int, *, artifact_type: str, artifact_id: str = "", title: str = "") -> dict[str, Any]:
return _make("artifact.created", agent_id, turn_index, {"artifact_type": artifact_type, "artifact_id": artifact_id, "title": title})
# ── approval lifecycle events ──────────────────────────────────────────────
def make_action_waiting_approval(agent_id: str, turn_index: int, *, action_id: str, approval_id: str, tool_name: str, summary: str = "") -> dict[str, Any]:
return _make("action.waiting_approval", agent_id, turn_index, {"action_id": action_id, "approval_id": approval_id, "tool_name": tool_name, "summary": _truncate(summary, 500)})
def make_action_approved(agent_id: str, turn_index: int, *, action_id: str, approval_id: str, decided_by: str = "") -> dict[str, Any]:
return _make("action.approved", agent_id, turn_index, {"action_id": action_id, "approval_id": approval_id, "decided_by": decided_by})
def make_action_rejected(agent_id: str, turn_index: int, *, action_id: str, approval_id: str, decided_by: str = "") -> dict[str, Any]:
return _make("action.rejected", agent_id, turn_index, {"action_id": action_id, "approval_id": approval_id, "decided_by": decided_by})
# ── workflow checkpoint events ─────────────────────────────────────────────
def make_workflow_checkpointed(agent_id: str | None, turn_index: int, *, checkpoint_id: str, reason: str = "") -> dict[str, Any]:
return _make("workflow.checkpointed", agent_id or "", turn_index, {"checkpoint_id": checkpoint_id, "reason": reason})
# ── internal helpers ──────────────────────────────────────────────────────────
def _make(event_type: str, agent_id: str, turn_index: int, payload: dict[str, Any], source_event_id: str | None = None) -> dict[str, Any]:
ev: dict[str, Any] = {
"event_type": event_type,
"agent_id": agent_id,
"turn_index": turn_index,
"payload": sanitize_payload(payload),
}
if source_event_id:
ev["source_event_id"] = source_event_id
return ev
def _get(data: Any, key: str, default: Any = None) -> Any:
if isinstance(data, dict):
return data.get(key, default)
return default
def _normalize_messages(data: Any, agent_id: str, turn_index: int) -> list[dict[str, Any]]:
"""Handle ``messages`` SSE event (streaming token deltas).
Format: ``[message_id, {type, content, ...}]`` (messages-tuple mode).
"""
events: list[dict[str, Any]] = []
if not isinstance(data, (list, tuple)) or len(data) < 2:
return events
msg_id = str(data[0]) if data[0] else None
msg = data[1] if len(data) > 1 else None
if not isinstance(msg, dict):
return events
msg_type = msg.get("type") or msg.get("role") or ""
content = msg.get("content")
if msg_type in ("ai", "assistant"):
tool_calls = msg.get("tool_calls")
if tool_calls:
for tc in tool_calls:
if not isinstance(tc, dict):
continue
tc_id = tc.get("id", "")
events.append(_make("tool.requested", agent_id, turn_index, {
"tool_name": tc.get("name", ""),
"tool_call_id": tc_id,
"args": _summarize_args(tc.get("args")),
}, source_event_id=f"{msg_id}:{tc_id}" if msg_id and tc_id else None))
if content:
text = _extract_text(content)
if text:
events.append(_make("agent.message.delta", agent_id, turn_index, {"text": text}, source_event_id=msg_id))
elif msg_type == "tool":
tc_id = msg.get("tool_call_id", "")
status = msg.get("status", "completed")
event_type = "tool.completed" if status != "error" else "tool.failed"
events.append(_make(event_type, agent_id, turn_index, {
"tool_name": msg.get("name", ""),
"tool_call_id": tc_id,
"content_preview": _truncate(_extract_text(content), 500),
"status": status,
}, source_event_id=f"tool:{tc_id}" if tc_id else None))
return events
def _normalize_updates(data: Any, agent_id: str, turn_index: int) -> list[dict[str, Any]]:
"""Handle ``updates`` SSE event (node completion with full output).
Only emits tool lifecycle events from structured data. Does NOT guess
skill execution from text content.
"""
events: list[dict[str, Any]] = []
if not isinstance(data, dict):
return events
for node_name, node_output in data.items():
if not isinstance(node_output, dict):
continue
messages = node_output.get("messages")
if not isinstance(messages, list):
continue
for msg in messages:
if not isinstance(msg, dict):
continue
msg_type = msg.get("type") or msg.get("role") or ""
if msg_type in ("ai", "assistant"):
tool_calls = msg.get("tool_calls")
if tool_calls:
for tc in tool_calls:
if not isinstance(tc, dict):
continue
tc_id = tc.get("id", "")
events.append(_make("tool.started", agent_id, turn_index, {
"tool_name": tc.get("name", ""),
"tool_call_id": tc_id,
"node": node_name,
}, source_event_id=f"upd:{tc_id}" if tc_id else None))
elif msg_type == "tool":
tc_id = msg.get("tool_call_id", "")
status = msg.get("status", "completed")
event_type = "tool.completed" if status != "error" else "tool.failed"
events.append(_make(event_type, agent_id, turn_index, {
"tool_name": msg.get("name", ""),
"tool_call_id": tc_id,
"content_preview": _truncate(_extract_text(msg.get("content")), 500),
"status": status,
"node": node_name,
}, source_event_id=f"upd:tool:{tc_id}" if tc_id else None))
return events
def _extract_text(content: Any) -> str:
if isinstance(content, str):
return content
if isinstance(content, list):
parts = []
for p in content:
if isinstance(p, dict) and p.get("type") == "text":
parts.append(p.get("text", ""))
elif isinstance(p, str):
parts.append(p)
return "\n".join(parts)
return ""
def _truncate(text: str, max_len: int) -> str:
if len(text) <= max_len:
return text
return text[:max_len] + "..."
def _summarize_args(args: Any) -> dict[str, Any] | None:
if not isinstance(args, dict):
return None
from app.maf_roundtable.sanitize import sanitize
result = sanitize(args)
return result if isinstance(result, dict) else None
@@ -0,0 +1,333 @@
"""Controlled DeerFlow runtime invocation client for MAF roundtable.
All invocations require an explicit ``ExecutionPrincipal`` — the server-generated
identity derived ONLY from the authenticated MAF session owner. No raw tokens,
cookies, or credentials ever pass into events, checkpoints, or prompts.
Two invocation modes (the adapter uses mode 2):
1. Direct checkpointer access for thread creation and message reads.
2. In-process ``start_run`` via a typed internal request that carries the
principal's user identity (never ``user=None``).
Security invariants:
- ExecutionPrincipal is constructed ONLY from the MAF session's user_id.
- The internal request object explicitly carries the principal's user so
downstream code sees a real identity, not a None placeholder.
- Agent access is enforced server-side (enforce_access=True).
"""
from __future__ import annotations
import logging
import uuid
from dataclasses import dataclass
from datetime import UTC, datetime
from typing import Any
from langgraph.checkpoint.base import empty_checkpoint
from deerflow.runtime.user_context import reset_current_user, set_current_user
logger = logging.getLogger(__name__)
def _serialize_tool_result(result: Any) -> Any:
"""Convert a tool result to a JSON-safe dict/list/str/int/float/bool/None."""
if result is None:
return None
if isinstance(result, (str, int, float, bool)):
return result
if isinstance(result, (list, tuple)):
return [_serialize_tool_result(v) for v in result]
if isinstance(result, dict):
return {str(k): _serialize_tool_result(v) for k, v in result.items()}
return str(result)[:1000]
@dataclass(frozen=True)
class ExecutionPrincipal:
"""Server-generated execution identity for a MAF seat run.
Constructed ONLY from the authenticated MAF session owner. Never from
request body, query params, or client-supplied data.
"""
user_id: str
session_id: str
run_id: str
def __post_init__(self) -> None:
if not self.user_id or not self.user_id.strip():
raise ValueError("ExecutionPrincipal requires a non-empty user_id")
class _PrincipalUser:
"""Minimal CurrentUser protocol implementation backed by ExecutionPrincipal."""
def __init__(self, principal: ExecutionPrincipal) -> None:
self.id = principal.user_id
class _InternalState:
"""Typed state container for the internal run request.
Carries the principal's user identity explicitly — never None — so
downstream access checks and run metadata attribution work correctly.
"""
def __init__(self, principal: ExecutionPrincipal) -> None:
self.user = _PrincipalUser(principal)
self.auth = None
@dataclass
class _InternalRunRequest:
"""Typed internal request for in-process agent run invocation.
Replaces the former ``SimpleNamespace(app=..., state=SimpleNamespace(user=None))``
pattern. The state explicitly carries the principal's user identity.
"""
app: Any
state: _InternalState
@classmethod
def from_principal(cls, app: Any, principal: ExecutionPrincipal) -> _InternalRunRequest:
return cls(app=app, state=_InternalState(principal))
class DeerFlowRuntimeClient:
"""Controlled entry point for invoking the DeerFlow Agent Runtime from MAF.
All calls require an ExecutionPrincipal. The client:
- Sets the user ContextVar before each invocation.
- Creates threads with proper user attribution.
- Invokes start_run with server-generated identity.
- Never passes raw tokens or credentials downstream.
"""
def __init__(self, app: Any) -> None:
self._app = app
@property
def app(self) -> Any:
return self._app
async def create_thread(self, principal: ExecutionPrincipal) -> str:
"""Create a DeerFlow thread owned by the principal's user.
The user ContextVar is set so thread_store.create records the correct
user_id in thread_meta.
"""
token = set_current_user(_PrincipalUser(principal))
try:
checkpointer = self._app.state.checkpointer
thread_store = self._app.state.thread_store
thread_id = str(uuid.uuid4())
await thread_store.create(
thread_id,
assistant_id=None,
metadata={
"thread_type": "maf_roundtable",
"system": True,
"maf_session_id": principal.session_id,
"maf_run_id": principal.run_id,
},
)
config = {"configurable": {"thread_id": thread_id, "checkpoint_ns": ""}}
await checkpointer.aput(
config,
empty_checkpoint(),
{"step": -1, "source": "input", "writes": None, "parents": {}, "created_at": datetime.now(UTC).isoformat()},
{},
)
return thread_id
finally:
reset_current_user(token)
async def start_agent_run(
self,
principal: ExecutionPrincipal,
*,
thread_id: str,
agent_id: str,
message: str,
model_name: str | None = None,
reasoning_effort: str | None = None,
thinking_enabled: bool = True,
subagent_enabled: bool = False,
excluded_tools: list[str] | None = None,
memory_recall_disabled: bool | None = None,
memory_injection_enabled: bool | None = None,
turn_index: int = 0,
capability_snapshot: dict[str, Any] | None = None,
write_policy: str = "confirm_high_risk",
approved_tool: str | None = None,
approved_action_id: str | None = None,
) -> Any:
"""Start a DeerFlow agent run under the principal's identity.
Returns the RunRecord (with .task and .run_id). The caller must await
the task and handle exceptions.
WriteGuard activation: when ``write_policy != "auto"`` the run context
carries ``maf_run_id`` (the activation flag the WriteGuard middleware
checks) plus the per-run data the interceptor needs to record a
pending action. ``excluded_tools`` here MUST only contain tools the
user explicitly disabled — write tools are no longer excluded (the
middleware intercepts them instead, keeping them visible to the model).
"""
from app.gateway.routers.thread_runs import RunCreateRequest
from app.gateway.services import RUN_SCOPE_BACKGROUND_CHILD, start_run
context: dict[str, Any] = {
"agent_name": agent_id,
"model_name": model_name or "",
"mode": "pro",
"reasoning_effort": reasoning_effort or "medium",
"thinking_enabled": thinking_enabled,
"is_plan_mode": False,
"subagent_enabled": subagent_enabled,
"thread_id": thread_id,
}
if memory_recall_disabled is not None:
context["memory_recall_disabled"] = memory_recall_disabled
if memory_injection_enabled is not None:
context["memory_injection_enabled"] = memory_injection_enabled
# WriteGuard activation + per-run data (server-generated identity only).
# ``maf_run_id`` is the flag the WriteGuard middleware checks to decide
# whether to intercept; the rest is the data the interceptor reads.
context["maf_run_id"] = principal.run_id
context["maf_session_id"] = principal.session_id
context["maf_user_id"] = principal.user_id
context["agent_id"] = agent_id
context["turn_index"] = turn_index
context["write_policy"] = write_policy
if capability_snapshot is not None:
context["capability_snapshot"] = capability_snapshot
# Post-approval deterministic execution: when set, the WriteGuard
# middleware passes this single tool through without interception.
# ``maf_approved_action_id`` binds the passthrough to a specific
# approved action — the middleware validates both tool name AND
# action_id so a model calling another tool with the same name is
# still intercepted (defense-in-depth when combined with direct
# tool execution that bypasses the LLM).
if approved_tool:
context["maf_approved_tool"] = approved_tool
if approved_action_id:
context["maf_approved_action_id"] = approved_action_id
body = RunCreateRequest(
assistant_id="lead_agent",
input={"messages": [{"type": "human", "content": [{"type": "text", "text": message}], "additional_kwargs": {}}]},
metadata={"run_scope": RUN_SCOPE_BACKGROUND_CHILD, "maf_run_id": principal.run_id},
config={"recursion_limit": 1000},
context=context,
excluded_tools=excluded_tools or [],
on_disconnect="continue",
multitask_strategy="reject",
)
# Typed internal request carrying the principal's identity — never user=None.
request = _InternalRunRequest.from_principal(self._app, principal)
token = set_current_user(_PrincipalUser(principal))
try:
record = await start_run(
body,
thread_id,
request,
run_scope=RUN_SCOPE_BACKGROUND_CHILD,
)
return record
finally:
reset_current_user(token)
async def read_thread_messages(self, principal: ExecutionPrincipal, thread_id: str) -> list[dict[str, Any]]:
"""Read the latest checkpoint messages from a thread."""
from deerflow.runtime.serialization import serialize_channel_values
token = set_current_user(_PrincipalUser(principal))
try:
checkpointer = self._app.state.checkpointer
config = {"configurable": {"thread_id": thread_id, "checkpoint_ns": ""}}
ct = await checkpointer.aget_tuple(config)
if ct is None:
return []
checkpoint = getattr(ct, "checkpoint", {}) or {}
values = serialize_channel_values(checkpoint.get("channel_values", {}) or {})
return values.get("messages") or []
finally:
reset_current_user(token)
async def execute_tool_directly(
self,
*,
thread_id: str,
agent_id: str,
tool_name: str,
params: dict[str, Any],
principal: ExecutionPrincipal,
turn_index: int,
capability_snapshot: dict[str, Any] | None,
write_policy: str,
approved_action_id: str,
action_record: dict[str, Any] | None,
model_name: str | None = None,
excluded_tools: list[str] | None = None,
) -> dict[str, Any]:
"""Execute a DeerFlow tool directly without LLM involvement.
For post-approval deterministic execution this delegates to the harness
``execute_approved_tool``, which runs the call through the **real**
LangGraph ``ToolNode`` / ``ToolRuntime`` / middleware chain (state
recovered from the thread checkpoint), not a faked runtime. No raw
params enter any prompt, checkpoint, or model context.
Returns ``{"status": "succeeded", "result": ...}`` or
``{"status": "failed", "error": "..."}``. A security rejection
(unauthorized / disabled / nonexistent tool, context mismatch) is a
``failed`` outcome and the tool executes 0 times.
"""
from deerflow.config import get_app_config
from deerflow.tools.approved_tool_executor import execute_approved_tool
app_config = get_app_config()
checkpointer = getattr(self._app.state, "checkpointer", None)
store = getattr(self._app.state, "store", None)
return await execute_approved_tool(
app_config=app_config,
checkpointer=checkpointer,
store=store,
thread_id=thread_id,
user_id=principal.user_id,
session_id=principal.session_id,
run_id=principal.run_id,
agent_id=agent_id,
turn_index=turn_index,
model_name=model_name,
excluded_tools=excluded_tools,
capability_snapshot=capability_snapshot,
write_policy=write_policy,
tool_name=tool_name,
params=params,
approved_action_id=approved_action_id,
action_record=action_record,
)
async def cancel_run(self, deerflow_run_id: str) -> bool:
"""Cancel a DeerFlow run by its run_id."""
run_manager = getattr(self._app.state, "run_manager", None)
if run_manager is None:
return False
try:
await run_manager.cancel(deerflow_run_id, action="interrupt")
return True
except Exception as exc: # noqa: BLE001
# Log only the exception type — never the raw message/traceback,
# which may carry params or credentials.
logger.warning(
"cancel DeerFlow run %s failed (%s)", deerflow_run_id, type(exc).__name__
)
return False
@@ -0,0 +1,103 @@
"""Recursive sanitization for MAF roundtable events, payloads, and logs.
Strips credentials, tokens, cookies, passwords, secrets, and API keys from
nested data structures before they reach the event store, context builder,
or log output. Applied uniformly to tool arguments, tool results, fact
ledger entries, and event payloads.
Design:
- Pure functions, no I/O.
- Recursive: handles nested dicts, lists, and strings.
- Key-based: redacts values whose key matches a sensitive pattern.
- Value-based: redacts string values that look like tokens/keys.
- Never raises: malformed input passes through unchanged (best-effort).
"""
from __future__ import annotations
import re
from typing import Any
_SENSITIVE_KEYS = frozenset({
"token", "access_token", "refresh_token", "id_token",
"authorization", "auth", "auth_token", "authtoken",
"cookie", "cookies", "set-cookie",
"password", "passwd", "pwd",
"secret", "secret_key", "client_secret",
"api_key", "apikey", "api-key",
"private_key", "private-key",
"credential", "credentials",
"session_id", "sessionid",
"x-api-key", "x-auth-token",
})
_KEY_PATTERN = re.compile(
r"(token|authorization|cookie|password|passwd|secret|api[_-]?key|private[_-]?key|credential|bearer)",
re.IGNORECASE,
)
_VALUE_PATTERNS = [
re.compile(r"^Bearer\s+\S+", re.IGNORECASE),
re.compile(r"^(sk|pk|ak|rk)[_-][A-Za-z0-9]{16,}$"),
re.compile(r"^eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}"),
re.compile(r"^[A-Za-z0-9+/]{40,}={0,2}$"),
]
_INLINE_SECRET_PATTERN = re.compile(
r"(token|password|passwd|secret|api[_-]?key|authorization|cookie)\s*[=:]\s*\S+",
re.IGNORECASE,
)
_REDACTED = "***REDACTED***"
_MAX_DEPTH = 12
def sanitize(data: Any, *, _depth: int = 0) -> Any:
"""Recursively sanitize sensitive fields from a data structure."""
if _depth > _MAX_DEPTH:
return data
if isinstance(data, dict):
return _sanitize_dict(data, _depth)
if isinstance(data, (list, tuple)):
return [sanitize(item, _depth=_depth + 1) for item in data]
if isinstance(data, str):
return _sanitize_value_str(data)
return data
def sanitize_payload(payload: dict[str, Any] | None) -> dict[str, Any] | None:
"""Sanitize an event payload dict. Returns None if input is None."""
if payload is None:
return None
result = sanitize(payload)
return result if isinstance(result, dict) else payload
def _sanitize_dict(d: dict[str, Any], depth: int) -> dict[str, Any]:
out: dict[str, Any] = {}
for key, value in d.items():
key_lower = str(key).lower().replace("-", "_")
if key_lower in _SENSITIVE_KEYS or _KEY_PATTERN.search(key_lower):
out[key] = _REDACTED
elif isinstance(value, dict):
out[key] = _sanitize_dict(value, depth + 1)
elif isinstance(value, (list, tuple)):
out[key] = [sanitize(item, _depth=depth + 1) for item in value]
elif isinstance(value, str):
out[key] = _sanitize_value_str(value)
else:
out[key] = value
return out
def _sanitize_value_str(s: str) -> str:
# Never skip sanitization based on length — long strings (error traces,
# log dumps, seat-run errors) may embed credentials deep inside.
for pat in _VALUE_PATTERNS:
if pat.match(s):
return _REDACTED
if _INLINE_SECRET_PATTERN.search(s):
return _INLINE_SECRET_PATTERN.sub(
lambda m: m.group(0).split("=")[0].split(":")[0] + "=***REDACTED***", s
)
return s
@@ -30,8 +30,8 @@ class ParticipantInput(BaseModel):
display_name: str = Field(default="", max_length=255)
role: MafParticipantRole = "seat"
sort_order: int = 0
# Frozen at creation — the agent's tools / skills snapshot.
capability_snapshot: dict[str, Any] | None = None
# Subtractive only: tools removed from the server-resolved allow-list for this seat.
excluded_tools: list[str] = Field(default_factory=list)
class CreateSessionRequest(BaseModel):
@@ -48,8 +48,8 @@ class CreateSessionRequest(BaseModel):
# Optional: omitted → MafRoundtableConfig.default_write_policy.
write_policy: MafWritePolicy | None = None
participants: list[ParticipantInput] = Field(default_factory=list)
# Frozen at creation — the full session capability snapshot (agents + tools + skills).
capability_snapshot: dict[str, Any] | None = None
# Subtractive session-wide tool exclusions (applied per seat when building snapshot).
excluded_tools: list[str] = Field(default_factory=list)
# Fields that must not be explicitly set to null on PUT (→ 422).
@@ -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(
@@ -0,0 +1,235 @@
"""Deterministic post-approval tool executor for the MAF roundtable.
After a human approves an external-write action, this executor calls the
approved DeerFlow tool **directly** with the **decrypted original params** —
no model free-will, no re-decision, no raw params in any prompt or checkpoint.
It is invoked by ``WorkflowRunner.resume()`` instead of re-running an LLM seat
turn (which would let the model pick different arguments or a different tool).
Design — direct tool invocation
-------------------------------
1. **Atomic occupy** (``approved → running``): only the caller whose
conditional UPDATE affects one row wins the right to execute. Concurrent
``resume()`` or post-restart replay finds the row already ``running`` or
terminal and bails out — at-most-once execution is guaranteed at the DB
level, not by locking.
2. **Direct tool call**: decrypts approved params (server-only), looks up the
tool in DeerFlow's registry, builds a minimal ToolRuntime from the thread's
persisted state (sandbox/thread_data), and calls ``tool.func()`` or
``tool.ainvoke()`` directly. The LLM is never involved.
3. **Authority**: the approved ``action_id`` is carried in the runtime context
so the WriteGuard middleware can validate both tool name AND action_id as
defense-in-depth (though the LLM is bypassed, so this is purely a secondary
check).
4. **Outcome recording**: ``succeeded`` / ``failed`` / ``unknown`` are
recorded via the state-machine-constrained ``record_terminal_result``
(only ``running → terminal``). ``unknown`` prohibits auto-retry.
Security: the decrypted params are read server-side from the encrypted secret
and never leave this process. They do NOT appear in prompts, checkpoints,
events, or API responses.
"""
from __future__ import annotations
import logging
from typing import Any
from app.maf_roundtable.action_coordinator import ActionCoordinator
from app.maf_roundtable.sanitize import sanitize
logger = logging.getLogger(__name__)
class ToolExecutor:
"""Executes an approved external-write action deterministically.
Constructed per-resume from the ``WorkflowRunner``; takes the already-built
adapter + coordinator + runtime client so it reuses identity / sandbox /
middleware wiring.
"""
def __init__(
self,
*,
adapter: Any,
action_coordinator: ActionCoordinator,
user_id: str,
) -> None:
self._adapter = adapter
self._coordinator = action_coordinator
self._user_id = user_id
async def execute(
self,
*,
action_id: str,
session_id: str,
run_id: str,
agent_id: str,
thread_id: str,
approved_tool: str,
capability_snapshot: dict[str, Any] | None = None,
write_policy: str = "confirm_high_risk",
model_name: str | None = None,
excluded_tools: list[str] | None = None,
) -> dict[str, Any]:
"""Execute the approved tool deterministically and record the outcome.
Returns::
{"status": "succeeded"|"failed"|"skipped"|"unknown", ...}
``skipped`` means another caller already occupied/finished the action
(at-most-once) — the caller should return the existing result.
The approved params are recovered **server-side** from the encrypted
action secret *after* the atomic occupy. If the secret is missing or
cannot be decrypted, ``ActionSecretUnavailableError`` is raised by the
coordinator and turned into a terminal ``failed`` outcome here — the
tool is NEVER called with empty params (no ``params or {}`` fallback),
so the external side effect happens exactly zero times.
The actual call is delegated to the harness ``execute_approved_tool``
(real ``ToolNode`` / ``ToolRuntime`` / middleware chain), rebuilt from
the seat's frozen capability snapshot / model / ``excluded_tools``. The
stored action record is passed so the harness can verify run/session/
agent/tool consistency before executing.
"""
# 1. Atomic occupy — only the winner ("claimed") proceeds to execute.
# A lost claim reflects the action's ACTUAL state (in_progress /
# terminal) rather than a blanket "skip", so the caller can keep the
# parent run running while another executor finishes it.
from deerflow.persistence.maf_roundtable.actions import (
MafActionStateMachineError,
)
try:
claim = await self._coordinator.occupy_for_execution(action_id)
except MafActionStateMachineError as exc:
logger.error(
"ToolExecutor: action %s cannot be claimed: %s", action_id, exc,
)
return {"status": "failed", "error": f"action state machine error: {exc}"}
if claim != "claimed":
existing = await self._coordinator._store.actions.get_action(action_id) # noqa: SLF001
if claim == "in_progress":
logger.info(
"ToolExecutor: action %s already running elsewhere (in_progress)",
action_id,
)
return {"status": "in_progress", "action": existing}
logger.info(
"ToolExecutor: action %s already terminal (%s) — at-most-once",
action_id, claim,
)
return {"status": claim, "action": existing}
if not approved_tool:
await self._coordinator.record_result(
action_id, status="failed",
result={"error": "no approved tool name — cannot execute"},
)
return {"status": "failed", "error": "no approved tool name"}
# 2. Recover the approved params from the server-only encrypted secret.
# A missing/undecryptable/invalid secret is a HARD failure: record
# the action failed and never invoke the tool (execution count == 0).
from app.maf_roundtable.action_coordinator import ActionSecretUnavailableError
try:
params = await self._coordinator.get_approved_action_params(action_id)
except ActionSecretUnavailableError as exc:
safe_msg = str(sanitize(exc.detail))[:500]
logger.error(
"ToolExecutor: action %s params unavailable (%s): %s",
action_id, exc.reason, safe_msg,
)
await self._coordinator.record_result(
action_id, status="failed",
result={"error": f"action secret unavailable: {exc.reason}"},
)
return {"status": "failed", "error": safe_msg}
# 3. Read the stored action record (authoritative turn_index + the
# run/session/agent/tool the harness will verify against).
action_record = await self._coordinator._store.actions.get_action(action_id) # noqa: SLF001
turn_index = int((action_record or {}).get("turn_index") or 0)
# 4. Execute via the real DeerFlow tool path — no LLM, no prompt
# injection. The raw params are read from the encrypted secret and
# passed straight to the tool; they never enter any model context.
from app.maf_roundtable.runtime_client import ExecutionPrincipal
principal = ExecutionPrincipal(
user_id=self._user_id,
session_id=session_id,
run_id=run_id,
)
client = self._adapter._client # noqa: SLF001 — DeerFlowRuntimeClient
try:
outcome = await client.execute_tool_directly(
thread_id=thread_id,
agent_id=agent_id,
tool_name=approved_tool,
params=params,
principal=principal,
turn_index=turn_index,
capability_snapshot=capability_snapshot,
write_policy=write_policy,
model_name=model_name,
excluded_tools=excluded_tools,
approved_action_id=action_id,
action_record=action_record,
)
except Exception as exc:
safe_msg = str(sanitize(str(exc)))[:500]
logger.error(
"ToolExecutor: direct tool call '%s' raised: %s",
approved_tool, safe_msg,
)
await self._coordinator.record_result(
action_id, status="failed", result={"error": safe_msg},
)
return {"status": "failed", "error": safe_msg}
# 5. Record terminal result (state-machine constrained: only
# running → terminal; a lost race is a no-op).
outcome_status = outcome.get("status")
if outcome_status == "succeeded":
await self._coordinator.record_result(
action_id, status="succeeded",
result={"tool_result": outcome.get("result")},
)
return {"status": "succeeded", "tool_result": outcome.get("result")}
elif outcome_status == "unknown":
# Inconclusive external result (timeout / disconnect / gateway):
# record ``unknown`` — never auto-retry, a human must reconcile.
error = outcome.get("error", "inconclusive external result")
await self._coordinator.record_result(
action_id, status="unknown", result={"error": error},
)
return {"status": "unknown", "error": error}
else:
error = outcome.get("error", "tool execution failed")
await self._coordinator.record_result(
action_id, status="failed", result={"error": error},
)
return {"status": "failed", "error": error}
async def record_unknown(self, action_id: str, *, reason: str) -> None:
"""Record an ``unknown`` outcome (network timeout / inconclusive).
``unknown`` prohibits auto-retry — the action stays in ``unknown``
until a human reconciles it.
"""
logger.warning(
"ToolExecutor: action %s outcome unknown — %s (no auto-retry)",
action_id, reason,
)
await self._coordinator.record_result(
action_id, status="unknown", result={"reason": reason},
)
@@ -0,0 +1,606 @@
"""MAF Workflow node executors for the roundtable experiment.
Each executor is a real MAF ``Executor`` subclass instance. Every seat gets
its own executor bound to a fixed ``agent_id`` — no shared function that
guesses the current speaker from input metadata.
Executors delegate to ``DeerFlowAgentAdapter.run_seat_turn()`` for actual
model/tool execution and emit MAF events via the adapter.
Nodes:
- CoordinatorExecutor: decides which seat speaks next, whether to continue.
- SeatExecutor (one per seat): runs one seat turn via DeerFlowAgentAdapter.
- ApprovalGateExecutor: pauses for external-write approval before proceeding.
- FinalizerExecutor: generates the final synthesis and ends the run.
"""
from __future__ import annotations
import logging
from typing import Any
from agent_framework import Executor, WorkflowContext, handler
from app.maf_roundtable.action_coordinator import (
ActionCoordinator,
classify_tool,
tool_needs_approval,
)
from app.maf_roundtable.context_builder import build_manager_synthesis_input
logger = logging.getLogger(__name__)
class WriteGuardConfigurationError(RuntimeError):
"""Raised when WriteGuard should have intercepted a write tool but didn't.
Indicates write_guard is misconfigured (not enabled or provider missing)
while a MAF run requires approval. The run is failed — we never fall back
to creating generic post-hoc approval records.
"""
# ── Serializable workflow state ─────────────────────────────────────────────
class RoundtableState:
"""Serializable shared state for the MAF roundtable workflow.
Persisted to the run's ``maf_checkpoint_json`` so the workflow survives
restarts and approval-pause/resume cycles.
"""
def __init__(
self,
*,
session_id: str,
run_id: str,
task_text: str,
mode: str,
model_name: str | None,
reasoning_effort: str | None,
max_rounds: int,
write_policy: str,
manager_agent_id: str | None,
seat_agent_ids: list[str],
thread_map: dict[str, str],
capability_snapshot: dict[str, Any] | None = None,
) -> None:
self.session_id = session_id
self.run_id = run_id
self.task_text = task_text
self.mode = mode
self.model_name = model_name
self.reasoning_effort = reasoning_effort
self.max_rounds = max_rounds
self.write_policy = write_policy
self.manager_agent_id = manager_agent_id
self.seat_agent_ids = seat_agent_ids
self.thread_map = thread_map
self.capability_snapshot = capability_snapshot
self.current_round = 0
self.turn_results: list[dict[str, Any]] = []
self.fact_ledger: dict[str, Any] = {
"confirmed_facts": [],
"tool_results": [],
"conflicts": [],
"pending_actions": [],
}
self.final_result: dict[str, Any] | None = None
self.status = "running"
self.pending_approvals: list[dict[str, Any]] = []
def to_dict(self) -> dict[str, Any]:
return {
"session_id": self.session_id,
"run_id": self.run_id,
"task_text": self.task_text,
"mode": self.mode,
"model_name": self.model_name,
"reasoning_effort": self.reasoning_effort,
"max_rounds": self.max_rounds,
"write_policy": self.write_policy,
"manager_agent_id": self.manager_agent_id,
"seat_agent_ids": self.seat_agent_ids,
"thread_map": self.thread_map,
"capability_snapshot": self.capability_snapshot,
"current_round": self.current_round,
"turn_results": self.turn_results,
"fact_ledger": self.fact_ledger,
"final_result": self.final_result,
"status": self.status,
"pending_approvals": self.pending_approvals,
}
@classmethod
def from_dict(cls, d: dict[str, Any]) -> RoundtableState:
state = cls(
session_id=d["session_id"],
run_id=d["run_id"],
task_text=d["task_text"],
mode=d["mode"],
model_name=d.get("model_name"),
reasoning_effort=d.get("reasoning_effort"),
max_rounds=d.get("max_rounds", 8),
write_policy=d.get("write_policy", "confirm_high_risk"),
manager_agent_id=d.get("manager_agent_id"),
seat_agent_ids=d.get("seat_agent_ids", []),
thread_map=d.get("thread_map", {}),
capability_snapshot=d.get("capability_snapshot"),
)
state.current_round = d.get("current_round", 0)
state.turn_results = d.get("turn_results", [])
state.fact_ledger = d.get("fact_ledger", state.fact_ledger)
state.final_result = d.get("final_result")
state.status = d.get("status", "running")
state.pending_approvals = d.get("pending_approvals", []) or d.get("pending_approval") and [d["pending_approval"]] or []
return state
# ── Coordinator executor ────────────────────────────────────────────────────
class CoordinatorExecutor(Executor):
"""Decides which seat speaks next, whether to continue or finish."""
def __init__(self, adapter: Any, state: RoundtableState) -> None:
super().__init__(id="coordinator")
self._adapter = adapter
self._state = state
@handler(input=Any, output=dict)
async def handle(self, message: Any, ctx: WorkflowContext) -> None:
self._state.current_round += 1
if self._state.current_round > self._state.max_rounds:
await ctx.send_message({"decision": "done", "reason": "max_rounds_reached"})
return
if self._state.mode == "structured":
if self._state.current_round == 1:
await ctx.send_message({"decision": "parallel_seats", "agents": self._state.seat_agent_ids})
return
await ctx.send_message({"decision": "done", "reason": "structured_complete"})
return
# group_chat: round-robin speaker selection
remaining = [
a for a in self._state.seat_agent_ids
if not any(
r.get("agent_id") == a and r.get("turn_index", 0) >= self._state.current_round - 1
for r in self._state.turn_results
)
]
if not remaining:
await ctx.send_message({"decision": "done", "reason": "all_seats_spoke"})
return
next_agent = remaining[(self._state.current_round - 1) % len(remaining)]
await self._adapter._emit_critical(self._state.run_id, {
"event_type": "manager.decision",
"agent_id": self._state.manager_agent_id or "coordinator",
"turn_index": self._state.current_round,
"payload": {"next_speaker": next_agent, "reason": "round_robin", "round": self._state.current_round},
})
await ctx.send_message({"decision": "next_speaker", "agent_id": next_agent})
# ── Seat executor (one instance per seat) ───────────────────────────────────
class SeatExecutor(Executor):
"""Runs one seat turn via DeerFlowAgentAdapter.
Each instance is bound to a fixed ``agent_id`` — the MAF workflow routes
to the correct seat executor by edge, not by guessing from input.
Phase-2 fix: write tools are NO LONGER excluded from the seat run. The
WriteGuard middleware (harness layer) intercepts them at execution time
via ``wrap_tool_call``/``awrap_tool_call`` when the run context carries a
``maf_run_id`` flag. The model therefore SEES the write-tool schema and
can propose the call, but the real tool never executes before approval.
``excluded_tools`` now only contains tools the user explicitly disabled
(from the capability snapshot). The post-turn capture is retained solely
to surface the intercepted calls in the run state / pending approval.
"""
def __init__(self, adapter: Any, state: RoundtableState, agent_id: str, *, action_coordinator: ActionCoordinator | None = None) -> None:
super().__init__(id=f"seat_{agent_id}")
self._adapter = adapter
self._state = state
self._agent_id = agent_id
self._action_coordinator = action_coordinator
@handler(input=Any, output=dict)
async def handle(self, message: Any, ctx: WorkflowContext) -> None:
thread_id = self._state.thread_map.get(self._agent_id, "")
if not thread_id:
await ctx.send_message({"error": f"no thread for agent {self._agent_id}", "agent_id": self._agent_id})
return
prior_turns = [
{"agent_id": r["agent_id"], "turn_index": r["turn_index"], "summary": r.get("content", "")[:500]}
for r in self._state.turn_results
]
# Read ALL capabilities from the frozen snapshot — never default-disable.
caps = _agent_capabilities_from_snapshot(self._state.capability_snapshot, self._agent_id)
# Phase-2: excluded_tools contains ONLY user-disabled tools. Write tools
# that need approval are no longer excluded — the WriteGuard middleware
# intercepts them at execution time so the model still sees the schema.
excluded = list(caps.get("excluded_tools", []))
response = await self._adapter.run_seat_turn(
session_id=self._state.session_id,
run_id=self._state.run_id,
agent_id=self._agent_id,
turn_index=self._state.current_round,
message=self._state.task_text,
thread_id=thread_id,
model_name=caps.get("model_name") or self._state.model_name,
reasoning_effort=caps.get("reasoning_effort") or self._state.reasoning_effort,
thinking_enabled=caps.get("thinking_enabled", True),
subagent_enabled=caps.get("subagent_enabled", False),
task_text=self._state.task_text,
stage_instruction=f"第{self._state.current_round}轮分析",
prior_turns=prior_turns,
fact_ledger=self._state.fact_ledger,
excluded_tools=excluded,
memory_recall_disabled=caps.get("memory_recall_disabled"),
memory_injection_enabled=caps.get("memory_injection_enabled"),
capability_snapshot=self._state.capability_snapshot,
write_policy=self._state.write_policy,
)
# Phase-2: the WriteGuard middleware already created pending actions for
# intercepted write tools during the run (inside DeerFlow). We now read
# the waiting_approval actions that match THIS agent + THIS turn to
# surface the pending approval in the workflow state so the ApprovalGate
# can pause. No action creation here.
if response.tool_calls and self._state.write_policy != "auto":
pending_calls = [
tc for tc in response.tool_calls
if tc.get("name") and tool_needs_approval(
tc.get("name"), self._state.write_policy,
self._state.capability_snapshot, self._agent_id,
)
]
if pending_calls:
all_actions = await self._store.actions.list_actions(
run_id=self._state.run_id, status="waiting_approval"
)
# P1-5/P1b: candidate actions are scoped to this run + agent +
# THIS turn (never an earlier turn's waiting actions).
turn_actions = [
a for a in all_actions
if a.get("agent_id") == self._agent_id
and a.get("turn_index") == self._state.current_round
]
# Every pending tool call must match EXACTLY one action, by
# tool_call_id (logical_action_id); fall back to tool_name only
# when the call carries no id. Any count/ID mismatch is a hard
# failure — we never guess which action a call maps to.
matched: list[dict[str, Any]] = []
for tc in pending_calls:
tc_id = tc.get("id") or ""
tc_name = tc.get("name", "")
if tc_id:
hits = [
a for a in turn_actions
if (a.get("logical_action_id") or "") == tc_id
]
else:
hits = [
a for a in turn_actions
if a.get("tool_name") == tc_name
and not a.get("logical_action_id")
]
if len(hits) != 1:
raise RuntimeError(
f"seat {self._agent_id} turn {self._state.current_round}: "
f"pending tool call '{tc_name}' (id={tc_id or '<none>'}) matched "
f"{len(hits)} waiting actions (expected exactly 1) — refusing to guess"
)
matched.append(hits[0])
self._state.pending_approvals = [
{
"action_id": a["id"],
"approval_id": a.get("approval_id", ""),
"agent_id": self._agent_id,
"tool_name": a.get("tool_name", ""),
"turn_index": self._state.current_round,
}
for a in matched
]
self._state.turn_results.append({
"agent_id": self._agent_id,
"turn_index": self._state.current_round,
"content": response.content,
"tool_calls": response.tool_calls,
"error": response.error,
"usage": response.usage,
})
if response.tool_calls:
for tc in response.tool_calls:
tc_name = tc.get("name", "")
is_intercepted = any(
a.get("tool_name") == tc_name
for a in (self._state.pending_approvals or [])
)
self._state.fact_ledger["tool_results"].append({
"tool_name": tc_name,
"status": "waiting_approval" if is_intercepted else "completed",
"agent_id": self._agent_id,
})
# SDK/API errors must fail the run, never silently complete.
if response.error:
raise RuntimeError(
f"seat {self._agent_id} turn {self._state.current_round} failed: {response.error}"
)
await ctx.send_message({"agent_id": self._agent_id, "content": response.content, "error": response.error})
@property
def _store(self) -> Any:
return self._adapter._service.store
def _pending_write_calls(self, tool_calls: list[dict[str, Any]]) -> list[str]:
"""Return the names of write tool calls that the policy requires approval for."""
names: list[str] = []
for tc in tool_calls:
name = tc.get("name", "")
if name and tool_needs_approval(
name, self._state.write_policy, self._state.capability_snapshot, self._agent_id
):
names.append(name)
return names
# ── Approval gate executor ──────────────────────────────────────────────────
class ApprovalGateExecutor(Executor):
"""Pauses for external-write approval before proceeding.
When the write policy requires approval and a seat produced external write
tool calls, this executor:
1. Reads the pending approvals already created by WriteGuard (zero or more).
2. If none exist but the policy requires approval for detected write tools:
raises ``WriteGuardConfigurationError`` — the WriteGuard middleware
should have intercepted and recorded them. We NEVER fall back to
creating generic post-hoc actions.
3. Emits ``action.waiting_approval`` events.
4. Sets the run status to ``waiting_approval``.
On resume (after user approves), the workflow re-enters and this executor
checks the approval statuses. When all are decided, it routes to the
finalizer.
"""
def __init__(self, adapter: Any, state: RoundtableState, service: Any) -> None:
super().__init__(id="approval_gate")
self._adapter = adapter
self._state = state
self._service = service
@handler(input=Any, output=dict)
async def handle(self, message: Any, ctx: WorkflowContext) -> None:
# Check if we're resuming from a previous approval pause.
if self._state.pending_approvals:
all_decided = True
for pa in self._state.pending_approvals:
approval_id = pa.get("approval_id", "")
approval = await self._service.store.approvals.get_approval(approval_id)
if approval is None or approval["status"] == "pending":
all_decided = False
continue
if approval["status"] == "approved":
from app.maf_roundtable.event_normalizer import make_action_approved
await self._adapter._emit_critical(self._state.run_id, make_action_approved(
pa.get("agent_id", ""),
self._state.current_round,
action_id=pa.get("action_id", ""),
approval_id=approval_id,
decided_by=approval.get("decided_by", ""),
))
elif approval["status"] == "rejected":
from app.maf_roundtable.event_normalizer import make_action_rejected
await self._adapter._emit_critical(self._state.run_id, make_action_rejected(
pa.get("agent_id", ""),
self._state.current_round,
action_id=pa.get("action_id", ""),
approval_id=approval_id,
decided_by=approval.get("decided_by", ""),
))
if all_decided:
self._state.pending_approvals = []
await ctx.send_message({"decision": "approved"})
return
# Still pending — stay in waiting state.
await ctx.send_message({"decision": "waiting_approval"})
return
# First entry: check if any seat produced write tool calls needing approval.
needs_approval = self._check_needs_approval()
if not needs_approval:
await ctx.send_message({"decision": "approved", "policy": self._state.write_policy})
return
# P0-4: WriteGuard should already have created pending actions for every
# tool that needs approval. If we detect write tools that need approval
# but NO pending_approvals were set by the SeatExecutor, the WriteGuard
# middleware is misconfigured — fail the run rather than silently
# bypassing approval.
if not self._state.pending_approvals:
raise WriteGuardConfigurationError(
f"Write policy '{self._state.write_policy}' requires approval "
f"for detected write tools, but WriteGuard did not create any "
f"pending actions. Check that write_guard.enabled is true and "
f"the provider is configured in config.yaml."
)
# Update run status to waiting_approval.
await self._service.store.runs.update_run(self._state.run_id, {"status": "waiting_approval"})
await self._service.store.sessions.update_session(
self._state.session_id, user_id=self._adapter._user_id, fields={"status": "waiting_approval"}
)
await ctx.send_message({"decision": "waiting_approval"})
def _check_needs_approval(self) -> bool:
"""Check if the write policy requires approval for any pending tool calls.
P1: uses metadata-driven classification from the capability snapshot,
not name-prefix heuristics. Tools without metadata use a safe default
(requires approval).
"""
if self._state.write_policy == "auto":
return False
for result in self._state.turn_results:
for tc in result.get("tool_calls") or []:
name = tc.get("name", "")
if not name:
continue
if tool_needs_approval(name, self._state.write_policy, self._state.capability_snapshot):
return True
return False
# ── Finalizer executor ──────────────────────────────────────────────────────
async def generate_final_report(adapter: Any, state: RoundtableState) -> dict[str, Any]:
"""Run the manager synthesis (the MAF finalizer path) and set ``state.final_result``.
Shared by the in-graph ``FinalizerExecutor`` and ``WorkflowRunner.resume`` so
that a run which paused for approval still gets a real synthesized report
after its approved actions execute — resume must re-enter the finalizer
path, not merely flip ``state.status`` to ``completed``.
"""
from app.maf_roundtable.event_normalizer import make_run_completed
manager_id = state.manager_agent_id or "coordinator"
thread_id = state.thread_map.get(manager_id, "")
synthesis_input = build_manager_synthesis_input(
task_text=state.task_text,
seat_results=state.turn_results,
fact_ledger=state.fact_ledger,
)
if thread_id:
response = await adapter.run_seat_turn(
session_id=state.session_id,
run_id=state.run_id,
agent_id=manager_id,
turn_index=state.current_round + 1,
message=synthesis_input,
thread_id=thread_id,
model_name=state.model_name,
reasoning_effort=state.reasoning_effort,
task_text=synthesis_input,
stage_instruction="综合所有席位分析,生成最终结论",
)
state.final_result = {"content": response.content, "agent_id": manager_id}
else:
state.final_result = {"content": synthesis_input, "agent_id": manager_id, "note": "no_manager_thread"}
await adapter._emit_critical(state.run_id, make_run_completed(manager_id, state.current_round + 1, {
"total_rounds": state.current_round,
"seats_completed": len(state.turn_results),
}))
return state.final_result
class FinalizerExecutor(Executor):
"""Generates the final synthesis and ends the run."""
def __init__(self, adapter: Any, state: RoundtableState) -> None:
super().__init__(id="finalizer")
self._adapter = adapter
self._state = state
@handler(input=Any, workflow_output=dict)
async def handle(self, message: Any, ctx: WorkflowContext) -> None:
await generate_final_report(self._adapter, self._state)
self._state.status = "completed"
await ctx.yield_output({"final_result": self._state.final_result})
# ── Waiting terminal executor ───────────────────────────────────────────────
class WaitingTerminalExecutor(Executor):
"""Terminal executor for the approval-waiting path.
When the approval gate routes here, the workflow stops. The run stays in
``waiting_approval`` until the user decides, at which point the service
resumes the workflow from its checkpoint.
"""
def __init__(self) -> None:
super().__init__(id="waiting_terminal")
@handler(input=Any, workflow_output=dict)
async def handle(self, message: Any, ctx: WorkflowContext) -> None:
await ctx.yield_output({"status": "waiting_approval"})
# ── helpers ─────────────────────────────────────────────────────────────────
def _excluded_tools_from_snapshot(snapshot: dict[str, Any] | None, agent_id: str) -> list[str]:
"""Extract excluded_tools from the frozen capability snapshot for an agent."""
caps = _agent_capabilities_from_snapshot(snapshot, agent_id)
return caps.get("excluded_tools", [])
def _agent_capabilities_from_snapshot(snapshot: dict[str, Any] | None, agent_id: str) -> dict[str, Any]:
"""Extract ALL capabilities from the frozen snapshot for an agent.
Returns a dict with keys: model_name, reasoning_effort, thinking_enabled,
subagent_enabled, excluded_tools, memory_recall_disabled,
memory_injection_enabled, write_policy. Missing keys default to
permissive values (tools/skills/memory NOT disabled by default).
"""
if not snapshot:
return {}
agents = snapshot.get("agents")
if not isinstance(agents, list):
return {}
for a in agents:
if isinstance(a, dict) and a.get("agent_id") == agent_id:
return {
"model_name": a.get("model_name"),
"reasoning_effort": a.get("reasoning_effort"),
"thinking_enabled": a.get("thinking_enabled", True),
"subagent_enabled": a.get("subagent_enabled", False),
"excluded_tools": a.get("excluded_tools") or [],
"memory_recall_disabled": a.get("memory_recall_disabled"),
"memory_injection_enabled": a.get("memory_injection_enabled"),
"write_policy": a.get("write_policy"),
}
return {}
def _is_high_risk_tool(tool_name: str, snapshot: dict[str, Any] | None = None) -> bool:
"""Determine if a tool is high-risk using capability snapshot metadata.
P1 fix: no longer guesses risk from name prefixes (``create_`` /
``delete_`` etc.). Instead, reads the per-tool ``side_effect`` and
``risk_level`` from the frozen capability snapshot. Tools without
metadata use a **safe default** (R3 write → high-risk → requires approval).
"""
side_effect, risk_level = classify_tool(tool_name, snapshot)
if side_effect in ("read", "skill"):
return False
risk_order = {"R0": 0, "R1": 1, "R2": 2, "R3": 3, "R4": 4}
return risk_order.get(risk_level, 3) >= 3
@@ -0,0 +1,139 @@
"""MAF WorkflowBuilder graph construction for the roundtable experiment.
Creates real MAF Workflow graphs using the official SDK's WorkflowBuilder.
The SDK is imported lazily so the Gateway starts without it when the feature
flag is off.
Two topologies:
- ``structured``: coordinator → parallel seats → approval gate → finalizer
- ``group_chat``: coordinator loop (dynamic speaker selection) → finalizer
Each node is a real MAF ``Executor`` subclass instance (from
``workflow_executors.py``). The builder uses the SDK's actual API:
``WorkflowBuilder(start_executor=...)``, ``add_edge``, ``add_fan_out_edges``,
``add_fan_in_edges``, ``add_switch_case_edge_group``, ``build()``.
"""
from __future__ import annotations
import logging
from typing import Any
logger = logging.getLogger(__name__)
def build_structured_workflow(
*,
coordinator: Any,
seat_executors: list[Any],
approval_gate: Any,
finalizer: Any,
waiting_terminal: Any,
) -> Any:
"""Build a structured (fixed-topology) MAF Workflow.
Topology: coordinator → parallel seat executors → approval gate → finalizer.
The approval gate conditionally routes to waiting_terminal (pause) or finalizer.
"""
from agent_framework import Case, Default, WorkflowBuilder
builder = WorkflowBuilder(
start_executor=coordinator,
name="maf-structured-roundtable",
output_from=[finalizer, waiting_terminal],
)
# coordinator → seats → approval gate. Handle 0/1/≥2 seats since the SDK's
# FanOut/FanIn edge groups require at least two members.
if len(seat_executors) >= 2:
builder.add_fan_out_edges(coordinator, seat_executors)
builder.add_fan_in_edges(seat_executors, approval_gate)
elif len(seat_executors) == 1:
builder.add_edge(coordinator, seat_executors[0])
builder.add_edge(seat_executors[0], approval_gate)
else:
# No seats — coordinator feeds the approval gate directly.
builder.add_edge(coordinator, approval_gate)
# approval gate → conditional: approved → finalizer, waiting → waiting_terminal
builder.add_switch_case_edge_group(approval_gate, [
Case(condition=lambda out: isinstance(out, dict) and out.get("decision") == "waiting_approval", target=waiting_terminal),
Default(target=finalizer),
])
return builder.build()
def build_group_chat_workflow(
*,
coordinator: Any,
seat_executors: list[Any],
approval_gate: Any,
finalizer: Any,
waiting_terminal: Any,
seat_agent_ids: list[str],
) -> Any:
"""Build a dynamic group-chat MAF Workflow.
The coordinator selects the next speaker each round via switch-case edges.
Loop terminates on: coordinator signals completion, max_rounds reached.
"""
from agent_framework import Case, Default, WorkflowBuilder
builder = WorkflowBuilder(
start_executor=coordinator,
name="maf-groupchat-roundtable",
output_from=[finalizer, waiting_terminal],
)
# coordinator → switch-case: route to the selected seat, or to approval gate
cases = []
for i, agent_id in enumerate(seat_agent_ids):
cases.append(Case(
condition=lambda out, aid=agent_id: isinstance(out, dict) and out.get("agent_id") == aid,
target=seat_executors[i],
))
# Default: coordinator said "done" → go to approval gate
cases.append(Default(target=approval_gate))
builder.add_switch_case_edge_group(coordinator, cases)
# each seat → back to coordinator (loop)
for seat_exec in seat_executors:
builder.add_edge(seat_exec, coordinator)
# approval gate → conditional: waiting → waiting_terminal, else → finalizer
builder.add_switch_case_edge_group(approval_gate, [
Case(condition=lambda out: isinstance(out, dict) and out.get("decision") == "waiting_approval", target=waiting_terminal),
Default(target=finalizer),
])
return builder.build()
def create_workflow(
*,
mode: str,
coordinator: Any,
seat_executors: list[Any],
approval_gate: Any,
finalizer: Any,
waiting_terminal: Any,
seat_agent_ids: list[str],
) -> Any:
"""Factory: create the appropriate workflow for the given mode."""
if mode == "group_chat":
return build_group_chat_workflow(
coordinator=coordinator,
seat_executors=seat_executors,
approval_gate=approval_gate,
finalizer=finalizer,
waiting_terminal=waiting_terminal,
seat_agent_ids=seat_agent_ids,
)
return build_structured_workflow(
coordinator=coordinator,
seat_executors=seat_executors,
approval_gate=approval_gate,
finalizer=finalizer,
waiting_terminal=waiting_terminal,
)
@@ -0,0 +1,483 @@
"""MAF Workflow runner — orchestrates workflow execution for a MAF run.
Called after ``create_run`` to actually execute the workflow. Translates all
MAF Workflow events into ``maf_roundtable_events`` (the single event stream
the frontend reads). Manages run status lifecycle and checkpoint persistence.
There is NO sequential fallback. If the MAF SDK is missing or the workflow
fails, the run is marked ``failed`` with a sanitized error message. The runner
never pretends a workflow executed when it did not.
Usage::
runner = WorkflowRunner(app, service=svc, user_id="u1")
await runner.execute(session, run)
"""
from __future__ import annotations
import logging
import time
from datetime import UTC, datetime
from typing import Any
from app.maf_roundtable.action_coordinator import ActionCoordinator
from app.maf_roundtable.deerflow_agent_adapter import DeerFlowAgentAdapter
from app.maf_roundtable.runtime_client import DeerFlowRuntimeClient
from app.maf_roundtable.sanitize import sanitize
from app.maf_roundtable.workflow_executors import (
ApprovalGateExecutor,
CoordinatorExecutor,
FinalizerExecutor,
RoundtableState,
SeatExecutor,
WaitingTerminalExecutor,
_agent_capabilities_from_snapshot,
generate_final_report,
)
from app.maf_roundtable.workflow_factory import create_workflow
logger = logging.getLogger(__name__)
class MafSdkMissingError(RuntimeError):
"""Raised when the MAF SDK (agent_framework) is not installed."""
class WorkflowRunner:
"""Executes a MAF workflow for a given session/run pair."""
def __init__(self, app: Any, *, service: Any, user_id: str) -> None:
self._app = app
self._service = service
self._user_id = user_id
self._client = DeerFlowRuntimeClient(app)
self._adapter = DeerFlowAgentAdapter(self._client, service=service, user_id=user_id)
self._action_coordinator = ActionCoordinator(service, user_id=user_id)
@property
def adapter(self) -> DeerFlowAgentAdapter:
return self._adapter
@property
def action_coordinator(self) -> ActionCoordinator:
return self._action_coordinator
async def execute(self, session: dict[str, Any], run: dict[str, Any]) -> None:
"""Execute the full workflow for a session/run.
Transitions run status: pending → running → completed/failed/cancelled.
Persists checkpoint (RoundtableState) after each major step so the
workflow can resume after approval or restart.
"""
run_id = run["id"]
session_id = session["id"]
t0 = time.perf_counter()
# Verify the MAF SDK is available before touching anything.
try:
import agent_framework # noqa: F401
except ImportError as exc:
await self._fail_run(run_id, session_id, t0, "MafSdkMissing", "agent_framework SDK is not installed")
raise MafSdkMissingError("agent_framework SDK is not installed") from exc
await self._service.store.runs.update_run(run_id, {
"status": "running",
"started_at": datetime.now(UTC),
})
try:
participants = await self._service.store.participants.list_participants(session_id)
thread_map = await self._adapter.ensure_threads(session_id, run_id, participants)
seat_agents = [p["agent_id"] for p in participants if p.get("role") != "manager"]
manager_id = session.get("manager_agent_id")
state = RoundtableState(
session_id=session_id,
run_id=run_id,
task_text=session.get("task_text", ""),
mode=session.get("mode", "structured"),
model_name=session.get("model_name"),
reasoning_effort=session.get("reasoning_effort"),
max_rounds=session.get("max_rounds", 8),
write_policy=session.get("write_policy", "confirm_high_risk"),
manager_agent_id=manager_id,
seat_agent_ids=seat_agents,
thread_map=thread_map,
capability_snapshot=session.get("capability_snapshot"),
)
# Build executor instances — one per seat, each bound to a fixed agent_id.
coordinator = CoordinatorExecutor(self._adapter, state)
seat_executors = [
SeatExecutor(self._adapter, state, agent_id, action_coordinator=self._action_coordinator)
for agent_id in seat_agents
]
approval_gate = ApprovalGateExecutor(self._adapter, state, self._service)
finalizer = FinalizerExecutor(self._adapter, state)
waiting_terminal = WaitingTerminalExecutor()
workflow = create_workflow(
mode=state.mode,
coordinator=coordinator,
seat_executors=seat_executors,
approval_gate=approval_gate,
finalizer=finalizer,
waiting_terminal=waiting_terminal,
seat_agent_ids=seat_agents,
)
await self._run_workflow(workflow, state)
# Persist final state. waiting_approval is NOT a terminal state —
# it must NOT write finished_at. Only completed/failed/cancelled do.
latency = int((time.perf_counter() - t0) * 1000)
final_status = state.status
token_usage = _aggregate_token_usage(state.turn_results)
update_fields: dict[str, Any] = {
"status": final_status,
"latency_ms": latency,
"maf_checkpoint": state.to_dict(),
"token_usage": token_usage,
}
# Only write finished_at for terminal statuses.
if final_status in ("completed", "failed", "cancelled"):
update_fields["finished_at"] = datetime.now(UTC)
await self._service.store.runs.update_run(run_id, update_fields)
session_fields: dict[str, Any] = {"status": final_status}
if final_status == "completed":
session_fields["final_result"] = state.final_result
if final_status != "waiting_approval":
session_fields["fact_ledger"] = state.fact_ledger
await self._service.store.sessions.update_session(
session_id, user_id=self._user_id, fields=session_fields
)
except MafSdkMissingError:
raise
except Exception as exc:
await self._fail_run(run_id, session_id, t0, type(exc).__name__, str(exc))
async def _run_workflow(self, workflow: Any, state: RoundtableState) -> None:
"""Execute the workflow graph via the MAF SDK's streaming API.
Consumes ``WorkflowEvent``s and translates them into MAF roundtable
events. Persists the RoundtableState checkpoint after each superstep.
"""
from app.maf_roundtable.event_normalizer import make_workflow_checkpointed
async for event in workflow.run(state.task_text, stream=True, include_status_events=True):
event_type = getattr(event, "type", "")
executor_id = getattr(event, "executor_id", None)
if event_type == "superstep_completed":
# Persist checkpoint after each superstep.
iteration = getattr(event, "iteration", None)
await self._service.store.runs.update_run(state.run_id, {
"maf_checkpoint": state.to_dict(),
})
await self._adapter._emit_critical(state.run_id, make_workflow_checkpointed(
executor_id, state.current_round,
checkpoint_id=f"superstep-{iteration}",
reason="superstep_completed",
))
elif event_type == "executor_failed":
details = getattr(event, "details", None)
error_msg = str(details) if details else "executor failed"
raise RuntimeError(f"MAF executor '{executor_id}' failed: {error_msg}")
# Check if the workflow ended in a waiting_approval state.
if state.status == "waiting_approval" or state.pending_approvals:
state.status = "waiting_approval"
async def _fail_run(self, run_id: str, session_id: str, t0: float, error_code: str, error_message: str) -> None:
"""Mark a run as failed with a sanitized error message."""
latency = int((time.perf_counter() - t0) * 1000)
safe_message = str(sanitize(error_message))[:500]
logger.error("MAF workflow failed for run %s: %s", run_id, safe_message, exc_info=True)
await self._service.store.runs.update_run(run_id, {
"status": "failed",
"finished_at": datetime.now(UTC),
"error_code": error_code,
"error_message_safe": safe_message,
"latency_ms": latency,
})
await self._service.store.sessions.update_session(session_id, user_id=self._user_id, fields={
"status": "failed",
})
async def cancel(self, run_id: str) -> dict[str, Any]:
"""Cancel a running workflow (cascades to all active seat runs).
Returns the structured cancel result from the adapter so the caller
can decide whether to finalize the parent run as ``cancelled`` or
leave it non-terminal when some sub-runs failed to cancel.
"""
return await self._adapter.cancel(run_id)
async def resume(self, run_id: str) -> dict[str, Any] | None:
"""Resume a workflow from its persisted checkpoint after an approval decision.
P1: ``RoundtableState.from_dict()`` is actually called here. Flow:
1. Load ``maf_checkpoint_json`` from the run row.
2. Restore ``RoundtableState`` via ``from_dict()``.
3. Check the pending approvals' status:
- ``approved``: execute the approved action via ToolExecutor
(at-most-once, deterministic, no LLM).
- ``rejected`` / ``expired``: write ``action.rejected``, skip.
- ``pending``: do NOT start a second Workflow — return immediately.
4. After all actions are executed, determine the parent run status:
- All succeeded → ``completed``.
- Any failed → ``failed`` (P1-8).
- Any unknown → ``waiting_input`` (not completed; human reconcile needed).
- All skipped (already executed) → ``completed``.
Only the owner can resume (enforced by the router before calling
``dispatcher.resume``).
"""
t0 = time.perf_counter()
run = await self._service.store.runs.get_run(run_id)
if run is None:
return None
if run["status"] != "waiting_approval":
return run
checkpoint = run.get("maf_checkpoint")
if not checkpoint:
logger.warning("Cannot resume run %s: no checkpoint", run_id)
return run
state = RoundtableState.from_dict(checkpoint)
session_id = state.session_id
if not state.pending_approvals:
logger.warning("Cannot resume run %s: no pending_approvals in checkpoint", run_id)
return run
# Check if any approval is still pending — if so, don't resume yet.
any_pending = False
for pa in state.pending_approvals:
approval_id = pa.get("approval_id", "")
approval = await self._service.store.approvals.get_approval(approval_id)
if approval and approval.get("status") == "pending":
any_pending = True
if any_pending:
return run
# P0-3 run-level CAS: only ONE concurrent resume may execute the
# approved actions and write the parent run's final state. The winner
# moves the run waiting_approval → running; every other concurrent
# caller loses the CAS and returns the current run WITHOUT writing a
# terminal status (so it can never race a completed/failed write).
claimed_run = await self._service.store.runs.claim_for_resume(run_id)
if not claimed_run:
logger.info("resume(%s): lost run-level CAS — another resume is executing", run_id)
return await self._service.store.runs.get_run(run_id)
# Execute each approved action (skip rejected/expired).
action_outcomes: list[dict[str, Any]] = []
for pa in state.pending_approvals:
approval_id = pa.get("approval_id", "")
action_id = pa.get("action_id", "")
approval = await self._service.store.approvals.get_approval(approval_id)
if approval is None:
action_outcomes.append({"action_id": action_id, "status": "failed",
"error": "approval not found"})
continue
approval_status = approval.get("status", "pending")
if approval_status in ("rejected", "expired"):
from app.maf_roundtable.event_normalizer import make_action_rejected
# Conditional transition (waiting_approval → rejected) — never
# overwrite a terminal state via a generic update.
await self._service.store.actions.mark_rejected(action_id)
await self._adapter._emit_critical(run_id, make_action_rejected(
pa.get("agent_id", ""),
state.current_round,
action_id=action_id,
approval_id=approval_id,
decided_by=approval.get("decided_by", ""),
))
action_outcomes.append({"action_id": action_id, "status": "rejected"})
continue
if approval_status != "approved":
action_outcomes.append({"action_id": action_id, "status": "failed",
"error": f"unexpected approval status: {approval_status}"})
continue
# Approved — execute deterministically via ToolExecutor.
agent_id = pa.get("agent_id", "")
thread_id = state.thread_map.get(agent_id, "")
tool_name = pa.get("tool_name", "")
# Conditional transition (waiting_approval → approved). The
# authoritative at-most-once gate is the ToolExecutor's
# approved → running claim below; this just advances the state
# machine without ever clobbering a terminal status.
await self._service.store.actions.mark_approved(action_id)
from app.maf_roundtable.event_normalizer import make_action_approved
await self._adapter._emit_critical(run_id, make_action_approved(
agent_id,
state.current_round,
action_id=action_id,
approval_id=approval_id,
decided_by=approval.get("decided_by", ""),
))
# Params are recovered server-side inside ToolExecutor (after the
# atomic occupy). A missing/undecryptable secret fails the action
# there — it is never coerced into empty params, so the tool is
# never called (execution count == 0) and the parent run fails.
if thread_id and tool_name:
from app.maf_roundtable.tool_executor import ToolExecutor
executor = ToolExecutor(
adapter=self._adapter,
action_coordinator=self._action_coordinator,
user_id=self._user_id,
)
try:
outcome = await executor.execute(
action_id=action_id,
session_id=session_id,
run_id=run_id,
agent_id=agent_id,
thread_id=thread_id,
approved_tool=tool_name,
capability_snapshot=state.capability_snapshot,
write_policy=state.write_policy,
model_name=state.model_name,
excluded_tools=list(
_agent_capabilities_from_snapshot(
state.capability_snapshot, agent_id
).get("excluded_tools")
or []
),
)
except Exception as exc:
safe_msg = str(sanitize(str(exc)))[:500]
logger.error("ToolExecutor for action %s failed: %s", action_id, safe_msg)
outcome = {"status": "failed", "error": safe_msg}
else:
outcome = {"status": "failed", "error": f"no thread_id or tool_name for action {action_id}"}
action_outcomes.append({
"action_id": action_id,
"tool_name": tool_name,
"status": outcome.get("status"),
"error": outcome.get("error"),
})
state.fact_ledger["pending_actions"].append({
"action_id": action_id,
"tool_name": tool_name,
"outcome": outcome.get("status"),
})
# P0-3: determine parent run status from action outcomes.
statuses = {o.get("status") for o in action_outcomes}
# While any action is still in_progress (another executor running it),
# the parent run stays running — never write finished_at, never finalize.
if "in_progress" in statuses:
state.status = "running"
await self._service.store.runs.update_run(run_id, {
"status": "running",
"maf_checkpoint": state.to_dict(),
})
logger.info("resume(%s): action(s) still in_progress — run stays running", run_id)
return await self._service.store.runs.get_run(run_id)
state.pending_approvals = []
has_unknown = "unknown" in statuses
has_failed = "failed" in statuses
all_resolved = statuses <= {"succeeded", "skipped", "rejected"}
if has_unknown:
state.status = "waiting_input" # human reconciliation needed
elif has_failed:
state.status = "failed"
elif all_resolved:
# Re-enter the MAF finalizer path to synthesize the real report —
# do NOT just flip the status to completed.
try:
await generate_final_report(self._adapter, state)
state.status = "completed"
except Exception as exc: # noqa: BLE001
safe_msg = str(sanitize(str(exc)))[:500]
logger.error("resume(%s): finalizer failed: %s", run_id, safe_msg)
state.status = "failed"
action_outcomes.append({"action_id": "", "status": "failed",
"error": f"finalizer failed: {safe_msg}"})
else:
state.status = "failed"
# Persist final state.
latency = int((time.perf_counter() - t0) * 1000)
token_usage = _aggregate_token_usage(state.turn_results)
update_fields: dict[str, Any] = {
"status": state.status,
"latency_ms": latency,
"maf_checkpoint": state.to_dict(),
"token_usage": token_usage,
}
if state.status in ("completed", "failed", "cancelled"):
update_fields["finished_at"] = datetime.now(UTC)
if state.status == "failed":
errors = [o.get("error") for o in action_outcomes if o.get("error")]
update_fields["error_code"] = "ActionExecutionFailed"
update_fields["error_message_safe"] = str(sanitize("; ".join(errors)))[:500]
await self._service.store.runs.update_run(run_id, update_fields)
session_fields: dict[str, Any] = {"status": state.status}
if state.status == "completed":
session_fields["final_result"] = state.final_result
session_fields["fact_ledger"] = state.fact_ledger
await self._service.store.sessions.update_session(
session_id, user_id=self._user_id, fields=session_fields
)
return await self._service.store.runs.get_run(run_id)
def _aggregate_token_usage(turn_results: list[dict[str, Any]]) -> dict[str, Any]:
"""Aggregate token usage across all seat turns into a run-level summary."""
total_input = 0
total_output = 0
total_total = 0
per_seat: list[dict[str, Any]] = []
for turn in turn_results:
usage = turn.get("usage")
if not isinstance(usage, dict):
continue
inp = usage.get("input_tokens", 0) or usage.get("prompt_tokens", 0) or 0
out = usage.get("output_tokens", 0) or usage.get("completion_tokens", 0) or 0
tot = usage.get("total_tokens", 0) or (inp + out)
total_input += inp
total_output += out
total_total += tot
per_seat.append({
"agent_id": turn.get("agent_id", ""),
"turn_index": turn.get("turn_index", 0),
"input_tokens": inp,
"output_tokens": out,
"total_tokens": tot,
})
return {
"total_input_tokens": total_input,
"total_output_tokens": total_output,
"total_tokens": total_total,
"per_seat": per_seat,
}
@@ -0,0 +1,210 @@
"""Application-layer bridge between the harness ``WriteGuardMiddleware`` and
the MAF ``ActionCoordinator``.
The harness middleware (``deerflow.agents.middlewares.write_guard_middleware``)
is constructed once at agent-build time and cannot hold per-run state. It
resolves two factories — ``make_policy`` / ``make_interceptor`` — by dotted
path (``resolve_variable``). These factories return lightweight singleton
objects that, at interception time, read the MAF service + per-run data from
the run context.
Wiring
------
``register_write_guard_service(service)`` is called from ``deps.py`` once the
``MafRoundtableService`` is built, stashing a module-level reference. The
factories use it to build an ``ActionCoordinator`` on demand.
Per-run data (``session_id`` / ``run_id`` / ``agent_id`` / ``turn_index`` /
``write_policy`` / ``capability_snapshot``) is injected into the DeerFlow run
context by ``runtime_client.start_agent_run`` (see Task 1.4) and read back
here from the ``run_context`` dict the middleware forwards.
"""
from __future__ import annotations
import logging
from typing import Any
from app.maf_roundtable.action_coordinator import (
ActionCoordinator,
tool_needs_approval,
)
logger = logging.getLogger(__name__)
# Module-level reference to the MAF service, set by ``register_write_guard_service``.
# Resolved lazily so importing this module never requires the service to exist.
_maf_service: Any = None
def register_write_guard_service(service: Any) -> None:
"""Stash the MAF service so the WriteGuard factories can reach it.
Called once from ``app.gateway.deps`` after ``MafRoundtableService`` is built.
"""
global _maf_service
_maf_service = service
def _get_service() -> Any:
if _maf_service is None: # pragma: no cover - defensive; wiring is enforced at startup
raise RuntimeError(
"WriteGuard bridge used before register_write_guard_service() — "
"MAF service is not wired."
)
return _maf_service
def _coordinator_for_context(run_context: dict) -> ActionCoordinator:
"""Build an ActionCoordinator bound to the run's user identity.
The user_id is sourced ONLY from the server-injected run context (set by
``runtime_client`` from the authenticated ``ExecutionPrincipal``), never
from tool arguments.
"""
service = _get_service()
user_id = str(run_context.get("maf_user_id") or run_context.get("user_id") or "")
return ActionCoordinator(service, user_id=user_id)
# ── Policy ─────────────────────────────────────────────────────────────────
class MafWriteGuardPolicy:
"""Decides whether a tool call must be intercepted for approval.
Reads the per-run ``write_policy`` and ``capability_snapshot`` from the
run context. Uses the same metadata-driven classification as the rest of
the ActionCoordinator (never name-prefix heuristics). Tools without
metadata use the safe default (treated as a write requiring approval).
"""
def should_intercept(self, tool_name: str, args: Any, run_context: dict | None = None) -> bool: # noqa: ANN401
"""Decide interception from the run context (read vs write aware).
Reads / skills (``side_effect`` of ``read`` / ``skill``) are NEVER
intercepted, so they pass straight through — including on the sync
path. Writes are gated by the active write policy via the same
metadata-driven ``tool_needs_approval`` classification used everywhere
else (never name-prefix heuristics). When no run context is available
we defer to the interceptor (legacy behaviour).
"""
if not tool_name:
return False
if not run_context:
# Cannot classify without context — let the interceptor decide.
return True
write_policy = str(run_context.get("write_policy") or "confirm_high_risk")
capability_snapshot = run_context.get("capability_snapshot")
agent_id = str(run_context.get("agent_id") or "")
return tool_needs_approval(tool_name, write_policy, capability_snapshot, agent_id)
# ── Interceptor ────────────────────────────────────────────────────────────
class MafWriteGuardInterceptor:
"""Records an intercepted write tool call as a pending action + approval.
Implements the harness ``WriteGuardInterceptor`` Protocol. Uses the
single-transaction ``store.create_pending_action_bundle`` (Task 2) so an
action + secret + approval + audit event are written atomically — a
partial action never reaches the database.
"""
async def intercept(
self,
*,
tool_name: str,
args: Any, # noqa: ANN401
tool_call_id: str,
run_context: dict,
) -> dict[str, Any]:
write_policy = str(run_context.get("write_policy") or "confirm_high_risk")
capability_snapshot = run_context.get("capability_snapshot")
agent_id = str(run_context.get("agent_id") or "")
run_id = str(run_context.get("maf_run_id") or "")
session_id = str(run_context.get("maf_session_id") or "")
turn_index = int(run_context.get("turn_index") or 0)
# Apply the real policy now that we have the run context.
if not tool_needs_approval(tool_name, write_policy, capability_snapshot, agent_id):
return {"status": "allowed", "tool_name": tool_name}
coordinator = _coordinator_for_context(run_context)
raw_args = args if isinstance(args, dict) else {"value": str(args)}
created = await coordinator.intercept_write_tool_calls(
run_id=run_id,
session_id=session_id,
agent_id=agent_id,
turn_index=turn_index,
tool_calls=[{"name": tool_name, "id": tool_call_id, "args": raw_args}],
capability_snapshot=capability_snapshot,
write_policy=write_policy,
)
if not created:
return {"status": "allowed", "tool_name": tool_name}
action = created[0]
return {
"status": "approval_required",
"action_id": action.get("id", ""),
"approval_id": action.get("approval_id", ""),
"tool_name": tool_name,
}
async def validate_approved_action(
self,
*,
tool_name: str,
run_context: dict,
) -> bool:
"""Validate a post-approval deterministic execution against the store.
Field presence is NOT trusted: this queries the bound action and confirms
it is ``running`` (the executor already occupied it), belongs to the
current ``run_id`` / ``session_id`` / ``agent_id``, and its ``tool_name``
matches. Returns True only when every check holds; otherwise the
middleware fails closed and the tool does not run.
"""
action_id = str(run_context.get("maf_approved_action_id") or "")
if not action_id:
return False
approved_tool = str(run_context.get("maf_approved_tool") or "")
if approved_tool and tool_name != approved_tool:
return False
run_id = str(run_context.get("maf_run_id") or "")
session_id = str(run_context.get("maf_session_id") or "")
agent_id = str(run_context.get("agent_id") or "")
service = _get_service()
action = await service.store.actions.get_action(action_id)
if action is None:
return False
if action.get("status") != "running":
return False
if run_id and str(action.get("run_id") or "") != run_id:
return False
if session_id and str(action.get("session_id") or "") != session_id:
return False
if agent_id and str(action.get("agent_id") or "") != agent_id:
return False
if str(action.get("tool_name") or "") != tool_name:
return False
return True
# ── Factories resolved by the harness via resolve_variable ──────────────────
def make_policy(**_: Any) -> MafWriteGuardPolicy:
"""Factory for the harness ``resolve_variable`` resolution."""
return MafWriteGuardPolicy()
def make_interceptor(**_: Any) -> MafWriteGuardInterceptor:
"""Factory for the harness ``resolve_variable`` resolution."""
return MafWriteGuardInterceptor()