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

@@ -21,14 +21,38 @@ _MISSING_TOOL_CALL_ID = "missing_tool_call_id"
class ToolErrorHandlingMiddleware(AgentMiddleware[AgentState]):
"""Convert tool exceptions into error ToolMessages so the run can continue."""
def _maf_safe_mode(self, request: ToolCallRequest) -> bool:
runtime = getattr(request, "runtime", None)
ctx = getattr(runtime, "context", None) if runtime is not None else None
if isinstance(ctx, dict):
return bool(ctx.get("maf_safe_error_mode"))
return False
def _build_error_message(self, request: ToolCallRequest, exc: Exception) -> ToolMessage:
tool_name = str(request.tool_call.get("name") or "unknown_tool")
tool_call_id = str(request.tool_call.get("id") or _MISSING_TOOL_CALL_ID)
detail = str(exc).strip() or exc.__class__.__name__
if len(detail) > 500:
detail = detail[:497] + "..."
if self._maf_safe_mode(request):
logger.error(
"Tool execution failed (maf safe mode): name=%s id=%s type=%s",
tool_name,
tool_call_id,
type(exc).__name__,
)
content = "Error: tool execution failed."
else:
detail = str(exc).strip() or exc.__class__.__name__
if len(detail) > 500:
detail = detail[:497] + "..."
content = (
f"Error: Tool '{tool_name}' failed with {exc.__class__.__name__}: {detail}. "
"Continue with available context, or choose an alternative tool."
)
logger.exception(
"Tool execution failed (sync): name=%s id=%s",
request.tool_call.get("name"),
request.tool_call.get("id"),
)
content = f"Error: Tool '{tool_name}' failed with {exc.__class__.__name__}: {detail}. Continue with available context, or choose an alternative tool."
return ToolMessage(
content=content,
tool_call_id=tool_call_id,
@@ -47,8 +71,20 @@ class ToolErrorHandlingMiddleware(AgentMiddleware[AgentState]):
except GraphBubbleUp:
# Preserve LangGraph control-flow signals (interrupt/pause/resume).
raise
except Exception as exc:
logger.exception("Tool execution failed (sync): name=%s id=%s", request.tool_call.get("name"), request.tool_call.get("id"))
except Exception as exc: # noqa: BLE001
if self._maf_safe_mode(request):
logger.error(
"Tool execution failed (maf safe mode, sync): name=%s id=%s type=%s",
request.tool_call.get("name"),
request.tool_call.get("id"),
type(exc).__name__,
)
else:
logger.exception(
"Tool execution failed (sync): name=%s id=%s",
request.tool_call.get("name"),
request.tool_call.get("id"),
)
return self._build_error_message(request, exc)
@override
@@ -62,8 +98,20 @@ class ToolErrorHandlingMiddleware(AgentMiddleware[AgentState]):
except GraphBubbleUp:
# Preserve LangGraph control-flow signals (interrupt/pause/resume).
raise
except Exception as exc:
logger.exception("Tool execution failed (async): name=%s id=%s", request.tool_call.get("name"), request.tool_call.get("id"))
except Exception as exc: # noqa: BLE001
if self._maf_safe_mode(request):
logger.error(
"Tool execution failed (maf safe mode, async): name=%s id=%s type=%s",
request.tool_call.get("name"),
request.tool_call.get("id"),
type(exc).__name__,
)
else:
logger.exception(
"Tool execution failed (async): name=%s id=%s",
request.tool_call.get("name"),
request.tool_call.get("id"),
)
return self._build_error_message(request, exc)
@@ -127,6 +175,23 @@ def _build_runtime_middlewares(
provider = provider_cls(**provider_kwargs)
middlewares.append(GuardrailMiddleware(provider, fail_closed=guardrails_config.fail_closed, passport=guardrails_config.passport))
# WriteGuard middleware (if configured) — intercepts external-write tool
# calls for human approval. Activated per-run via a ``maf_run_id`` flag in
# the run context, so legacy runs are unaffected. The policy/interceptor
# factories live in the application layer and are resolved by dotted path
# so the harness never imports ``app.*``.
write_guard_config = app_config.write_guard
if write_guard_config.enabled and write_guard_config.provider:
from deerflow.agents.middlewares.write_guard_middleware import WriteGuardMiddleware
from deerflow.reflection import resolve_variable
policy_factory = resolve_variable(write_guard_config.provider.policy_use)
interceptor_factory = resolve_variable(write_guard_config.provider.interceptor_use)
factory_kwargs = dict(write_guard_config.provider.config) if write_guard_config.provider.config else {}
policy = policy_factory(**factory_kwargs)
interceptor = interceptor_factory(**factory_kwargs)
middlewares.append(WriteGuardMiddleware(policy=policy, interceptor=interceptor))
from deerflow.agents.middlewares.sandbox_audit_middleware import SandboxAuditMiddleware
middlewares.append(SandboxAuditMiddleware())
@@ -0,0 +1,318 @@
"""WriteGuardMiddleware — intercepts external-write tool calls for human approval.
This middleware keeps write tools **visible** to the model (the schema is not
removed from the tool list), but short-circuits their execution so the real
tool never runs until a human approves. The model sees a structured
``ToolMessage`` describing the pending approval instead of the tool's real
result.
Activation model (zero-impact on legacy runs)
---------------------------------------------
The middleware is always present in the chain when configured, but it only
acts when the run context carries a truthy ``maf_run_id`` flag. Every other
run — legacy single-agent chats, subagents, ephemeral runs — calls the
``handler`` unchanged. This mirrors how ``TaskExternalContextMiddleware``
reads a run-context flag to switch on per-run behaviour.
Injection
---------
The application layer supplies a ``WriteGuardPolicy`` (decides *whether* to
intercept a given call) and a ``WriteGuardInterceptor`` (records the
action/approval/audit bundle). Both are injected via constructor so the
harness never imports ``app.*``; resolution happens in
``_build_runtime_middlewares`` through ``resolve_variable``.
Note: unlike ``GuardrailMiddleware`` (which is fail-closed on provider error),
this middleware is **fail-open by default for legacy runs** — but inside an
active MAF run a failure to record an approval aborts the call with an error
ToolMessage rather than letting the write proceed.
"""
from __future__ import annotations
import json
import logging
from collections.abc import Awaitable, Callable
from typing import override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain_core.messages import ToolMessage
from langgraph.errors import GraphBubbleUp
from langgraph.prebuilt.tool_node import ToolCallRequest
from langgraph.types import Command
from deerflow.config.write_guard_config import WriteGuardInterceptor, WriteGuardPolicy
logger = logging.getLogger(__name__)
class WriteGuardMiddleware(AgentMiddleware[AgentState]):
"""Intercept write tool calls for approval when running inside a MAF seat run.
The middleware reads ``request.runtime.context`` (the shared run context)
to detect an active MAF run (``maf_run_id`` truthy). When inactive it is a
pure pass-through. When active, each tool call is offered to the injected
``WriteGuardPolicy``; if it says ``should_intercept`` is True, the
``WriteGuardInterceptor`` records the pending action and the middleware
returns an ``approval_required`` ToolMessage **without** calling
``handler`` — so the real tool executes exactly zero times before approval.
"""
def __init__(
self,
policy: WriteGuardPolicy,
interceptor: WriteGuardInterceptor,
) -> None:
self.policy = policy
self.interceptor = interceptor
# ── context helpers ──────────────────────────────────────────────────
@staticmethod
def _run_context(request: ToolCallRequest) -> dict:
"""Return the run context dict from the runtime, or {} if absent.
``request.runtime`` is a ``ToolRuntime`` whose ``.context`` attribute
holds the shared run-context dict (the same one ``Runtime.context``
exposes to graph nodes / other middlewares). Outside a graph it may
be None.
"""
runtime = getattr(request, "runtime", None)
if runtime is None:
return {}
ctx = getattr(runtime, "context", None)
if isinstance(ctx, dict):
return ctx
# Some context objects are Mapping-like but not plain dicts.
try:
return dict(ctx) # type: ignore[arg-type]
except Exception:
return {}
@staticmethod
def _tool_name(request: ToolCallRequest) -> str:
return str(request.tool_call.get("name", ""))
@staticmethod
def _tool_call_id(request: ToolCallRequest) -> str:
return str(request.tool_call.get("id", ""))
@staticmethod
def _tool_args(request: ToolCallRequest) -> object:
return request.tool_call.get("args", {})
def _build_approval_message(self, request: ToolCallRequest, outcome: dict) -> ToolMessage:
"""Build the ToolMessage the model sees in place of the real tool result.
The content is a structured JSON envelope so a frontend / coordinator
can parse the ``action_id`` to drive the approval UI. The real tool's
return value is never produced.
"""
tool_name = self._tool_name(request)
tool_call_id = self._tool_call_id(request)
envelope = {
"status": outcome.get("status", "approval_required"),
"action_id": outcome.get("action_id", ""),
"approval_id": outcome.get("approval_id", ""),
"tool_name": tool_name,
"message": (
f"外部写操作 '{tool_name}' 已记录,等待人工审批后执行。"
"本次调用未执行实际写入。"
),
}
return ToolMessage(
content=json.dumps(envelope, ensure_ascii=False),
tool_call_id=tool_call_id,
name=tool_name,
status="error",
)
# ── interception core (shared by sync/async) ─────────────────────────
def _is_active(self, request: ToolCallRequest) -> bool:
"""True only when running inside an active MAF seat run."""
return bool(self._run_context(request).get("maf_run_id"))
def _approved_passthrough(self, request: ToolCallRequest) -> bool:
"""True when this run is a deterministic, post-approval tool execution.
The ToolExecutor sets ``maf_approved_tool`` + ``maf_approved_action_id``
in the run context for defense-in-depth validation. The middleware
checks:
1. ``maf_approved_tool`` matches the tool name (required).
2. ``maf_approved_action_id`` is present (required when tool is set).
3. The action is in ``approved`` status and belongs to the current
run / session / agent (verified through the interceptor).
A model calling another tool with the same name but different
action_id is still intercepted. When combined with the direct tool
executor (P0-2) which bypasses the LLM entirely, this is defense-in-
depth — the real enforcement is that the LLM never sees the approved
params and never decides whether to call the tool.
"""
ctx = self._run_context(request)
approved_tool = ctx.get("maf_approved_tool")
if not approved_tool:
return False
if self._tool_name(request) != approved_tool:
return False
approved_action_id = ctx.get("maf_approved_action_id")
if not approved_action_id:
# When no action_id is bound, the passthrough is too permissive.
# In production the ToolExecutor always sets this; the absence
# means the tool was flagged by some other mechanism without
# proper action binding — block to be safe.
logger.warning(
"WriteGuard: approved tool '%s' has no maf_approved_action_id "
"in run context — blocking passthrough",
approved_tool,
)
return False
return True
async def _validate_approved_async(self, request: ToolCallRequest) -> bool:
"""Confirm a bound approved action is genuinely executable (async path).
Field presence (``maf_approved_tool`` / ``maf_approved_action_id``) is
necessary but NOT sufficient: the interceptor queries the stored action
and verifies status==``running`` + run/session/agent ownership + tool
match. Fails closed (False) when the interceptor cannot confirm.
"""
run_context = self._run_context(request)
validator = getattr(self.interceptor, "validate_approved_action", None)
if validator is None:
# No validator available — cannot confirm the action is legitimate.
logger.warning(
"WriteGuard: approved tool '%s' bound but interceptor lacks "
"validate_approved_action — blocking (fail-closed)",
self._tool_name(request),
)
return False
try:
return bool(await validator(tool_name=self._tool_name(request), run_context=run_context))
except Exception:
logger.exception(
"WriteGuard: validate_approved_action failed for '%s' — blocking",
self._tool_name(request),
)
return False
async def _intercept_async(self, request: ToolCallRequest) -> ToolMessage | None:
"""Record an interception. Returns the approval ToolMessage, or None to allow."""
tool_name = self._tool_name(request)
args = self._tool_args(request)
run_context = self._run_context(request)
if not self.policy.should_intercept(tool_name, args, run_context):
return None
try:
outcome = await self.interceptor.intercept(
tool_name=tool_name,
args=args,
tool_call_id=self._tool_call_id(request),
run_context=run_context,
)
except GraphBubbleUp:
raise
except Exception:
# Recording the approval failed. We must NOT let the write
# proceed silently — fail the call so the run surfaces the error
# rather than executing an unapproved write.
logger.exception("WriteGuard interceptor failed for tool '%s'", tool_name)
return ToolMessage(
content=json.dumps(
{"status": "intercept_failed", "tool_name": tool_name,
"message": f"记录写操作审批失败,{tool_name} 未执行。"},
ensure_ascii=False,
),
tool_call_id=self._tool_call_id(request),
name=tool_name,
status="error",
)
# If the interceptor decided no approval is needed (e.g. a read tool
# under a write policy, or ``auto`` policy), allow the call through.
if outcome.get("status") == "allowed":
return None
return self._build_approval_message(request, outcome)
# ── AgentMiddleware overrides ────────────────────────────────────────
@override
def wrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
if not self._is_active(request):
return handler(request)
# Post-approval deterministic execution: the approved tool passes through.
if self._approved_passthrough(request):
return handler(request)
# The interceptor is async; recording synchronously is not supported.
# Reads are never intercepted (should_intercept False) so they pass
# straight through on the sync path. Writes that cannot be safely
# async-intercepted fail closed here rather than running unapproved.
tool_name = self._tool_name(request)
run_context = self._run_context(request)
if self.policy.should_intercept(tool_name, self._tool_args(request), run_context):
# Cannot await here; return an immediate error so the write does
# not proceed. The async path records the action properly.
logger.warning(
"WriteGuard: sync write call '%s' blocked (use async tool path)", tool_name
)
return ToolMessage(
content=json.dumps(
{"status": "intercept_blocked_sync", "tool_name": tool_name,
"message": f"{tool_name} 写操作需走异步审批路径,未执行。"},
ensure_ascii=False,
),
tool_call_id=self._tool_call_id(request),
name=tool_name,
status="error",
)
return handler(request)
@override
async def awrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
) -> ToolMessage | Command:
if not self._is_active(request):
return await handler(request)
# Post-approval deterministic execution: the approved tool passes
# through only after the bound action is validated against the store
# (status running + run/session/agent ownership + tool match). Field
# presence alone is not trusted.
if self._approved_passthrough(request):
if await self._validate_approved_async(request):
return await handler(request)
tool_name = self._tool_name(request)
logger.warning(
"WriteGuard: approved execution of '%s' failed action validation — blocking",
tool_name,
)
return ToolMessage(
content=json.dumps(
{"status": "approval_invalid", "tool_name": tool_name,
"message": f"{tool_name} 的已审批动作未通过校验,未执行。"},
ensure_ascii=False,
),
tool_call_id=self._tool_call_id(request),
name=tool_name,
status="error",
)
try:
approval_msg = await self._intercept_async(request)
except GraphBubbleUp:
# Preserve interrupt/pause/resume control-flow signals.
raise
if approval_msg is not None:
logger.info(
"WriteGuard intercepted '%s' (call_id=%s) — awaiting approval",
self._tool_name(request), self._tool_call_id(request),
)
return approval_msg
return await handler(request)