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)
|
||||
@@ -41,6 +41,7 @@ from deerflow.config.token_usage_config import TokenUsageConfig
|
||||
from deerflow.config.tool_config import ToolConfig, ToolGroupConfig
|
||||
from deerflow.config.tool_search_config import ToolSearchConfig, load_tool_search_config_from_dict
|
||||
from deerflow.config.vision_config import VisionConfig
|
||||
from deerflow.config.write_guard_config import WriteGuardConfig, load_write_guard_config_from_dict
|
||||
from deerflow.config.y_log_config import YLogConfig
|
||||
|
||||
load_dotenv()
|
||||
@@ -131,6 +132,7 @@ class AppConfig(BaseModel):
|
||||
acp_agents: dict[str, ACPAgentConfig] = Field(default_factory=dict, description="ACP-compatible agent configuration")
|
||||
subagents: SubagentsAppConfig = Field(default_factory=SubagentsAppConfig, description="Subagent runtime configuration")
|
||||
guardrails: GuardrailsConfig = Field(default_factory=GuardrailsConfig, description="Guardrail middleware configuration")
|
||||
write_guard: WriteGuardConfig = Field(default_factory=WriteGuardConfig, description="WriteGuard middleware configuration (intercepts external-write tools for approval)")
|
||||
circuit_breaker: CircuitBreakerConfig = Field(default_factory=CircuitBreakerConfig, description="LLM circuit breaker configuration")
|
||||
excluded_tools: list[str] = Field(default_factory=list, description="Tool names to exclude from the main agent (e.g. ['task', 'ask_clarification'])")
|
||||
skill_stop: SkillStopConfig = Field(default_factory=SkillStopConfig, description="Skill stop middleware configuration")
|
||||
@@ -228,6 +230,10 @@ class AppConfig(BaseModel):
|
||||
if "guardrails" in config_data:
|
||||
load_guardrails_config_from_dict(config_data["guardrails"])
|
||||
|
||||
# Load write_guard config if present
|
||||
if "write_guard" in config_data:
|
||||
load_write_guard_config_from_dict(config_data["write_guard"])
|
||||
|
||||
# Load circuit_breaker config if present
|
||||
if "circuit_breaker" in config_data:
|
||||
config_data["circuit_breaker"] = config_data["circuit_breaker"]
|
||||
|
||||
+151
@@ -0,0 +1,151 @@
|
||||
"""Configuration for the WriteGuard middleware.
|
||||
|
||||
The WriteGuard middleware intercepts external-write tool calls so they can be
|
||||
recorded for human approval **before** the underlying tool executes. It is
|
||||
activated per-run via a ``maf_run_id`` flag in the run context, so legacy
|
||||
single-agent runs are completely unaffected (the middleware no-ops).
|
||||
|
||||
This module is harness-only: it defines the config schema and the
|
||||
``WriteGuardPolicy`` / ``WriteGuardInterceptor`` Protocols. The concrete
|
||||
implementations live in the application layer (``app.maf_roundtable``) and are
|
||||
resolved at runtime via ``resolve_variable`` from the ``use`` dotted path.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any, Protocol, runtime_checkable
|
||||
|
||||
from pydantic import BaseModel, Field
|
||||
|
||||
|
||||
class WriteGuardProviderConfig(BaseModel):
|
||||
"""Configuration for the application-layer WriteGuard implementations.
|
||||
|
||||
``policy_use`` resolves to a callable/class implementing
|
||||
``WriteGuardPolicy``; ``interceptor_use`` resolves to one implementing
|
||||
``WriteGuardInterceptor``. Both are resolved lazily by the harness via
|
||||
``deerflow.reflection.resolve_variable`` so the harness never imports
|
||||
``app.*``.
|
||||
"""
|
||||
|
||||
policy_use: str = Field(
|
||||
description="Dotted path to the WriteGuardPolicy factory, e.g. 'app.maf_roundtable.write_guard_bridge:make_policy'"
|
||||
)
|
||||
interceptor_use: str = Field(
|
||||
description="Dotted path to the WriteGuardInterceptor factory, e.g. 'app.maf_roundtable.write_guard_bridge:make_interceptor'"
|
||||
)
|
||||
config: dict = Field(default_factory=dict, description="Implementation-specific settings passed as kwargs")
|
||||
|
||||
|
||||
class WriteGuardConfig(BaseModel):
|
||||
"""Configuration for the WriteGuard middleware.
|
||||
|
||||
When ``enabled`` and a ``provider`` is configured, the harness appends a
|
||||
``WriteGuardMiddleware`` to the runtime middleware chain. The middleware
|
||||
itself only acts when the run context carries a ``maf_run_id`` flag —
|
||||
every other run is a pass-through.
|
||||
"""
|
||||
|
||||
enabled: bool = Field(default=False, description="Enable the WriteGuard middleware in the chain")
|
||||
provider: WriteGuardProviderConfig | None = Field(
|
||||
default=None, description="Application-layer policy/interceptor factories"
|
||||
)
|
||||
|
||||
|
||||
_write_guard_config: WriteGuardConfig | None = None
|
||||
|
||||
|
||||
def get_write_guard_config() -> WriteGuardConfig:
|
||||
"""Get the write-guard config, returning defaults if not loaded."""
|
||||
global _write_guard_config
|
||||
if _write_guard_config is None:
|
||||
_write_guard_config = WriteGuardConfig()
|
||||
return _write_guard_config
|
||||
|
||||
|
||||
def load_write_guard_config_from_dict(data: dict) -> WriteGuardConfig:
|
||||
"""Load write-guard config from a dict (called during AppConfig loading)."""
|
||||
global _write_guard_config
|
||||
_write_guard_config = WriteGuardConfig.model_validate(data)
|
||||
return _write_guard_config
|
||||
|
||||
|
||||
def reset_write_guard_config() -> None:
|
||||
"""Reset the cached config instance. Used in tests to prevent singleton leaks."""
|
||||
global _write_guard_config
|
||||
_write_guard_config = None
|
||||
|
||||
|
||||
# ── Protocols (harness ↔ application contract) ─────────────────────────────
|
||||
|
||||
|
||||
@runtime_checkable
|
||||
class WriteGuardPolicy(Protocol):
|
||||
"""Decides whether a given tool call must be intercepted for approval.
|
||||
|
||||
Implementations are constructed by the application layer and passed into
|
||||
the harness ``WriteGuardMiddleware``. They must NOT import deerflow.*
|
||||
(the harness owns this Protocol definition).
|
||||
"""
|
||||
|
||||
def should_intercept(self, tool_name: str, args: Any, run_context: dict | None = None) -> bool: # noqa: ANN401
|
||||
"""Return True if the tool call must be recorded for approval before execution.
|
||||
|
||||
``run_context`` (the shared run-context dict) lets the policy distinguish
|
||||
reads from writes using the frozen capability snapshot + write policy, so
|
||||
read tools are never intercepted (they pass straight through, including
|
||||
on the sync path) while writes are gated by the active write policy.
|
||||
"""
|
||||
...
|
||||
|
||||
|
||||
@runtime_checkable
|
||||
class WriteGuardInterceptor(Protocol):
|
||||
"""Records an intercepted write tool call (action + approval + audit event).
|
||||
|
||||
The interceptor is responsible for the full create-pending-action flow
|
||||
(see ``store.create_pending_action_bundle``). It receives the run context
|
||||
dict (the same one ``request.runtime.context`` exposes) so it can resolve
|
||||
the current ``session_id`` / ``run_id`` / ``agent_id`` / ``turn_index``
|
||||
and the write policy. It returns a dict describing the interception
|
||||
outcome so the middleware can build the ToolMessage the model sees in
|
||||
place of the real tool result.
|
||||
|
||||
Expected return shape::
|
||||
|
||||
{
|
||||
"status": "approval_required" | "allowed",
|
||||
"action_id": "<id when approval_required>",
|
||||
"approval_id": "<id when approval_required>",
|
||||
"tool_name": "<name>",
|
||||
}
|
||||
"""
|
||||
|
||||
async def intercept(
|
||||
self,
|
||||
*,
|
||||
tool_name: str,
|
||||
args: Any, # noqa: ANN401
|
||||
tool_call_id: str,
|
||||
run_context: dict,
|
||||
) -> dict[str, Any]:
|
||||
"""Record the tool call for approval. Never executes the real tool."""
|
||||
...
|
||||
|
||||
async def validate_approved_action(
|
||||
self,
|
||||
*,
|
||||
tool_name: str,
|
||||
run_context: dict,
|
||||
) -> bool:
|
||||
"""Validate a post-approval deterministic execution before it runs.
|
||||
|
||||
Called on the async path when the run context binds ``maf_approved_tool``
|
||||
+ ``maf_approved_action_id``. Must query the stored action and confirm:
|
||||
its status is ``running`` (the executor already occupied it), it belongs
|
||||
to the current ``run_id`` / ``session_id`` / ``agent_id``, and its
|
||||
``tool_name`` matches. Returns True only when all hold — the middleware
|
||||
fails closed (blocks the call) otherwise. Field-existence alone is NOT
|
||||
sufficient.
|
||||
"""
|
||||
...
|
||||
+16
-6
@@ -13,47 +13,57 @@ started (Phase 2+).
|
||||
|
||||
Tables (see the implementation plan §8):
|
||||
|
||||
- ``maf_roundtable_sessions`` — one MAF roundtable session (task + mode + capability snapshot)
|
||||
- ``maf_roundtable_participants`` — manager + seat agents bound to a session
|
||||
- ``maf_roundtable_runs`` — one execution run of a session
|
||||
- ``maf_roundtable_events`` — monotonic per-run event stream (``(run_id, seq)`` unique)
|
||||
- ``maf_roundtable_actions`` — external write / tool actions (idempotency-keyed)
|
||||
- ``maf_roundtable_approvals`` — pending human-approval requests
|
||||
- ``maf_roundtable_sessions`` — one MAF roundtable session (task + mode + capability snapshot)
|
||||
- ``maf_roundtable_participants`` — manager + seat agents bound to a session
|
||||
- ``maf_roundtable_runs`` — one execution run of a session
|
||||
- ``maf_roundtable_events`` — monotonic per-run event stream (``(run_id, seq)`` unique)
|
||||
- ``maf_roundtable_actions`` — external write / tool actions (idempotency-keyed)
|
||||
- ``maf_roundtable_approvals`` — pending human-approval requests
|
||||
- ``maf_roundtable_seat_runs`` — MAF↔DeerFlow run mapping (survives restart)
|
||||
- ``maf_roundtable_action_secrets`` — encrypted actual execution params (server-only)
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
|
||||
|
||||
from deerflow.persistence.maf_roundtable.action_secrets import MafActionSecretRepository
|
||||
from deerflow.persistence.maf_roundtable.actions import MafActionRepository
|
||||
from deerflow.persistence.maf_roundtable.approvals import MafApprovalRepository
|
||||
from deerflow.persistence.maf_roundtable.events import MafEventRepository
|
||||
from deerflow.persistence.maf_roundtable.model import (
|
||||
MafRoundtableActionRow,
|
||||
MafRoundtableActionSecretRow,
|
||||
MafRoundtableApprovalRow,
|
||||
MafRoundtableEventRow,
|
||||
MafRoundtableParticipantRow,
|
||||
MafRoundtableRunRow,
|
||||
MafRoundtableSeatRunRow,
|
||||
MafRoundtableSessionRow,
|
||||
)
|
||||
from deerflow.persistence.maf_roundtable.participants import MafParticipantRepository
|
||||
from deerflow.persistence.maf_roundtable.runs import MafRunRepository
|
||||
from deerflow.persistence.maf_roundtable.seat_runs import MafSeatRunRepository
|
||||
from deerflow.persistence.maf_roundtable.sessions import MafSessionRepository
|
||||
from deerflow.persistence.maf_roundtable.store import MafRoundtableStore
|
||||
|
||||
__all__ = [
|
||||
"MafActionRepository",
|
||||
"MafActionSecretRepository",
|
||||
"MafApprovalRepository",
|
||||
"MafEventRepository",
|
||||
"MafParticipantRepository",
|
||||
"MafRoundtableActionRow",
|
||||
"MafRoundtableActionSecretRow",
|
||||
"MafRoundtableApprovalRow",
|
||||
"MafRoundtableEventRow",
|
||||
"MafRoundtableParticipantRow",
|
||||
"MafRoundtableRunRow",
|
||||
"MafRoundtableSeatRunRow",
|
||||
"MafRoundtableSessionRow",
|
||||
"MafRoundtableStore",
|
||||
"MafRunRepository",
|
||||
"MafSeatRunRepository",
|
||||
"MafSessionRepository",
|
||||
"make_maf_roundtable_store",
|
||||
]
|
||||
|
||||
+65
@@ -0,0 +1,65 @@
|
||||
"""Action secrets repository — encrypted actual execution parameters.
|
||||
|
||||
Stores the **real** (un-redacted) tool-call arguments for a protected action
|
||||
so that after approval or a service restart the system can recover and
|
||||
execute the approved action with the original parameters. This repository is
|
||||
**server-only**: it is never read by any API endpoint, event serializer, log
|
||||
formatter, or frontend-facing query. The ActionCoordinator encrypts before
|
||||
writing and decrypts only at execution time.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from datetime import UTC, datetime
|
||||
from typing import Any
|
||||
from uuid import uuid4
|
||||
|
||||
from sqlalchemy import select
|
||||
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
|
||||
|
||||
from deerflow.persistence.maf_roundtable.model import MafRoundtableActionSecretRow
|
||||
|
||||
|
||||
def _now() -> datetime:
|
||||
return datetime.now(UTC)
|
||||
|
||||
|
||||
class MafActionSecretRepository:
|
||||
def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
|
||||
self._sf = session_factory
|
||||
|
||||
async def create(self, *, action_id: str, arguments_encrypted: str) -> dict[str, Any]:
|
||||
now = _now()
|
||||
row = MafRoundtableActionSecretRow(
|
||||
id=uuid4().hex,
|
||||
action_id=action_id,
|
||||
arguments_encrypted=arguments_encrypted,
|
||||
created_at=now,
|
||||
)
|
||||
async with self._sf() as session:
|
||||
session.add(row)
|
||||
await session.commit()
|
||||
return {"id": row.id, "action_id": action_id}
|
||||
|
||||
async def get_by_action(self, action_id: str) -> str | None:
|
||||
"""Return the encrypted arguments ciphertext for an action, or None."""
|
||||
async with self._sf() as session:
|
||||
stmt = (
|
||||
select(MafRoundtableActionSecretRow)
|
||||
.where(MafRoundtableActionSecretRow.action_id == action_id)
|
||||
.limit(1)
|
||||
)
|
||||
row = (await session.execute(stmt)).scalars().first()
|
||||
return row.arguments_encrypted if row is not None else None
|
||||
|
||||
async def delete_by_action(self, action_id: str) -> None:
|
||||
async with self._sf() as session:
|
||||
stmt = (
|
||||
select(MafRoundtableActionSecretRow)
|
||||
.where(MafRoundtableActionSecretRow.action_id == action_id)
|
||||
.limit(1)
|
||||
)
|
||||
row = (await session.execute(stmt)).scalars().first()
|
||||
if row is not None:
|
||||
await session.delete(row)
|
||||
await session.commit()
|
||||
+152
-2
@@ -14,7 +14,7 @@ from datetime import UTC, datetime
|
||||
from typing import Any
|
||||
from uuid import uuid4
|
||||
|
||||
from sqlalchemy import select
|
||||
from sqlalchemy import select, update
|
||||
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
|
||||
|
||||
from deerflow.persistence.maf_roundtable.model import MafRoundtableActionRow
|
||||
@@ -24,7 +24,8 @@ def _now() -> datetime:
|
||||
return datetime.now(UTC)
|
||||
|
||||
|
||||
def _to_dict(row: MafRoundtableActionRow) -> dict[str, Any]:
|
||||
def action_to_dict(row: MafRoundtableActionRow) -> dict[str, Any]:
|
||||
"""Serialise an action ORM row to a plain dict (public — reused by the store facade)."""
|
||||
return {
|
||||
"id": row.id,
|
||||
"session_id": row.session_id,
|
||||
@@ -32,6 +33,7 @@ def _to_dict(row: MafRoundtableActionRow) -> dict[str, Any]:
|
||||
"agent_id": row.agent_id,
|
||||
"tool_name": row.tool_name,
|
||||
"logical_action_id": row.logical_action_id,
|
||||
"turn_index": row.turn_index,
|
||||
"idempotency_key": row.idempotency_key,
|
||||
"target_key": row.target_key,
|
||||
"risk_level": row.risk_level,
|
||||
@@ -48,6 +50,25 @@ def _to_dict(row: MafRoundtableActionRow) -> dict[str, Any]:
|
||||
}
|
||||
|
||||
|
||||
# Back-compat alias for internal callers that used the old private name.
|
||||
_to_dict = action_to_dict
|
||||
|
||||
|
||||
class MafActionStateMachineError(RuntimeError):
|
||||
"""An action was claimed or transitioned from an unexpected state.
|
||||
|
||||
Raised when a claim loses the ``approved → running`` CAS and the row is in
|
||||
a state that is neither ``running`` (in progress elsewhere) nor a recognized
|
||||
terminal (``succeeded`` / ``failed`` / ``unknown`` / ``rejected``) — e.g.
|
||||
still ``waiting_approval`` / ``pending`` — meaning the caller tried to
|
||||
execute an action that was never properly approved.
|
||||
"""
|
||||
|
||||
|
||||
# Terminal statuses a failed claim may reflect back to the caller.
|
||||
_TERMINAL_CLAIM_STATUSES = ("succeeded", "failed", "unknown", "rejected")
|
||||
|
||||
|
||||
class MafActionRepository:
|
||||
def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
|
||||
self._sf = session_factory
|
||||
@@ -65,6 +86,7 @@ class MafActionRepository:
|
||||
agent_id=data.get("agent_id"),
|
||||
tool_name=str(data["tool_name"]),
|
||||
logical_action_id=data.get("logical_action_id"),
|
||||
turn_index=data.get("turn_index"),
|
||||
idempotency_key=str(data["idempotency_key"]),
|
||||
target_key=data.get("target_key"),
|
||||
risk_level=str(data.get("risk_level") or "R0"),
|
||||
@@ -135,3 +157,131 @@ class MafActionRepository:
|
||||
row.updated_at = _now()
|
||||
await session.commit()
|
||||
return _to_dict(row)
|
||||
|
||||
async def claim_for_execution(self, action_id: str) -> str:
|
||||
"""Atomically transition an action from ``approved`` to ``running``.
|
||||
|
||||
Single conditional UPDATE — only the caller whose UPDATE affects
|
||||
exactly one row wins the right to execute the external write. This
|
||||
guarantees at-most-once execution even under concurrent ``resume()``
|
||||
calls or retries after a restart.
|
||||
|
||||
Returns the effective claim status (callers must NOT treat a lost claim
|
||||
as a blanket "skip"):
|
||||
|
||||
- ``"claimed"`` — won the CAS; the caller may execute.
|
||||
- ``"in_progress"`` — another executor already moved it to ``running``.
|
||||
- ``"succeeded"`` / ``"failed"`` / ``"unknown"`` / ``"rejected"`` — the
|
||||
action is already in that terminal state.
|
||||
|
||||
Raises ``MafActionStateMachineError`` when the row is missing or in any
|
||||
other state (e.g. still ``waiting_approval`` / ``pending``) — i.e. it was
|
||||
never properly approved and must not be executed.
|
||||
"""
|
||||
now = _now()
|
||||
async with self._sf() as session:
|
||||
result = await session.execute(
|
||||
update(MafRoundtableActionRow)
|
||||
.where(
|
||||
MafRoundtableActionRow.id == action_id,
|
||||
MafRoundtableActionRow.status == "approved",
|
||||
)
|
||||
.values(status="running", started_at=now, updated_at=now)
|
||||
)
|
||||
await session.commit()
|
||||
if result.rowcount == 1: # type: ignore[union-attr]
|
||||
return "claimed"
|
||||
|
||||
# Lost the CAS (or never approved) — report the ACTUAL state.
|
||||
current = await self.get_action(action_id)
|
||||
if current is None:
|
||||
raise MafActionStateMachineError(f"action {action_id} not found during claim")
|
||||
status = current.get("status")
|
||||
if status == "running":
|
||||
return "in_progress"
|
||||
if status in _TERMINAL_CLAIM_STATUSES:
|
||||
return str(status)
|
||||
raise MafActionStateMachineError(
|
||||
f"action {action_id} cannot be claimed from state '{status}'"
|
||||
)
|
||||
|
||||
async def mark_approved(self, action_id: str) -> bool:
|
||||
"""Conditionally transition ``waiting_approval → approved``.
|
||||
|
||||
Returns True only if this call performed the transition (``rowcount==1``).
|
||||
A concurrent decider or an already-terminal action yields False — the
|
||||
caller must NOT overwrite a terminal state via a generic update.
|
||||
"""
|
||||
now = _now()
|
||||
async with self._sf() as session:
|
||||
result = await session.execute(
|
||||
update(MafRoundtableActionRow)
|
||||
.where(
|
||||
MafRoundtableActionRow.id == action_id,
|
||||
MafRoundtableActionRow.status == "waiting_approval",
|
||||
)
|
||||
.values(status="approved", updated_at=now)
|
||||
)
|
||||
await session.commit()
|
||||
return result.rowcount == 1 # type: ignore[union-attr]
|
||||
|
||||
async def mark_rejected(self, action_id: str) -> bool:
|
||||
"""Conditionally transition ``waiting_approval → rejected`` (+ finished_at).
|
||||
|
||||
Returns True only if this call performed the transition. Terminal states
|
||||
are never overwritten.
|
||||
"""
|
||||
now = _now()
|
||||
async with self._sf() as session:
|
||||
result = await session.execute(
|
||||
update(MafRoundtableActionRow)
|
||||
.where(
|
||||
MafRoundtableActionRow.id == action_id,
|
||||
MafRoundtableActionRow.status == "waiting_approval",
|
||||
)
|
||||
.values(status="rejected", finished_at=now, updated_at=now)
|
||||
)
|
||||
await session.commit()
|
||||
return result.rowcount == 1 # type: ignore[union-attr]
|
||||
|
||||
async def record_terminal_result(
|
||||
self,
|
||||
action_id: str,
|
||||
*,
|
||||
status: str,
|
||||
result: dict[str, Any] | None = None,
|
||||
external_object_id: str | None = None,
|
||||
) -> dict[str, Any] | None:
|
||||
"""Record the terminal outcome of an action execution.
|
||||
|
||||
State-machine constrained: only a ``running`` action may transition
|
||||
to a terminal status (``succeeded`` / ``failed`` / ``unknown``).
|
||||
A concurrent caller that lost the race (or a replay after restart)
|
||||
finds the row already terminal and its UPDATE is a no-op
|
||||
(``rowcount == 0``) — it must NOT overwrite the real result.
|
||||
"""
|
||||
if status not in ("succeeded", "failed", "unknown"):
|
||||
raise ValueError(f"invalid action result status: {status}")
|
||||
now = _now()
|
||||
async with self._sf() as session:
|
||||
result_q = await session.execute(
|
||||
update(MafRoundtableActionRow)
|
||||
.where(
|
||||
MafRoundtableActionRow.id == action_id,
|
||||
MafRoundtableActionRow.status == "running",
|
||||
)
|
||||
.values(
|
||||
status=status,
|
||||
result_redacted_json=result,
|
||||
external_object_id=external_object_id,
|
||||
finished_at=now,
|
||||
updated_at=now,
|
||||
)
|
||||
)
|
||||
await session.commit()
|
||||
# Use rowcount instead of .returning() for cross-DB compatibility
|
||||
# (SQLite, PostgreSQL, MySQL).
|
||||
if result_q.rowcount != 1: # type: ignore[union-attr]
|
||||
# Lost the race or not in running state — do not overwrite.
|
||||
return None
|
||||
return await self.get_action(action_id)
|
||||
+32
-1
@@ -46,6 +46,7 @@ def _to_dict(row: MafRoundtableEventRow) -> dict[str, Any]:
|
||||
"event_type": row.event_type,
|
||||
"agent_id": row.agent_id,
|
||||
"turn_index": row.turn_index,
|
||||
"source_event_id": row.source_event_id,
|
||||
"payload": row.payload_json,
|
||||
"created_at": row.created_at.isoformat() if isinstance(row.created_at, datetime) else row.created_at,
|
||||
}
|
||||
@@ -69,6 +70,7 @@ class MafEventRepository:
|
||||
agent_id: str | None = None,
|
||||
turn_index: int | None = None,
|
||||
payload: dict[str, Any] | None = None,
|
||||
source_event_id: str | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Append one event with a monotonic per-run seq.
|
||||
|
||||
@@ -77,7 +79,19 @@ class MafEventRepository:
|
||||
``last_event_seq`` cache is bumped forward (max wins) so pollers can
|
||||
cheaply check ``runs.last_event_seq`` without scanning the events
|
||||
table.
|
||||
|
||||
Durable dedup: when ``source_event_id`` is given, the
|
||||
``(run_id, source_event_id)`` unique constraint guarantees at-most-once
|
||||
persistence. A duplicate insert returns the already-stored row instead
|
||||
of raising — this survives process restarts (unlike an in-memory seen
|
||||
set), so a replayed runtime stream never double-writes an event.
|
||||
"""
|
||||
# Fast-path dedup: if this source_event_id already landed, return it.
|
||||
if source_event_id:
|
||||
existing = await self._get_by_source(run_id, source_event_id)
|
||||
if existing is not None:
|
||||
return existing
|
||||
|
||||
last_exc: Exception | None = None
|
||||
for _ in range(_SEQ_INSERT_RETRIES):
|
||||
async with self._sf() as session:
|
||||
@@ -97,6 +111,7 @@ class MafEventRepository:
|
||||
event_type=event_type,
|
||||
agent_id=agent_id,
|
||||
turn_index=turn_index,
|
||||
source_event_id=source_event_id,
|
||||
payload_json=payload,
|
||||
created_at=_now(),
|
||||
)
|
||||
@@ -104,8 +119,14 @@ class MafEventRepository:
|
||||
try:
|
||||
await session.commit()
|
||||
except IntegrityError as exc: # noqa: PERF203 - retry path
|
||||
last_exc = exc
|
||||
await session.rollback()
|
||||
# A source_event_id collision means a concurrent writer
|
||||
# already persisted this exact event — return its row.
|
||||
if source_event_id:
|
||||
dup = await self._get_by_source(run_id, source_event_id)
|
||||
if dup is not None:
|
||||
return dup
|
||||
last_exc = exc
|
||||
continue
|
||||
if self._run_repo is not None:
|
||||
# best-effort cache bump; never let a cache failure abort
|
||||
@@ -121,6 +142,15 @@ class MafEventRepository:
|
||||
orig=last_exc,
|
||||
)
|
||||
|
||||
async def _get_by_source(self, run_id: str, source_event_id: str) -> dict[str, Any] | None:
|
||||
stmt = select(MafRoundtableEventRow).where(
|
||||
MafRoundtableEventRow.run_id == run_id,
|
||||
MafRoundtableEventRow.source_event_id == source_event_id,
|
||||
)
|
||||
async with self._sf() as session:
|
||||
row = (await session.execute(stmt)).scalars().first()
|
||||
return _to_dict(row) if row is not None else None
|
||||
|
||||
async def append_events(
|
||||
self, *, session_id: str, run_id: str, events: list[dict[str, Any]]
|
||||
) -> list[dict[str, Any]]:
|
||||
@@ -138,6 +168,7 @@ class MafEventRepository:
|
||||
agent_id=ev.get("agent_id"),
|
||||
turn_index=ev.get("turn_index"),
|
||||
payload=ev.get("payload"),
|
||||
source_event_id=ev.get("source_event_id"),
|
||||
)
|
||||
)
|
||||
return out
|
||||
|
||||
+89
@@ -175,6 +175,13 @@ class MafRoundtableEventRow(Base):
|
||||
__tablename__ = "maf_roundtable_events"
|
||||
__table_args__ = (
|
||||
UniqueConstraint("run_id", "seq", name="uq_maf_events_run_seq"),
|
||||
# Dedup key for at-most-once event persistence. The authoritative
|
||||
# dedup is this DB constraint (survives process restarts) — not the
|
||||
# in-process ``_seen_source_ids`` set, which is only a fast-path cache.
|
||||
# ``source_event_id`` is nullable; rows with NULL are not deduped
|
||||
# (SQL treats NULLs as distinct in a UNIQUE constraint on sqlite /
|
||||
# postgres / mysql), so events without a source id stay append-only.
|
||||
UniqueConstraint("run_id", "source_event_id", name="uq_maf_events_run_source"),
|
||||
)
|
||||
|
||||
id: Mapped[str] = mapped_column(String(64), primary_key=True)
|
||||
@@ -194,6 +201,10 @@ class MafRoundtableEventRow(Base):
|
||||
event_type: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
|
||||
agent_id: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
|
||||
turn_index: Mapped[int | None] = mapped_column(Integer, nullable=True)
|
||||
# Upstream identity of the source runtime event (e.g. LangGraph message id
|
||||
# / tool_call id). Used by the ``(run_id, source_event_id)`` unique
|
||||
# constraint for durable at-most-once dedup across restarts.
|
||||
source_event_id: Mapped[str | None] = mapped_column(String(191), nullable=True, index=True)
|
||||
payload_json: Mapped[dict | None] = mapped_column(PortableJSON(), nullable=True)
|
||||
created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=_now, index=True)
|
||||
|
||||
@@ -227,6 +238,11 @@ class MafRoundtableActionRow(Base):
|
||||
agent_id: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
|
||||
tool_name: Mapped[str] = mapped_column(String(128), nullable=False, index=True)
|
||||
logical_action_id: Mapped[str | None] = mapped_column(String(128), nullable=True)
|
||||
# The seat turn that produced this action. Persisted (not only embedded in
|
||||
# the idempotency_key) so pending-approval matching can key on
|
||||
# run_id + agent_id + turn_index + logical_action_id precisely — never
|
||||
# mixing a seat's earlier-turn waiting actions into the current approval.
|
||||
turn_index: Mapped[int | None] = mapped_column(Integer, nullable=True)
|
||||
idempotency_key: Mapped[str] = mapped_column(String(191), nullable=False, unique=True)
|
||||
target_key: Mapped[str | None] = mapped_column(String(255), nullable=True, index=True)
|
||||
# R0 | R1 | R2 | R3 | R4
|
||||
@@ -280,11 +296,84 @@ class MafRoundtableApprovalRow(Base):
|
||||
)
|
||||
|
||||
|
||||
# ── 7. seat runs (Phase 2: MAF↔DeerFlow run mapping) ─────────────────────
|
||||
|
||||
|
||||
class MafRoundtableSeatRunRow(Base):
|
||||
"""Persistent mapping between a MAF workflow seat turn and its DeerFlow run.
|
||||
|
||||
Replaces the in-memory ``_active_runs`` dict so that after a service restart
|
||||
the system can still locate and cancel outstanding DeerFlow runs, and the
|
||||
MAF checkpoint can reference which seat turns completed.
|
||||
|
||||
Unique constraint: ``(maf_run_id, agent_id, turn_index)`` — one DeerFlow run
|
||||
per seat per turn.
|
||||
"""
|
||||
|
||||
__tablename__ = "maf_roundtable_seat_runs"
|
||||
__table_args__ = (
|
||||
UniqueConstraint("maf_run_id", "agent_id", "turn_index", name="uq_maf_seat_runs_run_agent_turn"),
|
||||
)
|
||||
|
||||
id: Mapped[str] = mapped_column(String(64), primary_key=True)
|
||||
maf_run_id: Mapped[str] = mapped_column(
|
||||
String(64), ForeignKey("maf_roundtable_runs.id", ondelete="CASCADE"), nullable=False, index=True
|
||||
)
|
||||
agent_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
|
||||
turn_index: Mapped[int] = mapped_column(Integer, nullable=False)
|
||||
deerflow_run_id: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
|
||||
deerflow_thread_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
|
||||
sandbox_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
|
||||
workflow_checkpoint_id: Mapped[str | None] = mapped_column(String(128), nullable=True)
|
||||
# pending | running | completed | failed | cancelled
|
||||
status: Mapped[str] = mapped_column(String(32), default="pending", index=True)
|
||||
started_at: Mapped[datetime | None] = mapped_column(BeijingDateTime(), nullable=True)
|
||||
finished_at: Mapped[datetime | None] = mapped_column(BeijingDateTime(), nullable=True)
|
||||
error: Mapped[str | None] = mapped_column(PortableLongText, nullable=True)
|
||||
created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=_now)
|
||||
updated_at: Mapped[datetime] = mapped_column(
|
||||
BeijingDateTime(), nullable=False, default=_now, onupdate=_now
|
||||
)
|
||||
|
||||
|
||||
# ── 8. action secrets (encrypted actual execution params, server-only) ────
|
||||
|
||||
|
||||
class MafRoundtableActionSecretRow(Base):
|
||||
"""Encrypted actual execution parameters for a protected action.
|
||||
|
||||
Stores the **real** (un-redacted) tool-call arguments so that after
|
||||
approval or a service restart the system can recover and execute the
|
||||
approved action with the original parameters. This table is **never**
|
||||
joined in any read query exposed to the API, events, logs, or frontend —
|
||||
it is server-only. The ActionCoordinator encrypts the payload before
|
||||
writing and decrypts only at execution time.
|
||||
|
||||
One row per action (unique ``action_id``). The encryption key is derived
|
||||
from the deployment's secret key; the ciphertext is opaque to the store.
|
||||
"""
|
||||
|
||||
__tablename__ = "maf_roundtable_action_secrets"
|
||||
__table_args__ = (
|
||||
UniqueConstraint("action_id", name="uq_maf_action_secrets_action"),
|
||||
)
|
||||
|
||||
id: Mapped[str] = mapped_column(String(64), primary_key=True)
|
||||
action_id: Mapped[str] = mapped_column(
|
||||
String(64), ForeignKey("maf_roundtable_actions.id", ondelete="CASCADE"),
|
||||
nullable=False, index=True,
|
||||
)
|
||||
arguments_encrypted: Mapped[str] = mapped_column(PortableLongText, nullable=False)
|
||||
created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=_now)
|
||||
|
||||
|
||||
__all__ = [
|
||||
"MafRoundtableActionRow",
|
||||
"MafRoundtableActionSecretRow",
|
||||
"MafRoundtableApprovalRow",
|
||||
"MafRoundtableEventRow",
|
||||
"MafRoundtableParticipantRow",
|
||||
"MafRoundtableRunRow",
|
||||
"MafRoundtableSeatRunRow",
|
||||
"MafRoundtableSessionRow",
|
||||
]
|
||||
+22
@@ -120,3 +120,25 @@ class MafParticipantRepository:
|
||||
row.updated_at = _now()
|
||||
await session.commit()
|
||||
return _to_dict(row)
|
||||
|
||||
async def bind_thread(
|
||||
self, session_id: str, agent_id: str, *, thread_id: str, sandbox_id: str | None = None
|
||||
) -> dict[str, Any] | None:
|
||||
async with self._sf() as session:
|
||||
stmt = (
|
||||
select(MafRoundtableParticipantRow)
|
||||
.where(
|
||||
MafRoundtableParticipantRow.session_id == session_id,
|
||||
MafRoundtableParticipantRow.agent_id == agent_id,
|
||||
)
|
||||
.limit(1)
|
||||
)
|
||||
row = (await session.execute(stmt)).scalars().first()
|
||||
if row is None:
|
||||
return None
|
||||
row.thread_id = thread_id
|
||||
if sandbox_id is not None:
|
||||
row.sandbox_id = sandbox_id
|
||||
row.updated_at = _now()
|
||||
await session.commit()
|
||||
return _to_dict(row)
|
||||
+21
@@ -118,6 +118,27 @@ class MafRunRepository:
|
||||
)
|
||||
await session.commit()
|
||||
|
||||
async def claim_for_resume(self, run_id: str) -> bool:
|
||||
"""Run-level CAS gating post-approval execution: ``waiting_approval → running``.
|
||||
|
||||
After every approval is decided, exactly one concurrent ``resume()`` may
|
||||
proceed to execute the approved actions and write the parent run's final
|
||||
state. The winner (``rowcount == 1``) executes; every other concurrent
|
||||
caller gets False and must return the current run WITHOUT writing a
|
||||
terminal status (so it can never race a ``completed``/``failed`` write).
|
||||
"""
|
||||
async with self._sf() as session:
|
||||
result = await session.execute(
|
||||
update(MafRoundtableRunRow)
|
||||
.where(
|
||||
MafRoundtableRunRow.id == run_id,
|
||||
MafRoundtableRunRow.status == "waiting_approval",
|
||||
)
|
||||
.values(status="running", started_at=_now(), updated_at=_now())
|
||||
)
|
||||
await session.commit()
|
||||
return result.rowcount == 1 # type: ignore[union-attr]
|
||||
|
||||
async def bump_last_event_seq(self, run_id: str, seq: int) -> None:
|
||||
"""Denormalized cache update — only bumps forward (max wins)."""
|
||||
async with self._sf() as session:
|
||||
|
||||
+195
@@ -0,0 +1,195 @@
|
||||
"""Seat run repository — persistent MAF↔DeerFlow run mapping.
|
||||
|
||||
Replaces the in-memory ``_active_runs`` dict. After a service restart the
|
||||
system can still locate and cancel outstanding DeerFlow runs via the
|
||||
persisted ``deerflow_run_id``.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from datetime import UTC, datetime
|
||||
from typing import Any
|
||||
from uuid import uuid4
|
||||
|
||||
from sqlalchemy import select, update
|
||||
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
|
||||
|
||||
from deerflow.persistence.maf_roundtable.model import MafRoundtableSeatRunRow
|
||||
|
||||
|
||||
def _now() -> datetime:
|
||||
return datetime.now(UTC)
|
||||
|
||||
|
||||
def _to_dict(row: MafRoundtableSeatRunRow) -> dict[str, Any]:
|
||||
return {
|
||||
"id": row.id,
|
||||
"maf_run_id": row.maf_run_id,
|
||||
"agent_id": row.agent_id,
|
||||
"turn_index": row.turn_index,
|
||||
"deerflow_run_id": row.deerflow_run_id,
|
||||
"deerflow_thread_id": row.deerflow_thread_id,
|
||||
"sandbox_id": row.sandbox_id,
|
||||
"workflow_checkpoint_id": row.workflow_checkpoint_id,
|
||||
"status": row.status,
|
||||
"started_at": row.started_at.isoformat() if isinstance(row.started_at, datetime) else row.started_at,
|
||||
"finished_at": row.finished_at.isoformat() if isinstance(row.finished_at, datetime) else row.finished_at,
|
||||
"error": row.error,
|
||||
"created_at": row.created_at.isoformat() if isinstance(row.created_at, datetime) else row.created_at,
|
||||
"updated_at": row.updated_at.isoformat() if isinstance(row.updated_at, datetime) else row.updated_at,
|
||||
}
|
||||
|
||||
|
||||
class MafSeatRunRepository:
|
||||
def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
|
||||
self._sf = session_factory
|
||||
|
||||
async def create_seat_run(
|
||||
self,
|
||||
*,
|
||||
maf_run_id: str,
|
||||
agent_id: str,
|
||||
turn_index: int,
|
||||
deerflow_thread_id: str | None = None,
|
||||
) -> dict[str, Any]:
|
||||
now = _now()
|
||||
row = MafRoundtableSeatRunRow(
|
||||
id=uuid4().hex,
|
||||
maf_run_id=maf_run_id,
|
||||
agent_id=agent_id,
|
||||
turn_index=turn_index,
|
||||
deerflow_thread_id=deerflow_thread_id,
|
||||
status="pending",
|
||||
created_at=now,
|
||||
updated_at=now,
|
||||
)
|
||||
async with self._sf() as session:
|
||||
session.add(row)
|
||||
await session.commit()
|
||||
return _to_dict(row)
|
||||
|
||||
async def mark_running(
|
||||
self, seat_run_id: str, *, deerflow_run_id: str, sandbox_id: str | None = None
|
||||
) -> None:
|
||||
async with self._sf() as session:
|
||||
await session.execute(
|
||||
update(MafRoundtableSeatRunRow)
|
||||
.where(MafRoundtableSeatRunRow.id == seat_run_id)
|
||||
.values(
|
||||
status="running",
|
||||
deerflow_run_id=deerflow_run_id,
|
||||
sandbox_id=sandbox_id,
|
||||
started_at=_now(),
|
||||
updated_at=_now(),
|
||||
)
|
||||
)
|
||||
await session.commit()
|
||||
|
||||
async def mark_completed(self, seat_run_id: str, *, checkpoint_id: str | None = None) -> None:
|
||||
async with self._sf() as session:
|
||||
await session.execute(
|
||||
update(MafRoundtableSeatRunRow)
|
||||
.where(MafRoundtableSeatRunRow.id == seat_run_id)
|
||||
.values(
|
||||
status="completed",
|
||||
workflow_checkpoint_id=checkpoint_id,
|
||||
finished_at=_now(),
|
||||
updated_at=_now(),
|
||||
)
|
||||
)
|
||||
await session.commit()
|
||||
|
||||
async def mark_failed(self, seat_run_id: str, *, error: str | None = None) -> None:
|
||||
async with self._sf() as session:
|
||||
await session.execute(
|
||||
update(MafRoundtableSeatRunRow)
|
||||
.where(MafRoundtableSeatRunRow.id == seat_run_id)
|
||||
.values(status="failed", error=error, finished_at=_now(), updated_at=_now())
|
||||
)
|
||||
await session.commit()
|
||||
|
||||
async def mark_cancelled(self, seat_run_id: str) -> None:
|
||||
async with self._sf() as session:
|
||||
await session.execute(
|
||||
update(MafRoundtableSeatRunRow)
|
||||
.where(MafRoundtableSeatRunRow.id == seat_run_id)
|
||||
.values(status="cancelled", finished_at=_now(), updated_at=_now())
|
||||
)
|
||||
await session.commit()
|
||||
|
||||
async def mark_cancelling(self, seat_run_id: str) -> None:
|
||||
"""Mark a seat run as cancelling (cancel requested, not yet confirmed)."""
|
||||
async with self._sf() as session:
|
||||
await session.execute(
|
||||
update(MafRoundtableSeatRunRow)
|
||||
.where(MafRoundtableSeatRunRow.id == seat_run_id)
|
||||
.values(status="cancelling", updated_at=_now())
|
||||
)
|
||||
await session.commit()
|
||||
|
||||
async def mark_cancel_failed(self, seat_run_id: str, *, error: str | None = None) -> None:
|
||||
"""Mark a seat run as cancel_failed (DeerFlow cancel did not succeed)."""
|
||||
async with self._sf() as session:
|
||||
await session.execute(
|
||||
update(MafRoundtableSeatRunRow)
|
||||
.where(MafRoundtableSeatRunRow.id == seat_run_id)
|
||||
.values(status="cancel_failed", error=error, updated_at=_now())
|
||||
)
|
||||
await session.commit()
|
||||
|
||||
async def mark_cancel_unknown(self, seat_run_id: str, *, error: str | None = None) -> None:
|
||||
"""Mark a seat run's cancel outcome as unknown (e.g. no DeerFlow run id)."""
|
||||
async with self._sf() as session:
|
||||
await session.execute(
|
||||
update(MafRoundtableSeatRunRow)
|
||||
.where(MafRoundtableSeatRunRow.id == seat_run_id)
|
||||
.values(status="cancel_unknown", error=error, updated_at=_now())
|
||||
)
|
||||
await session.commit()
|
||||
|
||||
async def get_active_by_maf_run(self, maf_run_id: str) -> list[dict[str, Any]]:
|
||||
stmt = (
|
||||
select(MafRoundtableSeatRunRow)
|
||||
.where(
|
||||
MafRoundtableSeatRunRow.maf_run_id == maf_run_id,
|
||||
MafRoundtableSeatRunRow.status.in_(("pending", "running")),
|
||||
)
|
||||
)
|
||||
async with self._sf() as session:
|
||||
rows = (await session.execute(stmt)).scalars().all()
|
||||
return [_to_dict(r) for r in rows]
|
||||
|
||||
async def get_by_maf_run(self, maf_run_id: str) -> list[dict[str, Any]]:
|
||||
stmt = (
|
||||
select(MafRoundtableSeatRunRow)
|
||||
.where(MafRoundtableSeatRunRow.maf_run_id == maf_run_id)
|
||||
.order_by(MafRoundtableSeatRunRow.turn_index.asc())
|
||||
)
|
||||
async with self._sf() as session:
|
||||
rows = (await session.execute(stmt)).scalars().all()
|
||||
return [_to_dict(r) for r in rows]
|
||||
|
||||
async def cancel_all_active(self, maf_run_id: str) -> list[dict[str, Any]]:
|
||||
"""Mark all active seat runs as cancelling and return their info.
|
||||
|
||||
Two-phase cancel: first mark as ``cancelling``, then the caller
|
||||
actually cancels the DeerFlow runs and calls ``mark_cancelled`` or
|
||||
``mark_cancel_failed`` per seat run. Returns list of
|
||||
``{seat_run_id, deerflow_run_id}`` dicts.
|
||||
"""
|
||||
stmt = (
|
||||
select(MafRoundtableSeatRunRow)
|
||||
.where(
|
||||
MafRoundtableSeatRunRow.maf_run_id == maf_run_id,
|
||||
MafRoundtableSeatRunRow.status.in_(("pending", "running")),
|
||||
)
|
||||
)
|
||||
async with self._sf() as session:
|
||||
rows = (await session.execute(stmt)).scalars().all()
|
||||
result = []
|
||||
for row in rows:
|
||||
row.status = "cancelling"
|
||||
row.updated_at = _now()
|
||||
result.append({"seat_run_id": row.id, "deerflow_run_id": row.deerflow_run_id})
|
||||
await session.commit()
|
||||
return result
|
||||
+314
-7
@@ -18,21 +18,31 @@ from datetime import UTC, datetime
|
||||
from typing import Any
|
||||
from uuid import uuid4
|
||||
|
||||
from sqlalchemy import select, update
|
||||
from sqlalchemy import func, select, update
|
||||
from sqlalchemy.exc import IntegrityError
|
||||
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
|
||||
|
||||
from deerflow.persistence.maf_roundtable.actions import MafActionRepository
|
||||
from deerflow.persistence.maf_roundtable.action_secrets import MafActionSecretRepository
|
||||
from deerflow.persistence.maf_roundtable.actions import MafActionRepository, action_to_dict
|
||||
from deerflow.persistence.maf_roundtable.approvals import MafApprovalRepository
|
||||
from deerflow.persistence.maf_roundtable.events import MafEventRepository
|
||||
from deerflow.persistence.maf_roundtable.model import MafRoundtableRunRow, MafRoundtableSessionRow
|
||||
from deerflow.persistence.maf_roundtable.model import (
|
||||
MafRoundtableActionRow,
|
||||
MafRoundtableActionSecretRow,
|
||||
MafRoundtableApprovalRow,
|
||||
MafRoundtableEventRow,
|
||||
MafRoundtableRunRow,
|
||||
MafRoundtableSessionRow,
|
||||
)
|
||||
from deerflow.persistence.maf_roundtable.participants import MafParticipantRepository
|
||||
from deerflow.persistence.maf_roundtable.runs import MafRunRepository, run_to_dict
|
||||
from deerflow.persistence.maf_roundtable.seat_runs import MafSeatRunRepository
|
||||
from deerflow.persistence.maf_roundtable.sessions import MafSessionRepository
|
||||
|
||||
# Session statuses that mean a run is in flight — the CAS claim refuses these.
|
||||
_ACTIVE_SESSION_STATUSES = ("starting", "running", "waiting_approval", "waiting_input")
|
||||
_ACTIVE_SESSION_STATUSES = ("starting", "running", "waiting_approval", "waiting_input", "cancelling", "cancel_failed")
|
||||
# Run statuses that are still in flight (cancellable).
|
||||
_ACTIVE_RUN_STATUSES = ("pending", "running", "waiting_approval", "waiting_input")
|
||||
_ACTIVE_RUN_STATUSES = ("pending", "running", "waiting_approval", "waiting_input", "cancelling", "cancel_failed")
|
||||
# Run statuses that are terminal (cannot be re-cancelled).
|
||||
_TERMINAL_RUN_STATUSES = ("completed", "failed", "cancelled")
|
||||
|
||||
@@ -57,6 +67,8 @@ class MafRoundtableStore:
|
||||
self.events = MafEventRepository(session_factory, run_repo=self.runs)
|
||||
self.actions = MafActionRepository(session_factory)
|
||||
self.approvals = MafApprovalRepository(session_factory)
|
||||
self.seat_runs = MafSeatRunRepository(session_factory)
|
||||
self.action_secrets = MafActionSecretRepository(session_factory)
|
||||
|
||||
@property
|
||||
def session_factory(self) -> async_sessionmaker[AsyncSession]:
|
||||
@@ -160,13 +172,15 @@ class MafRoundtableStore:
|
||||
|
||||
if run_row.status in _ACTIVE_RUN_STATUSES:
|
||||
# Normal cancel: run + session → cancelled.
|
||||
# Also handles cancel_failed → cancelled retry.
|
||||
run_row.status = "cancelled"
|
||||
run_row.finished_at = now
|
||||
run_row.updated_at = now
|
||||
session_row.status = "cancelled"
|
||||
session_row.updated_at = now
|
||||
elif run_row.status == "cancelled":
|
||||
# Already cancelled — repair session if still active.
|
||||
elif run_row.status == "cancelled" or run_row.status == "cancel_failed":
|
||||
# Already cancelled / previously failed cancel — repair
|
||||
# session if still active.
|
||||
if session_row.status in _ACTIVE_SESSION_STATUSES:
|
||||
session_row.status = "cancelled"
|
||||
session_row.updated_at = now
|
||||
@@ -180,9 +194,302 @@ class MafRoundtableStore:
|
||||
await db.flush()
|
||||
return run_to_dict(run_row)
|
||||
|
||||
async def start_cancel_atomically(
|
||||
self,
|
||||
*,
|
||||
run_id: str,
|
||||
owner_user_id: str,
|
||||
) -> dict[str, Any] | None:
|
||||
"""Atomically transition a run to ``cancelling`` (not yet ``cancelled``).
|
||||
|
||||
Phase 1 of the two-phase cancel cascade:
|
||||
1. Router calls this → run+session enter ``cancelling``.
|
||||
2. Router calls ``dispatcher.cancel(run_id)`` which cascades to
|
||||
DeerFlow sub-runs.
|
||||
3. After the cascade, ``cancel_run_atomically`` finalizes to
|
||||
``cancelled``.
|
||||
|
||||
Returns the updated run dict, or None if the run is missing,
|
||||
wrong-owner, or already terminal.
|
||||
"""
|
||||
now = _now()
|
||||
async with self._sf() as db:
|
||||
async with db.begin():
|
||||
stmt = (
|
||||
select(MafRoundtableRunRow, MafRoundtableSessionRow)
|
||||
.join(
|
||||
MafRoundtableSessionRow,
|
||||
MafRoundtableRunRow.session_id == MafRoundtableSessionRow.id,
|
||||
)
|
||||
.where(
|
||||
MafRoundtableRunRow.id == run_id,
|
||||
MafRoundtableSessionRow.user_id == owner_user_id,
|
||||
)
|
||||
.with_for_update()
|
||||
)
|
||||
row = (await db.execute(stmt)).first()
|
||||
if row is None:
|
||||
return None
|
||||
|
||||
run_row, session_row = row
|
||||
|
||||
# Transition ANY active (or cancel_failed retry) run to cancelling.
|
||||
# Includes: pending (not yet executing), running, waiting_*,
|
||||
# cancelling (no-op, return current), cancel_failed (retry).
|
||||
if run_row.status in _ACTIVE_RUN_STATUSES and run_row.status != "cancelling":
|
||||
run_row.status = "cancelling"
|
||||
run_row.updated_at = now
|
||||
session_row.status = "cancelling"
|
||||
session_row.updated_at = now
|
||||
await db.flush()
|
||||
return run_to_dict(run_row)
|
||||
|
||||
# Already cancelling or terminal — return current state.
|
||||
return run_to_dict(run_row)
|
||||
|
||||
async def mark_cancel_failed_atomically(
|
||||
self,
|
||||
*,
|
||||
run_id: str,
|
||||
owner_user_id: str,
|
||||
error_code: str | None = None,
|
||||
error_message: str | None = None,
|
||||
) -> dict[str, Any] | None:
|
||||
"""Atomically mark run+session as ``cancel_failed``.
|
||||
|
||||
Unlike ``mark_cancel_failed`` in service.py (which only updates run),
|
||||
this writes run AND session in a single transaction so their statuses
|
||||
never diverge. ``cancel_failed`` is a non-terminal state: the user
|
||||
can retry cancel later.
|
||||
"""
|
||||
now = _now()
|
||||
async with self._sf() as db:
|
||||
async with db.begin():
|
||||
stmt = (
|
||||
select(MafRoundtableRunRow, MafRoundtableSessionRow)
|
||||
.join(
|
||||
MafRoundtableSessionRow,
|
||||
MafRoundtableRunRow.session_id == MafRoundtableSessionRow.id,
|
||||
)
|
||||
.where(
|
||||
MafRoundtableRunRow.id == run_id,
|
||||
MafRoundtableSessionRow.user_id == owner_user_id,
|
||||
)
|
||||
.with_for_update()
|
||||
)
|
||||
row = (await db.execute(stmt)).first()
|
||||
if row is None:
|
||||
return None
|
||||
|
||||
run_row, session_row = row
|
||||
|
||||
if run_row.status not in ("cancelling", "cancel_failed"):
|
||||
return run_to_dict(run_row)
|
||||
|
||||
run_row.status = "cancel_failed"
|
||||
run_row.updated_at = now
|
||||
if error_code:
|
||||
run_row.error_code = error_code
|
||||
if error_message:
|
||||
run_row.error_message_safe = error_message
|
||||
session_row.status = "cancel_failed"
|
||||
session_row.updated_at = now
|
||||
await db.flush()
|
||||
return run_to_dict(run_row)
|
||||
|
||||
async def create_pending_action_bundle(
|
||||
self,
|
||||
*,
|
||||
session_id: str,
|
||||
run_id: str,
|
||||
agent_id: str,
|
||||
tool_name: str,
|
||||
logical_action_id: str | None,
|
||||
idempotency_key: str,
|
||||
risk_level: str,
|
||||
target_key: str | None,
|
||||
turn_index: int | None = None,
|
||||
arguments_sanitized: dict[str, Any] | None,
|
||||
arguments_encrypted: str,
|
||||
approval_summary: str,
|
||||
approval_payload: dict[str, Any] | None,
|
||||
audit_event_agent_id: str,
|
||||
audit_event_turn_index: int,
|
||||
) -> dict[str, Any]:
|
||||
"""Create an action + secret + approval + audit event in ONE transaction.
|
||||
|
||||
All four writes share a single ``AsyncSession`` + ``begin()`` so that
|
||||
any failure rolls everything back — the database never holds a
|
||||
half-finished action (action without secret / approval / event).
|
||||
|
||||
Idempotency: ``idempotency_key`` is DB-unique. A concurrent duplicate
|
||||
submission loses the INSERT (``IntegrityError``); the method then
|
||||
re-reads and returns the already-stored action instead of raising,
|
||||
so a retry never fails the run.
|
||||
|
||||
**P1-6 concurrent retry**: when multiple parallel seat turns create
|
||||
action bundles concurrently, the ``MAX(seq)+1`` approach may collide
|
||||
on the ``(run_id, seq)`` unique constraint. This method retries up to
|
||||
``_MAX_BUNDLE_RETRIES`` times, re-computing ``next_seq`` from the
|
||||
latest committed state inside a fresh transaction each time.
|
||||
|
||||
Returns the stored action dict (with ``approval_id`` linked). The
|
||||
returned dict carries a ``"_idempotent_replay"`` flag (True when an
|
||||
existing action was returned rather than newly created).
|
||||
"""
|
||||
_MAX_BUNDLE_RETRIES = 8
|
||||
|
||||
# Idempotency fast-path: check if an identical action already exists
|
||||
# (concurrent retry / replay after restart). This check is outside the
|
||||
# retry loop because idempotency key duplicates are independent of seq
|
||||
# collisions.
|
||||
async with self._sf() as db:
|
||||
existing = await db.execute(
|
||||
select(MafRoundtableActionRow).where(
|
||||
MafRoundtableActionRow.idempotency_key == idempotency_key
|
||||
).limit(1)
|
||||
)
|
||||
existing_row = existing.scalars().first()
|
||||
if existing_row is not None:
|
||||
d = action_to_dict(existing_row)
|
||||
d["_idempotent_replay"] = True
|
||||
return d
|
||||
|
||||
now = _now()
|
||||
action_id = uuid4().hex
|
||||
last_error: Exception | None = None
|
||||
|
||||
for attempt in range(1, _MAX_BUNDLE_RETRIES + 1):
|
||||
async with self._sf() as db:
|
||||
async with db.begin():
|
||||
# Re-check idempotency inside transaction (concurrent writer
|
||||
# may have committed between attempts).
|
||||
existing = await db.execute(
|
||||
select(MafRoundtableActionRow).where(
|
||||
MafRoundtableActionRow.idempotency_key == idempotency_key
|
||||
).limit(1)
|
||||
)
|
||||
existing_row2 = existing.scalars().first()
|
||||
if existing_row2 is not None:
|
||||
d = action_to_dict(existing_row2)
|
||||
d["_idempotent_replay"] = True
|
||||
return d
|
||||
|
||||
# 1. action row.
|
||||
action_row = MafRoundtableActionRow(
|
||||
id=action_id,
|
||||
session_id=session_id,
|
||||
run_id=run_id,
|
||||
agent_id=agent_id,
|
||||
tool_name=tool_name,
|
||||
logical_action_id=logical_action_id,
|
||||
idempotency_key=idempotency_key,
|
||||
target_key=target_key,
|
||||
turn_index=turn_index,
|
||||
risk_level=risk_level,
|
||||
status="waiting_approval",
|
||||
arguments_redacted_json=arguments_sanitized,
|
||||
created_at=now,
|
||||
updated_at=now,
|
||||
)
|
||||
db.add(action_row)
|
||||
try:
|
||||
await db.flush()
|
||||
except IntegrityError:
|
||||
last_error = IntegrityError("action row insert conflict", orig=None, params={})
|
||||
await db.rollback()
|
||||
# Re-read — another writer may have created the action.
|
||||
async with self._sf() as db2:
|
||||
existing3 = await db2.execute(
|
||||
select(MafRoundtableActionRow).where(
|
||||
MafRoundtableActionRow.idempotency_key == idempotency_key
|
||||
).limit(1)
|
||||
)
|
||||
er = existing3.scalars().first()
|
||||
if er is not None:
|
||||
d = action_to_dict(er)
|
||||
d["_idempotent_replay"] = True
|
||||
return d
|
||||
continue
|
||||
|
||||
# 2. encrypted secret (server-only).
|
||||
db.add(MafRoundtableActionSecretRow(
|
||||
id=uuid4().hex,
|
||||
action_id=action_id,
|
||||
arguments_encrypted=arguments_encrypted,
|
||||
created_at=now,
|
||||
))
|
||||
await db.flush()
|
||||
|
||||
# 3. approval row (pending).
|
||||
approval_id = uuid4().hex
|
||||
db.add(MafRoundtableApprovalRow(
|
||||
id=approval_id,
|
||||
session_id=session_id,
|
||||
run_id=run_id,
|
||||
action_id=action_id,
|
||||
requested_by_agent_id=agent_id,
|
||||
status="pending",
|
||||
summary=approval_summary,
|
||||
payload_redacted_json=approval_payload,
|
||||
created_at=now,
|
||||
updated_at=now,
|
||||
))
|
||||
await db.flush()
|
||||
|
||||
# 4. link approval back to action.
|
||||
action_row.approval_id = approval_id
|
||||
action_row.updated_at = now
|
||||
await db.flush()
|
||||
|
||||
# 5. critical audit event — action.waiting_approval.
|
||||
# Recompute seq fresh inside each attempt/transaction.
|
||||
max_seq = (
|
||||
await db.execute(
|
||||
select(func.max(MafRoundtableEventRow.seq)).where(
|
||||
MafRoundtableEventRow.run_id == run_id
|
||||
)
|
||||
)
|
||||
).scalar_one()
|
||||
next_seq = int(max_seq or 0) + 1
|
||||
db.add(MafRoundtableEventRow(
|
||||
id=uuid4().hex,
|
||||
session_id=session_id,
|
||||
run_id=run_id,
|
||||
seq=next_seq,
|
||||
event_type="action.waiting_approval",
|
||||
agent_id=audit_event_agent_id,
|
||||
turn_index=audit_event_turn_index,
|
||||
payload_json={
|
||||
"action_id": action_id,
|
||||
"approval_id": approval_id,
|
||||
"tool_name": tool_name,
|
||||
"risk_level": risk_level,
|
||||
},
|
||||
created_at=now,
|
||||
))
|
||||
try:
|
||||
await db.flush()
|
||||
except IntegrityError:
|
||||
# (run_id, seq) collision — retry with fresh seq.
|
||||
last_error = IntegrityError("event seq collision", orig=None, params={})
|
||||
await db.rollback()
|
||||
continue
|
||||
|
||||
result = action_to_dict(action_row)
|
||||
result["approval_id"] = approval_id
|
||||
result["_idempotent_replay"] = False
|
||||
return result
|
||||
|
||||
raise RuntimeError(
|
||||
f"create_pending_action_bundle failed after {_MAX_BUNDLE_RETRIES} attempts "
|
||||
f"for idempotency_key={idempotency_key}"
|
||||
) from last_error
|
||||
|
||||
|
||||
__all__ = [
|
||||
"MafActionRepository",
|
||||
"MafActionSecretRepository",
|
||||
"MafApprovalRepository",
|
||||
"MafEventRepository",
|
||||
"MafParticipantRepository",
|
||||
|
||||
+482
@@ -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,
|
||||
}
|
||||
Reference in new issue
Block a user