feat(maf): add secure roundtable workflow runtime

This commit is contained in:
董宏凯 committed 2026-08-01 17:51:53 +08:00
1 parent e690475e6e
commit bd4131b4e2
52 files changed
+10315 -96

No files matched your search

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