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,482 @@
"""Server-side executor for a single, human-approved tool call (MAF roundtable).
This is the harness-layer "approved tool executor". After a human approves an
external-write action, the MAF app layer hands the server-constructed tool call
to :func:`execute_approved_tool`, which runs it through the **real** LangGraph
tool-execution path — the same path a normal DeerFlow tool call uses — without
any LLM involvement:
- a real ``ToolNode`` (so ``_inject_tool_args`` runs internally: ``InjectedState``
/ ``InjectedStore`` / ``ToolRuntime`` are populated by the framework, the
caller-provided args are stripped-then-rebuilt so nothing is forged);
- a real ``ToolRuntime`` (``state`` recovered from the thread checkpoint's
``channel_values`` — sandbox / thread_data / etc. — plus ``config`` / ``store``
/ ``stream_writer``), NOT a duck-typed ``SimpleNamespace``;
- the same ``wrap_tool_call`` / ``awrap_tool_call`` middleware chain the lead
agent uses (``build_lead_runtime_middlewares``), composed first-outermost
exactly like ``langchain.agents.factory.create_agent``;
- unified tool-error handling (``handle_tool_errors=True``).
The tool list is rebuilt from the seat's frozen capability snapshot / agent
config / model / ``excluded_tools`` — never the global default registry — and
four security gates run BEFORE execution:
1. the action's ``run_id`` / ``session_id`` / ``agent_id`` / ``tool_name`` must
match the current execution context;
2. the tool must not be disabled (``excluded_tools``);
3. the tool must exist in the rebuilt allow-list (i.e. be permitted by the
capability snapshot);
4. a trusted MAF context (``maf_run_id`` / ``maf_approved_tool`` /
``maf_approved_action_id`` / …) is injected so ``WriteGuardMiddleware`` can
validate the approved binding and pass the call through.
Boundary: this module lives in ``deerflow.*`` and imports only ``deerflow.*`` +
``langgraph`` / ``langchain`` — never ``app.*``. The MAF app layer calls it,
passing all secret-derived params and the stored action record as plain data.
"""
from __future__ import annotations
import logging
import uuid
from typing import Any, TypedDict
from langchain_core.messages import AIMessage, ToolMessage
from langgraph.errors import GraphBubbleUp
from langgraph.types import Command
from deerflow.config.app_config import AppConfig
from deerflow.runtime.user_context import reset_current_user, set_current_user
from deerflow.tools.tools import get_available_tools
logger = logging.getLogger(__name__)
class MafApprovedToolContext(TypedDict, total=False):
"""Typed run context for post-approval ToolNode / ToolRuntime injection.
Declared so LangGraph ``Runtime[MafApprovedToolContext]`` serializes cleanly
(bare ``Runtime`` defaults ``context`` to ``None`` and warns on dict values).
"""
thread_id: str
run_id: str
agent_id: str
user_id: str
turn_index: int
maf_run_id: str
maf_session_id: str
maf_user_id: str
capability_snapshot: dict[str, Any]
write_policy: str
maf_approved_tool: str
maf_approved_action_id: str
maf_safe_error_mode: bool
class _ExecutorUser:
"""Minimal ``CurrentUser`` shim (structural ``.id``) for path resolution."""
def __init__(self, user_id: str) -> None:
self.id = user_id
class ApprovedToolRejection(Exception):
"""A security gate refused the approved tool call (never executed).
``reason`` is a stable machine-readable code; ``detail`` is safe to log /
persist (never contains params or credentials).
"""
def __init__(self, reason: str, detail: str) -> None:
self.reason = reason
self.detail = detail
super().__init__(f"approved tool rejected: {reason} — {detail}")
_INCONCLUSIVE_ERROR_MARKERS = (
"timeout", "timedout", "deadline",
"connection", "connect", "disconnect", "reset", "refused", "broken",
"gateway", "badgateway", "serviceunavailable", "unavailable",
"protocol", "remoteprotocol", "eof", "network", "socket",
"temporarily", "tryagain", "econnreset", "etimedout",
)
def _is_inconclusive_text(text: str) -> bool:
"""True when an error string denotes an unknowable external result."""
lowered = text.lower()
return any(marker in lowered for marker in _INCONCLUSIVE_ERROR_MARKERS)
def _is_inconclusive_error(exc: BaseException) -> bool:
"""True when an exception means the external result is unknowable.
Classified by exception type name + message keywords (no hard dependency on
httpx/aiohttp). Timeouts, dropped/reset connections, and 502/503-gateway
errors leave the external write's fate undetermined → ``unknown``.
"""
return _is_inconclusive_text(type(exc).__name__) or _is_inconclusive_text(str(exc))
# ── middleware-chain composition (mirrors langchain create_agent) ──────────
def _overrides_hook(middleware: Any, hook: str) -> bool:
"""True if ``middleware`` overrides ``hook`` (vs. the no-op base default)."""
from langchain.agents.middleware import AgentMiddleware
base = getattr(AgentMiddleware, hook, None)
impl = getattr(type(middleware), hook, None)
return impl is not None and impl is not base
def _compose_two_async(outer: Any, inner: Any) -> Any:
"""Compose two async ``wrap_tool_call`` wrappers; ``outer`` runs first."""
async def composed(request: Any, handler: Any) -> Any:
async def call_inner(req: Any) -> Any:
return await inner(req, handler)
return await outer(request, call_inner)
return composed
def compose_async_tool_call_wrappers(wrappers: list[Any]) -> Any | None:
"""Fold async wrappers into one chain, **first = outermost**.
Replicates ``langchain.agents.factory._chain_async_tool_call_wrappers``
without importing the private helper, so the approved executor reuses the
exact same middleware ordering the lead agent gets.
"""
if not wrappers:
return None
result = wrappers[-1]
for wrapper in reversed(wrappers[:-1]):
result = _compose_two_async(wrapper, result)
return result
def _build_tool_call_middleware_chain(app_config: AppConfig) -> Any | None:
"""Build the composed async ``wrap_tool_call`` chain from the real middlewares.
Uses ``build_lead_runtime_middlewares`` (the same instances the lead agent
runs — WriteGuard / ToolErrorHandling / SandboxAudit / ToolMetrics /
Guardrail when enabled), filtered to those overriding ``awrap_tool_call``
(falling back to a sync ``wrap_tool_call`` adapter), composed first-outermost.
"""
from deerflow.agents.middlewares.tool_error_handling_middleware import (
build_lead_runtime_middlewares,
)
middlewares = build_lead_runtime_middlewares(app_config=app_config)
wrappers: list[Any] = []
for mw in middlewares:
if _overrides_hook(mw, "awrap_tool_call"):
wrappers.append(mw.awrap_tool_call)
elif _overrides_hook(mw, "wrap_tool_call"):
# A sync-only wrap_tool_call cannot drive the async approved path
# safely; DeerFlow's tool middlewares all implement awrap_tool_call,
# so this is defensive. Skip rather than risk a broken chain.
logger.warning(
"execute_approved_tool: skipping sync-only tool middleware %s",
type(mw).__name__,
)
return compose_async_tool_call_wrappers(wrappers)
# ── security gates ────────────────────────────────────────────────────────
_SAFE_SUCCESS_KEYS = frozenset({"executed", "external_object_id", "safe_summary", "command", "has_update"})
_ERROR_CODE_INCONCLUSIVE = "inconclusive_external_result"
_ERROR_CODE_FAILED = "tool_execution_failed"
_ERROR_CODE_REJECTED = "approved_action_rejected"
def _seat_excluded_tools(
capability_snapshot: dict[str, Any] | None,
agent_id: str,
fallback: list[str] | None,
) -> list[str]:
if not capability_snapshot:
return list(fallback or [])
for a in capability_snapshot.get("agents") or []:
if isinstance(a, dict) and a.get("agent_id") == agent_id:
return list(a.get("excluded_tools") or [])
return list(fallback or [])
def _frozen_allowed_tool_names(
capability_snapshot: dict[str, Any] | None,
agent_id: str,
) -> frozenset[str] | None:
"""Return the frozen allow-list for a seat, or None if snapshot has no list."""
if not capability_snapshot:
return None
for a in capability_snapshot.get("agents") or []:
if isinstance(a, dict) and a.get("agent_id") == agent_id:
names = a.get("allowed_tool_names")
if isinstance(names, list):
return frozenset(str(n) for n in names)
return None
def _check_action_consistency(
*,
action_record: dict[str, Any] | None,
approved_action_id: str,
run_id: str,
session_id: str,
agent_id: str,
tool_name: str,
turn_index: int,
) -> None:
"""Gate 1: the stored action must belong to this exact execution context."""
if not action_record:
raise ApprovedToolRejection(
"missing_action", "no action record supplied for approved execution"
)
required: dict[str, Any] = {
"id": approved_action_id,
"status": "running",
"run_id": run_id,
"session_id": session_id,
"agent_id": agent_id,
"tool_name": tool_name,
"turn_index": turn_index,
}
for field, expected in required.items():
actual = action_record.get(field)
if actual != expected:
raise ApprovedToolRejection(
_ERROR_CODE_REJECTED,
f"action {field} mismatch or missing (expected {expected!r}, got {actual!r})",
)
# ── the executor ──────────────────────────────────────────────────────────
async def execute_approved_tool(
*,
app_config: AppConfig,
checkpointer: Any,
store: Any,
thread_id: str,
# identity / trusted context
user_id: str,
session_id: str,
run_id: str,
agent_id: str,
turn_index: int,
# frozen per-seat tool selection
model_name: str | None,
excluded_tools: list[str] | None,
capability_snapshot: dict[str, Any] | None,
write_policy: str,
# the approved call (params already decrypted server-side by the caller)
tool_name: str,
params: dict[str, Any],
approved_action_id: str,
action_record: dict[str, Any] | None,
tool_call_id: str | None = None,
) -> dict[str, Any]:
"""Execute one approved tool call via the real LangGraph tool path.
Returns ``{"status": "succeeded", "result": ...}`` or
``{"status": "failed", "error": ...}``. A security rejection is a
``failed`` outcome (so the parent run fails) and the tool executes 0 times.
The LLM is never involved.
"""
from deerflow.config.agents_config import load_agent_config
excluded = _seat_excluded_tools(capability_snapshot, agent_id, excluded_tools)
# Gate 1 — action/context consistency (before building anything).
try:
_check_action_consistency(
action_record=action_record,
approved_action_id=approved_action_id,
run_id=run_id,
session_id=session_id,
agent_id=agent_id,
tool_name=tool_name,
turn_index=turn_index,
)
except ApprovedToolRejection as exc:
logger.error(
"execute_approved_tool rejected (%s): %s", exc.reason, exc.detail
)
return {"status": "failed", "error": f"{exc.reason}: {exc.detail}"}
# Rebuild the tool list exactly as the seat's agent run would: the agent's
# configured tool_groups + model, minus disabled tools. Never the global
# default registry.
agent_config = load_agent_config(agent_id)
tool_groups = getattr(agent_config, "tool_groups", None) if agent_config else None
effective_model = model_name or (getattr(agent_config, "model", None) if agent_config else None)
all_tools = get_available_tools(
groups=tool_groups,
model_name=effective_model,
excluded_tools=excluded,
app_config=app_config,
)
tool_map = {t.name: t for t in all_tools}
frozen_allowed = _frozen_allowed_tool_names(capability_snapshot, agent_id)
if frozen_allowed is not None:
tool_map = {name: tool for name, tool in tool_map.items() if name in frozen_allowed}
# Gate 2 — disabled tool.
if tool_name in excluded:
logger.error("execute_approved_tool: tool '%s' is disabled", tool_name)
return {"status": "failed", "error": f"tool '{tool_name}' is disabled for this seat"}
# Gate 3 — allowed / exists in the rebuilt capability allow-list.
if tool_name not in tool_map:
logger.error("execute_approved_tool: tool '%s' not in seat allow-list", tool_name)
return {
"status": "failed",
"error": f"tool '{tool_name}' is not permitted by this seat's capability snapshot",
}
# Recover real runtime state from the thread checkpoint.
channel_values: dict[str, Any] = {}
config_dict: dict[str, Any] = {"configurable": {"thread_id": thread_id, "checkpoint_ns": ""}}
if checkpointer is not None:
try:
ct = await checkpointer.aget_tuple(config_dict)
checkpoint = getattr(ct, "checkpoint", None) if ct is not None else None
if isinstance(checkpoint, dict):
raw = checkpoint.get("channel_values", {}) or {}
if isinstance(raw, dict):
channel_values = dict(raw)
except Exception:
logger.warning(
"execute_approved_tool: could not read checkpoint for thread %s; "
"continuing with empty state",
thread_id,
exc_info=True,
)
# Build the trusted run context. These keys come ONLY from the server — the
# decrypted params never enter this dict or any model context.
call_id = tool_call_id or uuid.uuid4().hex
run_context: MafApprovedToolContext = {
"thread_id": thread_id,
"run_id": run_id,
"agent_id": agent_id,
"user_id": user_id,
"turn_index": turn_index,
"maf_run_id": run_id,
"maf_session_id": session_id,
"maf_user_id": user_id,
"capability_snapshot": capability_snapshot or {},
"write_policy": write_policy or "",
"maf_approved_tool": tool_name,
"maf_approved_action_id": approved_action_id,
"maf_safe_error_mode": True,
}
# Compose the real middleware chain (WriteGuard sees the approved binding
# and passes the call through; ToolErrorHandling/etc. behave as usual).
awrap = _build_tool_call_middleware_chain(app_config)
from langgraph.prebuilt import ToolNode
from langgraph.runtime import Runtime
collected_writes: list[Any] = []
def _stream_writer(payload: Any) -> None:
collected_writes.append(payload)
tool_node = ToolNode(
list(tool_map.values()),
awrap_tool_call=awrap,
handle_tool_errors=True,
)
# Server-constructed single tool call — no LLM. Carried on a synthetic
# AIMessage so the ToolNode parses it exactly like a graph tool turn.
tool_call = {"name": tool_name, "args": dict(params), "id": call_id, "type": "tool_call"}
ai_msg = AIMessage(content="", tool_calls=[tool_call])
input_state: dict[str, Any] = dict(channel_values)
input_state["messages"] = [ai_msg]
# Context lives only on typed Runtime — do not also set config["context"].
runtime = Runtime[MafApprovedToolContext](
context=run_context, store=store, stream_writer=_stream_writer
)
config_dict["configurable"]["__pregel_runtime"] = runtime
token = set_current_user(_ExecutorUser(user_id))
try:
result = await tool_node.ainvoke(input_state, config_dict)
except GraphBubbleUp:
# Preserve interrupt / pause / resume control-flow signals.
raise
except Exception as exc: # noqa: BLE001 — map any failure to a safe outcome
# Never leak raw exception text (it may embed params / credentials):
# surface only the exception type. Inconclusive failures (timeout /
# disconnect / gateway) become ``unknown`` and are NEVER auto-retried —
# the external write may or may not have happened.
if _is_inconclusive_error(exc):
logger.error(
"execute_approved_tool: tool '%s' inconclusive (%s) — recording unknown",
tool_name,
type(exc).__name__,
)
return {"status": "unknown", "error": _ERROR_CODE_INCONCLUSIVE}
logger.error(
"execute_approved_tool: tool '%s' raised %s",
tool_name,
type(exc).__name__,
)
return {"status": "failed", "error": _ERROR_CODE_FAILED}
finally:
reset_current_user(token)
return _interpret_tool_node_result(result, tool_name)
def _safe_success_payload(content: Any) -> dict[str, Any]:
if isinstance(content, dict):
safe = {k: content[k] for k in _SAFE_SUCCESS_KEYS if k in content}
if safe:
return safe
return {"executed": True}
def _interpret_tool_node_result(result: Any, tool_name: str) -> dict[str, Any]:
"""Translate the ToolNode output (ToolMessage / Command) into an outcome dict."""
messages: list[Any] = []
if isinstance(result, dict):
messages = result.get("messages", []) or []
elif isinstance(result, list):
messages = result
output = messages[0] if messages else result
if isinstance(output, Command):
update = getattr(output, "update", None)
return {
"status": "succeeded",
"result": {"command": type(output).__name__, "has_update": update is not None},
}
if isinstance(output, ToolMessage):
status = getattr(output, "status", "success")
content = output.content
if status == "error":
text = str(content)
if _is_inconclusive_text(text):
return {"status": "unknown", "error": _ERROR_CODE_INCONCLUSIVE}
return {"status": "failed", "error": _ERROR_CODE_FAILED}
return {"status": "succeeded", "result": _safe_success_payload(content)}
return {"status": "succeeded", "result": {"executed": True}}
@@ -0,0 +1,61 @@
"""Server-trusted tool side-effect / risk metadata for MAF WriteGuard.
Harness-only — never imports ``app.*``. Used when building frozen capability
snapshots and when classifying tools at runtime. Client-supplied metadata is
never trusted; only deployment config (``ToolConfig`` extras) and this registry
apply.
Tools without explicit metadata default to ``write`` / ``R3`` (requires approval
under ``confirm_high_risk``).
"""
from __future__ import annotations
from typing import Any
_DEFAULT_SIDE_EFFECT = "write"
_DEFAULT_RISK_LEVEL = "R3"
# Built-in tools whose side effects are known server-side (not name-prefix guessing
# for arbitrary tools — only this curated allow-list).
_BUILTIN_METADATA: dict[str, tuple[str, str]] = {
"memory": ("read", "R0"),
"ask_clarification": ("read", "R0"),
"view_image": ("read", "R0"),
"present_file": ("read", "R0"),
"web_search": ("read", "R1"),
"web_fetch": ("read", "R1"),
"read_file": ("read", "R0"),
"grep": ("read", "R0"),
"glob": ("read", "R0"),
"ls": ("read", "R0"),
"invoke_skill": ("skill", "R1"),
"skill_search": ("skill", "R1"),
"task": ("read", "R2"),
"bash": ("write", "R3"),
"write_file": ("write", "R3"),
"edit_file": ("write", "R3"),
}
def resolve_tool_metadata(
tool_name: str,
*,
config_extra: dict[str, Any] | None = None,
) -> dict[str, str]:
"""Return ``{name, tool_name, side_effect, risk_level}`` for one tool."""
side = _DEFAULT_SIDE_EFFECT
risk = _DEFAULT_RISK_LEVEL
if config_extra:
if config_extra.get("side_effect"):
side = str(config_extra["side_effect"])
if config_extra.get("risk_level"):
risk = str(config_extra["risk_level"])
elif tool_name in _BUILTIN_METADATA:
side, risk = _BUILTIN_METADATA[tool_name]
return {
"name": tool_name,
"tool_name": tool_name,
"side_effect": side,
"risk_level": risk,
}