feat(maf): add secure roundtable workflow runtime
This commit is contained in:
1 parent
e690475e6e
commit
bd4131b4e2
52 files changed
+10315
-96
No files matched your search
+73
-8
@@ -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())
|
||||
|
||||
+318
@@ -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)
|
||||
Reference in new issue
Block a user