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

@@ -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