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
@@ -328,13 +328,41 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
|
||||
maf_admin_diag = (
|
||||
bool(getattr(maf_cfg, "admin_diagnostic_access", True)) if maf_cfg is not None else True
|
||||
)
|
||||
# P0-4: when MAF is switched on, its full safety stack must be in
|
||||
# place (write_guard mounted + provider complete + bridge resolvable
|
||||
# + MAF_ACTION_SECRET_KEY set). If any prerequisite is missing the
|
||||
# feature is forced OFF (clearly logged) — never "MAF on, approval
|
||||
# guard not mounted". Reads stay open for admin history review.
|
||||
if maf_enabled:
|
||||
from app.maf_roundtable.service import (
|
||||
MafConfigurationError,
|
||||
validate_maf_prerequisites,
|
||||
)
|
||||
|
||||
try:
|
||||
validate_maf_prerequisites()
|
||||
except MafConfigurationError as cfg_exc:
|
||||
logger.error(
|
||||
"[maf-roundtable] enabled but prerequisites unmet — "
|
||||
"forcing the feature OFF: %s",
|
||||
cfg_exc,
|
||||
)
|
||||
maf_enabled = False
|
||||
if app.state.maf_roundtable_store is not None:
|
||||
app.state.maf_roundtable_service = MafRoundtableService(
|
||||
app.state.maf_roundtable_store,
|
||||
enabled=maf_enabled,
|
||||
admin_diagnostic_access=maf_admin_diag,
|
||||
config=maf_cfg,
|
||||
agent_store=getattr(app.state, "agent_store", None),
|
||||
app_config=config,
|
||||
)
|
||||
# Wire the WriteGuard bridge so the harness middleware can reach
|
||||
# the service when intercepting external-write tool calls.
|
||||
if app.state.maf_roundtable_service is not None:
|
||||
from app.maf_roundtable.write_guard_bridge import register_write_guard_service
|
||||
|
||||
register_write_guard_service(app.state.maf_roundtable_service)
|
||||
else:
|
||||
app.state.maf_roundtable_service = None
|
||||
except Exception: # noqa: BLE001 — experimental feature must never abort startup
|
||||
|
||||
@@ -198,12 +198,31 @@ async def delete_session(request: Request, session_id: str) -> dict[str, Any]:
|
||||
async def create_run(request: Request, session_id: str, body: CreateRunRequest) -> RunResponse:
|
||||
svc = _require_service(request)
|
||||
user_id, is_admin = _user_ctx(request)
|
||||
|
||||
# Check MAF SDK availability BEFORE creating the run — so the user gets a
|
||||
# clean 503 rather than a run that will immediately fail.
|
||||
from app.maf_roundtable.dispatcher import MafSdkNotAvailableError, get_dispatcher
|
||||
|
||||
dispatcher = get_dispatcher(request.app)
|
||||
try:
|
||||
dispatcher.check_sdk_available()
|
||||
except MafSdkNotAvailableError as exc:
|
||||
raise HTTPException(status_code=503, detail=str(exc)) from exc
|
||||
|
||||
try:
|
||||
run = await svc.create_run(
|
||||
session_id=session_id, user_id=user_id, workflow_version=body.workflow_version, is_admin=is_admin
|
||||
)
|
||||
except (MafDisabledError, MafForbiddenError, MafNotFoundError, MafConflictError) as exc:
|
||||
raise _map_service_error(exc) from exc
|
||||
|
||||
# Launch the workflow in the background. The run is already persisted as
|
||||
# "pending"; the dispatcher transitions it to "running" then completes/fails it.
|
||||
# Auto-dispatch can be disabled (e.g. in tests) via app.state.maf_auto_dispatch=False.
|
||||
if getattr(request.app.state, "maf_auto_dispatch", True):
|
||||
session = await svc.get_session(session_id=session_id, user_id=user_id, is_admin=is_admin)
|
||||
await dispatcher.dispatch(session, run, user_id=user_id or "default")
|
||||
|
||||
return RunResponse(**run)
|
||||
|
||||
|
||||
@@ -233,11 +252,43 @@ async def get_run(request: Request, run_id: str) -> RunResponse:
|
||||
async def cancel_run(request: Request, run_id: str) -> RunResponse:
|
||||
svc = _require_service(request)
|
||||
user_id, is_admin = _user_ctx(request)
|
||||
|
||||
# Phase 1: atomically set run+session to cancelling (not yet cancelled).
|
||||
try:
|
||||
run = await svc.cancel_run(run_id=run_id, user_id=user_id, is_admin=is_admin)
|
||||
await svc.start_cancel(run_id=run_id, user_id=user_id, is_admin=is_admin)
|
||||
except (MafDisabledError, MafForbiddenError, MafNotFoundError) as exc:
|
||||
raise _map_service_error(exc) from exc
|
||||
return RunResponse(**run)
|
||||
|
||||
# Phase 2: cascade cancel to the background task + DeerFlow sub-runs.
|
||||
from app.maf_roundtable.dispatcher import get_dispatcher
|
||||
|
||||
dispatcher = get_dispatcher(request.app)
|
||||
result = await dispatcher.cancel(run_id)
|
||||
|
||||
# Phase 3: finalize based on the structured cancel result.
|
||||
# - all_cancelled → finalize to ``cancelled`` (terminal).
|
||||
# - some sub-runs failed/still active → mark ``cancel_failed`` (non-terminal)
|
||||
# so the failure is visible and retryable. A failed cancel must NEVER
|
||||
# masquerade as cancelled.
|
||||
try:
|
||||
if result.get("all_cancelled"):
|
||||
final_run = await svc.finalize_cancel(run_id=run_id, user_id=user_id, is_admin=is_admin)
|
||||
else:
|
||||
failed = result.get("failed_run_ids") or []
|
||||
still_active = result.get("still_active_run_ids") or []
|
||||
detail = []
|
||||
if failed:
|
||||
detail.append(f"{len(failed)} sub-run(s) failed to cancel")
|
||||
if still_active:
|
||||
detail.append(f"{len(still_active)} sub-run(s) had no DeerFlow run id")
|
||||
reason = "; ".join(detail) or "cancel cascade incomplete"
|
||||
final_run = await svc.mark_cancel_failed(
|
||||
run_id=run_id, user_id=user_id, is_admin=is_admin, reason=reason
|
||||
)
|
||||
except (MafDisabledError, MafForbiddenError, MafNotFoundError) as exc:
|
||||
raise _map_service_error(exc) from exc
|
||||
|
||||
return RunResponse(**final_run)
|
||||
|
||||
|
||||
# ── events ─────────────────────────────────────────────────────────────────
|
||||
@@ -310,4 +361,25 @@ async def decide_approval(request: Request, approval_id: str, body: ApprovalDeci
|
||||
)
|
||||
except (MafDisabledError, MafForbiddenError, MafNotFoundError, MafConflictError) as exc:
|
||||
raise _map_service_error(exc) from exc
|
||||
|
||||
# P1: after a successful approval decision, resume the workflow from its
|
||||
# checkpoint. Only the owner can resume (decide_approval already enforced
|
||||
# owner-only write). The resume loads the checkpoint, restores
|
||||
# RoundtableState.from_dict(), and executes the approved action (at-most-once).
|
||||
run_id = approval.get("run_id")
|
||||
if run_id and body.decision in ("approved", "rejected"):
|
||||
from app.maf_roundtable.dispatcher import get_dispatcher
|
||||
|
||||
dispatcher = get_dispatcher(request.app)
|
||||
try:
|
||||
await dispatcher.resume(run_id, user_id=user_id or "default")
|
||||
except Exception:
|
||||
# Resume failure should not fail the approval response itself —
|
||||
# the approval is already persisted. Log for observability.
|
||||
import logging
|
||||
|
||||
logging.getLogger(__name__).exception(
|
||||
"MAF resume failed for run %s after approval %s", run_id, approval_id
|
||||
)
|
||||
|
||||
return ApprovalResponse(**approval)
|
||||
@@ -0,0 +1,386 @@
|
||||
"""Action Coordinator for the MAF roundtable experiment (Phase 2 P1).
|
||||
|
||||
Intercepts external-write tool calls **before** they reach the real external
|
||||
system. The current problem (pre-fix) was that seats executed DeerFlow tools
|
||||
first and the ApprovalGate only inspected ``tool_calls`` afterwards — too
|
||||
late. The ActionCoordinator fixes this by:
|
||||
|
||||
1. **Classification**: reads per-tool risk metadata from the frozen
|
||||
capability snapshot (``side_effect: read|write``, ``risk_level: R0–R4``).
|
||||
Tools without metadata use a **safe default** (treated as write/R3 →
|
||||
requires approval). Classification never relies on name-prefix heuristics
|
||||
like ``create_`` / ``delete_``.
|
||||
|
||||
2. **Pre-execution interception (Phase-2)**: write tools are NO LONGER
|
||||
excluded from the seat run — the model sees the full tool schema and can
|
||||
propose writes. A harness-level ``WriteGuardMiddleware`` intercepts each
|
||||
write tool call at ``wrap_tool_call``/``awrap_tool_call`` time (activated
|
||||
per-run by a ``maf_run_id`` flag in the run context) and records a pending
|
||||
action before the real tool ever runs. The AI's proposed call is turned
|
||||
into an ``approval_required`` ToolMessage instead of the tool's real result.
|
||||
|
||||
3. **Post-turn capture**: after the seat turn, the seat executor reads the
|
||||
run's ``tool_calls`` to surface the pending approval in workflow state so
|
||||
the ApprovalGate can pause. Action creation itself happens inside the
|
||||
WriteGuard interceptor (single transaction — see point 5).
|
||||
|
||||
For each intercepted write tool call, the coordinator creates — in a
|
||||
**single logical transaction** (``store.create_pending_action_bundle``):
|
||||
- an ``action`` row with idempotency key ``run_id:agent_id:turn_index:tool_call_id``
|
||||
- the **sanitized** arguments (for audit / API visibility)
|
||||
- the **encrypted** actual arguments (server-only, for restart recovery)
|
||||
- an ``approval`` row (pending)
|
||||
- an ``action.waiting_approval`` critical audit event
|
||||
|
||||
If the critical audit event write fails, the action stays **unexecuted**
|
||||
— the external system is never called.
|
||||
|
||||
4. **Post-approval execution**: after the user approves:
|
||||
- Only an ``approved`` ``action_id`` may re-enter the tool executor.
|
||||
- Before execution, the action is atomically occupied (``approved → running``).
|
||||
- A second entry for the same action returns the existing result or is
|
||||
rejected — **never** a second write.
|
||||
- Success → ``succeeded``, failure → ``failed``, network-unknown →
|
||||
``unknown`` (``unknown`` prohibits auto-retry).
|
||||
|
||||
Encryption: uses ``cryptography.fernet.Fernet`` with a key derived from the
|
||||
``MAF_ACTION_SECRET_KEY`` env var. There is **no default key** — the var is
|
||||
required whenever the MAF feature is enabled (validated at startup). The
|
||||
ciphertext is opaque to the store and is **never** returned from any API,
|
||||
event, log, or frontend query.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import base64
|
||||
import hashlib
|
||||
import logging
|
||||
import os
|
||||
from typing import Any
|
||||
|
||||
from app.maf_roundtable.sanitize import sanitize, sanitize_payload
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# ── Risk classification ───────────────────────────────────────────────────
|
||||
|
||||
# Tools whose side_effect is explicitly "read" or "skill" are never intercepted.
|
||||
# Everything else (including "unknown" / missing metadata) is treated as a
|
||||
# potential write and subject to the write policy.
|
||||
_SAFE_SIDE_EFFECTS = frozenset({"read", "skill"})
|
||||
|
||||
# Default risk level for tools without metadata — safe default requires approval.
|
||||
_DEFAULT_RISK_LEVEL = "R3"
|
||||
_DEFAULT_SIDE_EFFECT = "write"
|
||||
|
||||
|
||||
def classify_tool(
|
||||
tool_name: str,
|
||||
capability_snapshot: dict[str, Any] | None,
|
||||
agent_id: str | None = None,
|
||||
) -> tuple[str, str]:
|
||||
"""Classify a tool's side-effect and risk level from the capability snapshot.
|
||||
|
||||
Returns ``(side_effect, risk_level)``. Tools without explicit metadata
|
||||
use a **safe default**: ``("write", "R3")`` — meaning they are treated as
|
||||
high-risk writes requiring approval. This is intentional: we never guess
|
||||
risk from the tool name.
|
||||
"""
|
||||
if not capability_snapshot:
|
||||
return (_DEFAULT_SIDE_EFFECT, _DEFAULT_RISK_LEVEL)
|
||||
|
||||
tools = capability_snapshot.get("tools")
|
||||
if isinstance(tools, list):
|
||||
for t in tools:
|
||||
if isinstance(t, dict) and t.get("name") == tool_name:
|
||||
side = t.get("side_effect") or _DEFAULT_SIDE_EFFECT
|
||||
risk = t.get("risk_level") or _DEFAULT_RISK_LEVEL
|
||||
return (side, risk)
|
||||
|
||||
agents = capability_snapshot.get("agents")
|
||||
if isinstance(agents, list) and agent_id:
|
||||
for a in agents:
|
||||
if isinstance(a, dict) and a.get("agent_id") == agent_id:
|
||||
agent_tools = a.get("tools")
|
||||
if isinstance(agent_tools, list):
|
||||
for t in agent_tools:
|
||||
if isinstance(t, dict) and t.get("name") == tool_name:
|
||||
side = t.get("side_effect") or _DEFAULT_SIDE_EFFECT
|
||||
risk = t.get("risk_level") or _DEFAULT_RISK_LEVEL
|
||||
return (side, risk)
|
||||
|
||||
return (_DEFAULT_SIDE_EFFECT, _DEFAULT_RISK_LEVEL)
|
||||
|
||||
|
||||
def tool_needs_approval(
|
||||
tool_name: str,
|
||||
write_policy: str,
|
||||
capability_snapshot: dict[str, Any] | None,
|
||||
agent_id: str | None = None,
|
||||
) -> bool:
|
||||
"""Determine whether a tool call needs approval before execution.
|
||||
|
||||
- ``auto``: no approval needed (but the tool is still classified for audit).
|
||||
- ``confirm_high_risk``: approval needed for R3+ tools.
|
||||
- ``confirm_all_writes``: approval needed for any write tool.
|
||||
"""
|
||||
if write_policy == "auto":
|
||||
return False
|
||||
|
||||
side_effect, risk_level = classify_tool(tool_name, capability_snapshot, agent_id)
|
||||
if side_effect in _SAFE_SIDE_EFFECTS:
|
||||
return False
|
||||
|
||||
if write_policy == "confirm_all_writes":
|
||||
return True
|
||||
|
||||
# confirm_high_risk: R3 and above
|
||||
risk_order = {"R0": 0, "R1": 1, "R2": 2, "R3": 3, "R4": 4}
|
||||
risk_val = risk_order.get(risk_level, 3)
|
||||
return risk_val >= 3
|
||||
|
||||
|
||||
# ── Encryption ─────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
class MafActionSecretKeyError(RuntimeError):
|
||||
"""Raised when ``MAF_ACTION_SECRET_KEY`` is missing or empty.
|
||||
|
||||
There is no default key: the env var is required whenever the MAF feature
|
||||
is enabled (validated at startup). Using a baked-in default would let a
|
||||
deployment silently encrypt all action params with a publicly-known key.
|
||||
"""
|
||||
|
||||
|
||||
class ActionSecretUnavailableError(RuntimeError):
|
||||
"""The approved action's parameters cannot be produced — execution MUST fail.
|
||||
|
||||
Raised (instead of returning ``None``) whenever the server-only secret is
|
||||
missing, cannot be decrypted, or does not decrypt to a JSON object. Callers
|
||||
must treat this as a hard execution failure: record the action ``failed``,
|
||||
fail the parent run, and NEVER invoke the tool — they must NOT coerce the
|
||||
failure into empty params (``params or {}``) and execute anyway.
|
||||
|
||||
Carries a machine-readable ``reason`` (``missing`` / ``decrypt_failed`` /
|
||||
``invalid_type``) and a ``detail`` that is always safe to log/persist — it
|
||||
never contains the ciphertext, the key, or raw exception bodies.
|
||||
"""
|
||||
|
||||
def __init__(self, action_id: str, reason: str, detail: str) -> None:
|
||||
self.action_id = action_id
|
||||
self.reason = reason
|
||||
self.detail = detail
|
||||
super().__init__(f"action secret unavailable for {action_id}: {reason} — {detail}")
|
||||
|
||||
|
||||
def _get_fernet_key() -> bytes:
|
||||
"""Derive a Fernet key from the ``MAF_ACTION_SECRET_KEY`` env var.
|
||||
|
||||
Raises ``MafActionSecretKeyError`` if the var is missing or empty — there
|
||||
is deliberately **no default key**. Callers must ensure the var is set
|
||||
before the MAF feature is used (the service validates this at startup).
|
||||
"""
|
||||
raw = os.getenv("MAF_ACTION_SECRET_KEY", "")
|
||||
if not raw or not raw.strip():
|
||||
raise MafActionSecretKeyError(
|
||||
"MAF_ACTION_SECRET_KEY environment variable is not set. "
|
||||
"It is required to encrypt external-write action parameters. "
|
||||
"Set it (e.g. a 32+ char random string) before enabling "
|
||||
"maf_roundtable.enabled."
|
||||
)
|
||||
digest = hashlib.sha256(raw.encode()).digest()
|
||||
return base64.urlsafe_b64encode(digest)
|
||||
|
||||
|
||||
def encrypt_params(params: dict[str, Any]) -> str:
|
||||
"""Encrypt tool-call arguments for server-only storage."""
|
||||
import json
|
||||
|
||||
from cryptography.fernet import Fernet
|
||||
|
||||
plaintext = json.dumps(params, ensure_ascii=False).encode()
|
||||
return Fernet(_get_fernet_key()).encrypt(plaintext).decode()
|
||||
|
||||
|
||||
def decrypt_params(ciphertext: str) -> dict[str, Any]:
|
||||
"""Decrypt tool-call arguments at execution time (server-only)."""
|
||||
import json
|
||||
|
||||
from cryptography.fernet import Fernet
|
||||
|
||||
plaintext = Fernet(_get_fernet_key()).decrypt(ciphertext.encode()).decode()
|
||||
return json.loads(plaintext)
|
||||
|
||||
|
||||
# ── Action Coordinator ────────────────────────────────────────────────────
|
||||
|
||||
|
||||
class ActionCoordinator:
|
||||
"""Manages the intercept-approve-execute lifecycle for external writes.
|
||||
|
||||
Used by the DeerFlowAgentAdapter and WorkflowRunner to:
|
||||
- Determine which tools to exclude before a seat turn.
|
||||
- Capture intercepted write tool calls after a seat turn.
|
||||
- Create actions + approvals + audit events in one logical transaction.
|
||||
- Atomically occupy an approved action for execution (at-most-once).
|
||||
"""
|
||||
|
||||
def __init__(self, service: Any, *, user_id: str = "") -> None:
|
||||
self._service = service
|
||||
self._store = service.store
|
||||
self._user_id = user_id
|
||||
|
||||
# ── Post-turn: capture intercepted write tool calls ──────────────────
|
||||
|
||||
async def intercept_write_tool_calls(
|
||||
self,
|
||||
*,
|
||||
run_id: str,
|
||||
session_id: str,
|
||||
agent_id: str,
|
||||
turn_index: int,
|
||||
tool_calls: list[dict[str, Any]],
|
||||
capability_snapshot: dict[str, Any] | None,
|
||||
write_policy: str,
|
||||
) -> list[dict[str, Any]]:
|
||||
"""Process the AI's tool_calls and create actions+approvals for writes.
|
||||
|
||||
For each tool call that needs approval, create the action + encrypted
|
||||
params + approval + audit event in a **single transaction**
|
||||
(``store.create_pending_action_bundle``). If any step fails, the whole
|
||||
bundle rolls back — the DB never holds a half-finished action.
|
||||
|
||||
Idempotency: ``idempotency_key`` is DB-unique. A concurrent duplicate
|
||||
submission re-reads and returns the already-stored action instead of
|
||||
raising, so a retry never fails the run.
|
||||
|
||||
Returns a list of created (or pre-existing) action dicts.
|
||||
"""
|
||||
created: list[dict[str, Any]] = []
|
||||
|
||||
for tc in tool_calls:
|
||||
tool_name = tc.get("name", "")
|
||||
tool_call_id = tc.get("id", "")
|
||||
raw_args = tc.get("args") or {}
|
||||
|
||||
if not tool_needs_approval(tool_name, write_policy, capability_snapshot, agent_id):
|
||||
continue
|
||||
|
||||
_side_effect, risk_level = classify_tool(tool_name, capability_snapshot, agent_id)
|
||||
idempotency_key = f"{run_id}:{agent_id}:{turn_index}:{tool_call_id or tool_name}"
|
||||
|
||||
# Sanitize args for audit visibility (never expose raw args).
|
||||
sanitized_args = sanitize(raw_args)
|
||||
if not isinstance(sanitized_args, dict):
|
||||
sanitized_args = {"value": str(sanitized_args)}
|
||||
|
||||
# Encrypt actual args for server-only recovery.
|
||||
encrypted_args = encrypt_params(
|
||||
raw_args if isinstance(raw_args, dict) else {"value": str(raw_args)}
|
||||
)
|
||||
|
||||
# Single-transaction bundle: action + secret + approval + event.
|
||||
# The store retries internally (up to 8 attempts) on (run_id, seq)
|
||||
# collisions, re-computing MAX(seq)+1 each time.
|
||||
action = await self._store.create_pending_action_bundle(
|
||||
session_id=session_id,
|
||||
run_id=run_id,
|
||||
agent_id=agent_id,
|
||||
tool_name=tool_name,
|
||||
logical_action_id=tool_call_id or None,
|
||||
idempotency_key=idempotency_key,
|
||||
risk_level=risk_level,
|
||||
target_key=None,
|
||||
turn_index=turn_index,
|
||||
arguments_sanitized=sanitized_args,
|
||||
arguments_encrypted=encrypted_args,
|
||||
approval_summary=f"外部写操作需要审批: {tool_name}(第{turn_index}轮)",
|
||||
approval_payload={
|
||||
"tool_name": tool_name,
|
||||
"risk_level": risk_level,
|
||||
"turn_index": turn_index,
|
||||
"arguments_redacted": sanitized_args,
|
||||
},
|
||||
audit_event_agent_id=agent_id,
|
||||
audit_event_turn_index=turn_index,
|
||||
)
|
||||
|
||||
created.append(action)
|
||||
|
||||
return created
|
||||
|
||||
# ── Post-approval: atomic occupy + execution ─────────────────────────
|
||||
|
||||
async def occupy_for_execution(self, action_id: str) -> str:
|
||||
"""Atomically transition an action from ``approved`` to ``running``.
|
||||
|
||||
Returns the effective claim status (never a blanket bool):
|
||||
``"claimed"`` (won — execute), ``"in_progress"`` (another executor is
|
||||
running it), or a terminal status ``succeeded`` / ``failed`` /
|
||||
``unknown`` / ``rejected`` (already finished elsewhere). Raises
|
||||
``MafActionStateMachineError`` when the action was never properly
|
||||
approved. This guarantees at-most-once execution under concurrent
|
||||
``resume()`` / retries / restart.
|
||||
"""
|
||||
return await self._store.actions.claim_for_execution(action_id)
|
||||
|
||||
async def record_result(
|
||||
self,
|
||||
action_id: str,
|
||||
*,
|
||||
status: str,
|
||||
result: dict[str, Any] | None = None,
|
||||
external_object_id: str | None = None,
|
||||
) -> None:
|
||||
"""Record the outcome of an action execution.
|
||||
|
||||
``status`` must be ``succeeded``, ``failed``, or ``unknown``.
|
||||
``unknown`` prohibits auto-retry — the action stays in ``unknown``
|
||||
until a human reconciles it.
|
||||
|
||||
State-machine constrained: only a ``running`` action may transition
|
||||
to a terminal status. A concurrent caller that lost the race (or a
|
||||
replay after restart) finds the row already terminal and its UPDATE
|
||||
is a no-op — it must NOT overwrite the real result.
|
||||
"""
|
||||
sanitized_result = sanitize_payload(result) if result else None
|
||||
await self._store.actions.record_terminal_result(
|
||||
action_id,
|
||||
status=status,
|
||||
result=sanitized_result,
|
||||
external_object_id=external_object_id,
|
||||
)
|
||||
|
||||
async def get_approved_action_params(self, action_id: str) -> dict[str, Any]:
|
||||
"""Decrypt and return the actual execution parameters for an approved action.
|
||||
|
||||
Server-only: called only by the tool executor at execution time. The
|
||||
decrypted params never reach API, events, logs, or frontend.
|
||||
|
||||
Raises ``ActionSecretUnavailableError`` (never returns ``None``) when
|
||||
the params cannot be produced — missing secret row, undecryptable
|
||||
ciphertext, or a non-object plaintext. The caller MUST treat this as a
|
||||
hard failure (record ``failed``, fail the parent run, never execute the
|
||||
tool); it must NOT fall back to empty params.
|
||||
"""
|
||||
ciphertext = await self._store.action_secrets.get_by_action(action_id)
|
||||
if ciphertext is None:
|
||||
raise ActionSecretUnavailableError(
|
||||
action_id, "missing", "no encrypted action secret is stored for this action"
|
||||
)
|
||||
try:
|
||||
params = decrypt_params(ciphertext)
|
||||
except Exception as exc:
|
||||
# Log a sanitized reason only — never the ciphertext, key, or raw body.
|
||||
logger.error(
|
||||
"Failed to decrypt action params for %s: %s",
|
||||
action_id, sanitize(str(exc)),
|
||||
)
|
||||
raise ActionSecretUnavailableError(
|
||||
action_id, "decrypt_failed", "encrypted action params could not be decrypted"
|
||||
) from exc
|
||||
if not isinstance(params, dict):
|
||||
raise ActionSecretUnavailableError(
|
||||
action_id, "invalid_type", "decrypted action params are not a JSON object"
|
||||
)
|
||||
return params
|
||||
@@ -0,0 +1,168 @@
|
||||
"""Build server-trusted, frozen MAF capability snapshots.
|
||||
|
||||
Clients must not supply tool metadata or full snapshots — only participant
|
||||
``agent_id`` and optional per-seat ``excluded_tools`` (subtractive only).
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from typing import Any
|
||||
|
||||
from deerflow.config.agents_config import load_agent_config
|
||||
from deerflow.config.app_config import AppConfig
|
||||
from deerflow.tools.tool_metadata import resolve_tool_metadata
|
||||
from deerflow.tools.tools import get_available_tools
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class CapabilitySnapshotError(Exception):
|
||||
"""Invalid participant / tool selection when building a trusted snapshot."""
|
||||
|
||||
|
||||
class AgentNotAccessibleError(CapabilitySnapshotError):
|
||||
def __init__(self, agent_id: str) -> None:
|
||||
super().__init__(f"agent not accessible: {agent_id}")
|
||||
self.agent_id = agent_id
|
||||
|
||||
|
||||
class InvalidExcludedToolsError(CapabilitySnapshotError):
|
||||
def __init__(self, agent_id: str, tools: list[str]) -> None:
|
||||
super().__init__(f"invalid excluded_tools for {agent_id}: {tools}")
|
||||
self.agent_id = agent_id
|
||||
self.tools = tools
|
||||
|
||||
|
||||
async def _assert_user_may_use_agent(
|
||||
*,
|
||||
agent_store: Any | None,
|
||||
user_id: str,
|
||||
agent_id: str,
|
||||
) -> None:
|
||||
"""Ensure the user may run this agent (visible in catalog)."""
|
||||
if agent_store is not None:
|
||||
visible = await agent_store.get_visible(agent_id, user_id)
|
||||
if visible is None:
|
||||
raise AgentNotAccessibleError(agent_id)
|
||||
return
|
||||
cfg = load_agent_config(agent_id)
|
||||
if cfg is None:
|
||||
raise AgentNotAccessibleError(agent_id)
|
||||
|
||||
|
||||
def _config_extra_for_tool(app_config: AppConfig, tool_name: str) -> dict[str, Any] | None:
|
||||
for tc in app_config.tools:
|
||||
if tc.name == tool_name:
|
||||
extra = dict(getattr(tc, "model_extra", None) or {})
|
||||
return extra or None
|
||||
return None
|
||||
|
||||
|
||||
def _seat_tools_for_agent(
|
||||
*,
|
||||
app_config: AppConfig,
|
||||
agent_id: str,
|
||||
session_model_name: str | None,
|
||||
session_reasoning_effort: str | None,
|
||||
requested_excluded: list[str],
|
||||
) -> tuple[list[str], list[str], list[dict[str, str]]]:
|
||||
"""Resolve allowed names, effective excluded, and tool metadata for one seat."""
|
||||
agent_config = load_agent_config(agent_id)
|
||||
tool_groups = getattr(agent_config, "tool_groups", None) if agent_config else None
|
||||
model_name = (
|
||||
getattr(agent_config, "model", None) if agent_config else None
|
||||
) or session_model_name
|
||||
|
||||
available = get_available_tools(
|
||||
groups=tool_groups,
|
||||
model_name=model_name,
|
||||
excluded_tools=[],
|
||||
app_config=app_config,
|
||||
)
|
||||
allowed_set = {t.name for t in available}
|
||||
excluded_set = set(requested_excluded or [])
|
||||
unknown_excluded = excluded_set - allowed_set
|
||||
if unknown_excluded:
|
||||
raise InvalidExcludedToolsError(agent_id, sorted(unknown_excluded))
|
||||
effective_excluded = sorted(excluded_set & allowed_set)
|
||||
effective_allowed = sorted(allowed_set - set(effective_excluded))
|
||||
|
||||
tools_meta: list[dict[str, str]] = []
|
||||
for name in effective_allowed:
|
||||
extra = _config_extra_for_tool(app_config, name)
|
||||
tools_meta.append(resolve_tool_metadata(name, config_extra=extra))
|
||||
|
||||
return effective_allowed, effective_excluded, tools_meta
|
||||
|
||||
|
||||
async def build_trusted_capability_snapshot(
|
||||
*,
|
||||
user_id: str,
|
||||
participants: list[dict[str, Any]],
|
||||
app_config: AppConfig,
|
||||
agent_store: Any | None = None,
|
||||
session_model_name: str | None = None,
|
||||
session_reasoning_effort: str | None = None,
|
||||
session_excluded_tools: list[str] | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Build the frozen snapshot stored on the session and used by WriteGuard."""
|
||||
agents_out: list[dict[str, Any]] = []
|
||||
flat_tools: dict[str, dict[str, str]] = {}
|
||||
|
||||
for p in participants:
|
||||
agent_id = str(p.get("agent_id") or "")
|
||||
if not agent_id:
|
||||
continue
|
||||
await _assert_user_may_use_agent(
|
||||
agent_store=agent_store, user_id=user_id, agent_id=agent_id
|
||||
)
|
||||
agent_config = load_agent_config(agent_id)
|
||||
seat_excluded = list(p.get("excluded_tools") or [])
|
||||
if session_excluded_tools:
|
||||
seat_excluded = sorted(set(seat_excluded) | set(session_excluded_tools))
|
||||
|
||||
allowed, excluded, tools_meta = _seat_tools_for_agent(
|
||||
app_config=app_config,
|
||||
agent_id=agent_id,
|
||||
session_model_name=session_model_name,
|
||||
session_reasoning_effort=session_reasoning_effort,
|
||||
requested_excluded=seat_excluded,
|
||||
)
|
||||
for meta in tools_meta:
|
||||
flat_tools[meta["tool_name"]] = meta
|
||||
|
||||
agents_out.append(
|
||||
{
|
||||
"agent_id": agent_id,
|
||||
"role": p.get("role", "seat"),
|
||||
"model_name": getattr(agent_config, "model", None) if agent_config else session_model_name,
|
||||
"reasoning_effort": session_reasoning_effort,
|
||||
"thinking_enabled": True,
|
||||
"subagent_enabled": bool(getattr(agent_config, "subagent_enabled", False))
|
||||
if agent_config
|
||||
else False,
|
||||
"tool_groups": list(getattr(agent_config, "tool_groups", None) or [])
|
||||
if agent_config
|
||||
else None,
|
||||
"allowed_tool_names": allowed,
|
||||
"excluded_tools": excluded,
|
||||
"tools": tools_meta,
|
||||
"memory_recall_disabled": None,
|
||||
"memory_injection_enabled": None,
|
||||
}
|
||||
)
|
||||
|
||||
return {
|
||||
"version": 1,
|
||||
"agents": agents_out,
|
||||
"tools": list(flat_tools.values()),
|
||||
}
|
||||
|
||||
|
||||
def seat_snapshot_for_agent(full_snapshot: dict[str, Any], agent_id: str) -> dict[str, Any]:
|
||||
"""Per-participant slice persisted on ``maf_roundtable_participants``."""
|
||||
for a in full_snapshot.get("agents") or []:
|
||||
if isinstance(a, dict) and a.get("agent_id") == agent_id:
|
||||
return dict(a)
|
||||
return {}
|
||||
@@ -0,0 +1,160 @@
|
||||
"""Build bounded, traceable seat input from MAF roundtable context.
|
||||
|
||||
Converts the shared roundtable state (task, previous turns, fact ledger,
|
||||
stage instructions) into a single human message for a seat's DeerFlow thread.
|
||||
|
||||
Design constraints (MAF-02-06):
|
||||
- Bounded: total output STRICTLY never exceeds ``max_context_chars``.
|
||||
- Trimmable: each section is independently truncatable.
|
||||
- Traceable: includes turn references so the seat can cite prior work.
|
||||
- Never injects credentials, tokens, or raw binary content.
|
||||
- All content is sanitized before inclusion.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
from app.maf_roundtable.sanitize import sanitize
|
||||
|
||||
_DEFAULT_MAX_CONTEXT_CHARS = 12000
|
||||
_DEFAULT_MAX_TURN_CHARS = 2000
|
||||
_DEFAULT_MAX_FACT_CHARS = 3000
|
||||
|
||||
|
||||
def build_seat_input(
|
||||
*,
|
||||
task_text: str,
|
||||
stage_instruction: str,
|
||||
role_description: str,
|
||||
prior_turns: list[dict[str, Any]],
|
||||
fact_ledger: dict[str, Any] | None = None,
|
||||
max_context_chars: int = _DEFAULT_MAX_CONTEXT_CHARS,
|
||||
max_turn_chars: int = _DEFAULT_MAX_TURN_CHARS,
|
||||
max_fact_chars: int = _DEFAULT_MAX_FACT_CHARS,
|
||||
) -> str:
|
||||
"""Assemble the human message for a seat's DeerFlow run.
|
||||
|
||||
The total output length is STRICTLY <= max_context_chars. Truncation
|
||||
happens per-section first, then a final hard cap ensures no overflow.
|
||||
"""
|
||||
sections: list[str] = []
|
||||
|
||||
sections.append(f"【任务】\n{task_text}")
|
||||
|
||||
if role_description:
|
||||
sections.append(f"【你的角色】\n{role_description}")
|
||||
|
||||
if stage_instruction:
|
||||
sections.append(f"【本阶段要求】\n{stage_instruction}")
|
||||
|
||||
if prior_turns:
|
||||
turns_text = _format_prior_turns(prior_turns, max_turn_chars)
|
||||
if turns_text:
|
||||
sections.append(f"【已有讨论】\n{turns_text}")
|
||||
|
||||
if fact_ledger:
|
||||
sanitized_ledger = sanitize(fact_ledger)
|
||||
if isinstance(sanitized_ledger, dict):
|
||||
facts_text = _format_fact_ledger(sanitized_ledger, max_fact_chars)
|
||||
if facts_text:
|
||||
sections.append(f"【共享事实账本】\n{facts_text}")
|
||||
|
||||
result = "\n\n".join(sections)
|
||||
|
||||
if len(result) > max_context_chars:
|
||||
result = result[:max_context_chars]
|
||||
|
||||
return result
|
||||
|
||||
|
||||
def build_manager_synthesis_input(
|
||||
*,
|
||||
task_text: str,
|
||||
seat_results: list[dict[str, Any]],
|
||||
fact_ledger: dict[str, Any] | None = None,
|
||||
max_context_chars: int = _DEFAULT_MAX_CONTEXT_CHARS,
|
||||
) -> str:
|
||||
"""Build the manager's final synthesis prompt."""
|
||||
sections: list[str] = []
|
||||
sections.append(f"【原始任务】\n{task_text}")
|
||||
sections.append("【各席位分析结果】")
|
||||
|
||||
for r in seat_results:
|
||||
agent_id = r.get("agent_id", "unknown")
|
||||
content = str(r.get("content", ""))
|
||||
if len(content) > 3000:
|
||||
content = content[:3000] + "..."
|
||||
sections.append(f"--- {agent_id} ---\n{content}")
|
||||
|
||||
if fact_ledger:
|
||||
sanitized_ledger = sanitize(fact_ledger)
|
||||
if isinstance(sanitized_ledger, dict):
|
||||
facts_text = _format_fact_ledger(sanitized_ledger, _DEFAULT_MAX_FACT_CHARS)
|
||||
if facts_text:
|
||||
sections.append(f"【共享事实账本】\n{facts_text}")
|
||||
|
||||
sections.append(
|
||||
"【综合要求】\n"
|
||||
"请基于以上各席位分析和事实账本,生成最终结论。要求:\n"
|
||||
"1. 明确标注共识点和分歧点\n"
|
||||
"2. 区分「建议动作」和「已实际执行的动作」\n"
|
||||
"3. 引用具体证据来源\n"
|
||||
"4. 列出失败或状态不确定的动作"
|
||||
)
|
||||
|
||||
result = "\n\n".join(sections)
|
||||
if len(result) > max_context_chars:
|
||||
result = result[:max_context_chars]
|
||||
return result
|
||||
|
||||
|
||||
# ── internal helpers ──────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def _format_prior_turns(turns: list[dict[str, Any]], max_per_turn: int) -> str:
|
||||
lines: list[str] = []
|
||||
for t in turns:
|
||||
agent_id = t.get("agent_id", "unknown")
|
||||
turn_idx = t.get("turn_index", "?")
|
||||
summary = str(t.get("summary", ""))
|
||||
if len(summary) > max_per_turn:
|
||||
summary = summary[:max_per_turn] + "..."
|
||||
lines.append(f"[轮次{turn_idx}] {agent_id}: {summary}")
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def _format_fact_ledger(ledger: dict[str, Any], max_chars: int) -> str:
|
||||
parts: list[str] = []
|
||||
|
||||
facts = ledger.get("confirmed_facts")
|
||||
if facts and isinstance(facts, list):
|
||||
parts.append("已确认事实:")
|
||||
for f in facts[:20]:
|
||||
parts.append(f" - {f}")
|
||||
|
||||
tool_results = ledger.get("tool_results")
|
||||
if tool_results and isinstance(tool_results, list):
|
||||
parts.append("工具执行结果:")
|
||||
for tr in tool_results[:10]:
|
||||
if isinstance(tr, dict):
|
||||
parts.append(f" - {tr.get('tool_name', '?')}: {tr.get('status', '?')}")
|
||||
else:
|
||||
parts.append(f" - {tr}")
|
||||
|
||||
conflicts = ledger.get("conflicts")
|
||||
if conflicts and isinstance(conflicts, list):
|
||||
parts.append("未解决冲突:")
|
||||
for c in conflicts[:5]:
|
||||
parts.append(f" - {c}")
|
||||
|
||||
pending = ledger.get("pending_actions")
|
||||
if pending and isinstance(pending, list):
|
||||
parts.append("等待确认动作:")
|
||||
for p in pending[:5]:
|
||||
parts.append(f" - {p}")
|
||||
|
||||
result = "\n".join(parts)
|
||||
if len(result) > max_chars:
|
||||
result = result[:max_chars]
|
||||
return result
|
||||
@@ -0,0 +1,513 @@
|
||||
"""DeerFlow Agent Adapter for the MAF roundtable experiment (Phase 2).
|
||||
|
||||
Drives each MAF seat's actual execution through the existing DeerFlow Agent
|
||||
Runtime, preserving tools / skills / MCP / sandbox / identity / middleware
|
||||
semantics. The adapter does NOT wrap individual LangChain tools — it invokes
|
||||
a full agent run per seat turn via ``DeerFlowRuntimeClient``.
|
||||
|
||||
Architecture:
|
||||
- One DeerFlow thread per seat (bound at session start, reused across turns).
|
||||
- In-process ``start_run`` via DeerFlowRuntimeClient (no fake Request).
|
||||
- User context injected via ExecutionPrincipal (server-generated, never from body).
|
||||
- StreamBridge subscription translates runtime SSE → MAF events in real time.
|
||||
- Cancellation propagates from MAF run → DeerFlow run via RunManager.cancel.
|
||||
- All seat runs persisted to ``maf_roundtable_seat_runs`` (survives restart).
|
||||
- Critical audit events (tool.*, skill.*, approval.*, artifact.*) MUST persist;
|
||||
failure stops external writes and marks the run as failed.
|
||||
|
||||
Boundary: lives in ``app.maf_roundtable`` (may import ``deerflow.*`` and
|
||||
``app.gateway.*``); never imported by ``deerflow.*``.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import logging
|
||||
import os
|
||||
import time
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any
|
||||
|
||||
from app.maf_roundtable.context_builder import build_seat_input
|
||||
from app.maf_roundtable.event_normalizer import (
|
||||
make_run_cancelled,
|
||||
make_run_failed,
|
||||
make_turn_completed,
|
||||
make_turn_started,
|
||||
normalize_stream_event,
|
||||
)
|
||||
from app.maf_roundtable.runtime_client import DeerFlowRuntimeClient, ExecutionPrincipal
|
||||
from app.maf_roundtable.sanitize import sanitize
|
||||
from deerflow.runtime.stream_bridge.base import END_SENTINEL, HEARTBEAT_SENTINEL
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
_IDLE_TIMEOUT_S = int(os.getenv("MAF_SEAT_IDLE_TIMEOUT_SECONDS", "1200") or "1200")
|
||||
_IDLE_CHECK_INTERVAL_S = 10.0
|
||||
_MAX_CONTEXT_CHARS = int(os.getenv("MAF_MAX_CONTEXT_CHARS", "12000") or "12000")
|
||||
|
||||
_CRITICAL_EVENT_TYPES = frozenset({
|
||||
"tool.requested", "tool.started", "tool.completed", "tool.failed",
|
||||
"skill.selected", "skill.started", "skill.completed", "skill.failed",
|
||||
"artifact.created",
|
||||
"action.waiting_approval", "action.approved", "action.rejected",
|
||||
"run.completed", "run.failed", "run.cancelled",
|
||||
})
|
||||
|
||||
|
||||
class AuditEventError(RuntimeError):
|
||||
"""Raised when a critical audit event fails to persist."""
|
||||
|
||||
|
||||
@dataclass
|
||||
class SeatResponse:
|
||||
"""Standardized response from a seat turn (MAF-02-08)."""
|
||||
|
||||
agent_id: str
|
||||
turn_index: int
|
||||
content: str
|
||||
tool_calls: list[dict[str, Any]] = field(default_factory=list)
|
||||
usage: dict[str, Any] | None = None
|
||||
metadata: dict[str, Any] | None = None
|
||||
error: str | None = None
|
||||
latency_ms: int | None = None
|
||||
|
||||
|
||||
class DeerFlowAgentAdapter:
|
||||
"""Drives MAF seat execution through the DeerFlow Agent Runtime.
|
||||
|
||||
Usage::
|
||||
|
||||
client = DeerFlowRuntimeClient(app)
|
||||
adapter = DeerFlowAgentAdapter(client, service=svc, user_id="u1")
|
||||
await adapter.ensure_threads(session_id, participants)
|
||||
response = await adapter.run_seat_turn(...)
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
runtime_client: DeerFlowRuntimeClient,
|
||||
*,
|
||||
service: Any,
|
||||
user_id: str,
|
||||
) -> None:
|
||||
self._client = runtime_client
|
||||
self._service = service
|
||||
self._user_id = user_id
|
||||
self._seen_source_ids: set[str] = set()
|
||||
|
||||
# ── MAF-02-01: thread lifecycle ─────────────────────────────────────────
|
||||
|
||||
async def ensure_threads(
|
||||
self, session_id: str, run_id: str, participants: list[dict[str, Any]]
|
||||
) -> dict[str, str]:
|
||||
"""Create and bind a DeerFlow thread for each participant that lacks one.
|
||||
|
||||
Thread creation is wrapped in set_current_user so thread_meta.user_id
|
||||
matches the MAF session owner. Returns ``{agent_id: thread_id}``.
|
||||
"""
|
||||
principal = ExecutionPrincipal(user_id=self._user_id, session_id=session_id, run_id=run_id)
|
||||
thread_map: dict[str, str] = {}
|
||||
for p in participants:
|
||||
agent_id = p.get("agent_id", "")
|
||||
existing = p.get("thread_id")
|
||||
if existing:
|
||||
thread_map[agent_id] = existing
|
||||
continue
|
||||
thread_id = await self._client.create_thread(principal)
|
||||
await self._service.store.participants.bind_thread(
|
||||
session_id, agent_id, thread_id=thread_id
|
||||
)
|
||||
thread_map[agent_id] = thread_id
|
||||
return thread_map
|
||||
|
||||
# ── MAF-02-02/03/04/05: seat turn execution ─────────────────────────────
|
||||
|
||||
async def run_seat_turn(
|
||||
self,
|
||||
*,
|
||||
session_id: str,
|
||||
run_id: str,
|
||||
agent_id: str,
|
||||
turn_index: int,
|
||||
message: str,
|
||||
thread_id: str,
|
||||
model_name: str | None = None,
|
||||
reasoning_effort: str | None = None,
|
||||
thinking_enabled: bool = True,
|
||||
subagent_enabled: bool = False,
|
||||
excluded_tools: list[str] | None = None,
|
||||
stage_instruction: str = "",
|
||||
prior_turns: list[dict[str, Any]] | None = None,
|
||||
fact_ledger: dict[str, Any] | None = None,
|
||||
role_description: str = "",
|
||||
task_text: str = "",
|
||||
memory_recall_disabled: bool | None = None,
|
||||
memory_injection_enabled: bool | None = None,
|
||||
capability_snapshot: dict[str, Any] | None = None,
|
||||
write_policy: str = "confirm_high_risk",
|
||||
approved_tool: str | None = None,
|
||||
) -> SeatResponse:
|
||||
"""Execute one seat turn through the DeerFlow Agent Runtime."""
|
||||
t0 = time.perf_counter()
|
||||
|
||||
seat_message = build_seat_input(
|
||||
task_text=task_text or message,
|
||||
stage_instruction=stage_instruction,
|
||||
role_description=role_description,
|
||||
prior_turns=prior_turns or [],
|
||||
fact_ledger=fact_ledger,
|
||||
max_context_chars=_MAX_CONTEXT_CHARS,
|
||||
)
|
||||
if not task_text:
|
||||
seat_message = message
|
||||
|
||||
await self._emit_critical(run_id, make_turn_started(agent_id, turn_index, {"thread_id": thread_id}))
|
||||
|
||||
principal = ExecutionPrincipal(user_id=self._user_id, session_id=session_id, run_id=run_id)
|
||||
|
||||
seat_run = await self._service.store.seat_runs.create_seat_run(
|
||||
maf_run_id=run_id, agent_id=agent_id, turn_index=turn_index, deerflow_thread_id=thread_id
|
||||
)
|
||||
seat_run_id = seat_run["id"]
|
||||
|
||||
try:
|
||||
response = await self._execute_run(
|
||||
principal=principal,
|
||||
seat_run_id=seat_run_id,
|
||||
run_id=run_id,
|
||||
agent_id=agent_id,
|
||||
turn_index=turn_index,
|
||||
thread_id=thread_id,
|
||||
message=seat_message,
|
||||
model_name=model_name,
|
||||
reasoning_effort=reasoning_effort,
|
||||
thinking_enabled=thinking_enabled,
|
||||
subagent_enabled=subagent_enabled,
|
||||
excluded_tools=excluded_tools or [],
|
||||
memory_recall_disabled=memory_recall_disabled,
|
||||
memory_injection_enabled=memory_injection_enabled,
|
||||
capability_snapshot=capability_snapshot,
|
||||
write_policy=write_policy,
|
||||
approved_tool=approved_tool,
|
||||
)
|
||||
except asyncio.CancelledError:
|
||||
await self._service.store.seat_runs.mark_cancelled(seat_run_id)
|
||||
await self._emit_critical(run_id, make_run_cancelled(agent_id, turn_index))
|
||||
raise
|
||||
except Exception as exc:
|
||||
latency = int((time.perf_counter() - t0) * 1000)
|
||||
# Sanitize before persisting / emitting — the raw exception body may
|
||||
# embed params or credentials; only the redacted text is stored.
|
||||
safe_error = str(sanitize(str(exc)))[:500]
|
||||
await self._service.store.seat_runs.mark_failed(seat_run_id, error=safe_error)
|
||||
await self._emit_critical(run_id, make_run_failed(agent_id, turn_index, error_code=type(exc).__name__, message=safe_error))
|
||||
return SeatResponse(
|
||||
agent_id=agent_id,
|
||||
turn_index=turn_index,
|
||||
content="",
|
||||
error=safe_error,
|
||||
latency_ms=latency,
|
||||
)
|
||||
|
||||
await self._service.store.seat_runs.mark_completed(seat_run_id)
|
||||
response.latency_ms = int((time.perf_counter() - t0) * 1000)
|
||||
await self._emit_critical(run_id, make_turn_completed(
|
||||
agent_id, turn_index,
|
||||
content=response.content,
|
||||
usage=response.usage,
|
||||
metadata=response.metadata,
|
||||
))
|
||||
return response
|
||||
|
||||
async def _execute_run(
|
||||
self,
|
||||
*,
|
||||
principal: ExecutionPrincipal,
|
||||
seat_run_id: str,
|
||||
run_id: str,
|
||||
agent_id: str,
|
||||
turn_index: int,
|
||||
thread_id: str,
|
||||
message: str,
|
||||
model_name: str | None,
|
||||
reasoning_effort: str | None,
|
||||
thinking_enabled: bool,
|
||||
subagent_enabled: bool,
|
||||
excluded_tools: list[str],
|
||||
memory_recall_disabled: bool | None,
|
||||
memory_injection_enabled: bool | None,
|
||||
capability_snapshot: dict[str, Any] | None = None,
|
||||
write_policy: str = "confirm_high_risk",
|
||||
approved_tool: str | None = None,
|
||||
) -> SeatResponse:
|
||||
record = await self._client.start_agent_run(
|
||||
principal,
|
||||
thread_id=thread_id,
|
||||
agent_id=agent_id,
|
||||
message=message,
|
||||
model_name=model_name,
|
||||
reasoning_effort=reasoning_effort,
|
||||
thinking_enabled=thinking_enabled,
|
||||
subagent_enabled=subagent_enabled,
|
||||
excluded_tools=excluded_tools,
|
||||
memory_recall_disabled=memory_recall_disabled,
|
||||
memory_injection_enabled=memory_injection_enabled,
|
||||
turn_index=turn_index,
|
||||
capability_snapshot=capability_snapshot,
|
||||
write_policy=write_policy,
|
||||
approved_tool=approved_tool,
|
||||
)
|
||||
|
||||
deerflow_run_id = getattr(record, "run_id", None)
|
||||
if deerflow_run_id:
|
||||
await self._service.store.seat_runs.mark_running(seat_run_id, deerflow_run_id=deerflow_run_id)
|
||||
|
||||
await self._await_with_event_translation(
|
||||
record, deerflow_run_id, run_id=run_id, agent_id=agent_id, turn_index=turn_index
|
||||
)
|
||||
|
||||
messages = await self._client.read_thread_messages(principal, thread_id)
|
||||
content = self._latest_ai_text(messages)
|
||||
tool_calls = self._tool_calls_since_last_human(messages)
|
||||
usage = self._extract_usage(messages)
|
||||
|
||||
return SeatResponse(
|
||||
agent_id=agent_id,
|
||||
turn_index=turn_index,
|
||||
content=content,
|
||||
tool_calls=tool_calls,
|
||||
usage=usage,
|
||||
metadata={"thread_id": thread_id, "deerflow_run_id": deerflow_run_id},
|
||||
)
|
||||
|
||||
# ── MAF-02-07: real-time event translation ──────────────────────────────
|
||||
|
||||
async def _await_with_event_translation(
|
||||
self,
|
||||
record: Any,
|
||||
deerflow_run_id: str | None,
|
||||
*,
|
||||
run_id: str,
|
||||
agent_id: str,
|
||||
turn_index: int,
|
||||
) -> None:
|
||||
"""Await the DeerFlow run while translating StreamBridge events to MAF events.
|
||||
|
||||
P1.5 fix: ``if task in done: await task`` so exceptions propagate.
|
||||
"""
|
||||
task = getattr(record, "task", None)
|
||||
if task is None:
|
||||
return
|
||||
|
||||
bridge = getattr(self._client.app.state, "stream_bridge", None)
|
||||
if bridge is None or deerflow_run_id is None:
|
||||
await task
|
||||
return
|
||||
|
||||
loop = asyncio.get_running_loop()
|
||||
last_activity = loop.time()
|
||||
stuck = asyncio.Event()
|
||||
|
||||
async def _watch() -> None:
|
||||
nonlocal last_activity
|
||||
async for ev in bridge.subscribe(deerflow_run_id, heartbeat_interval=_IDLE_CHECK_INTERVAL_S):
|
||||
if ev is END_SENTINEL:
|
||||
return
|
||||
now = loop.time()
|
||||
if ev is HEARTBEAT_SENTINEL:
|
||||
if now - last_activity >= _IDLE_TIMEOUT_S:
|
||||
stuck.set()
|
||||
return
|
||||
else:
|
||||
last_activity = now
|
||||
maf_events = normalize_stream_event(
|
||||
ev.event, ev.data, agent_id=agent_id, turn_index=turn_index
|
||||
)
|
||||
for me in maf_events:
|
||||
await self._emit(run_id, me)
|
||||
|
||||
watch = asyncio.create_task(_watch())
|
||||
try:
|
||||
done, _ = await asyncio.wait({task, watch}, return_when=asyncio.FIRST_COMPLETED)
|
||||
if task in done:
|
||||
await task
|
||||
return
|
||||
if not stuck.is_set():
|
||||
await task
|
||||
return
|
||||
idle_elapsed = loop.time() - last_activity
|
||||
logger.error(
|
||||
"MAF seat '%s' stalled: no output for %.0fs on run %s",
|
||||
agent_id, idle_elapsed, deerflow_run_id,
|
||||
)
|
||||
await self._client.cancel_run(deerflow_run_id)
|
||||
try:
|
||||
await asyncio.wait_for(asyncio.shield(task), timeout=10.0)
|
||||
except (TimeoutError, asyncio.CancelledError, Exception):
|
||||
logger.warning("DeerFlow task did not finish after cancel for run %s", deerflow_run_id)
|
||||
raise RuntimeError(f"MAF seat '{agent_id}' stalled (no output for {_IDLE_TIMEOUT_S}s)")
|
||||
finally:
|
||||
if not watch.done():
|
||||
watch.cancel()
|
||||
try:
|
||||
await watch
|
||||
except BaseException:
|
||||
pass
|
||||
|
||||
# ── MAF-02-09: cancellation ─────────────────────────────────────────────
|
||||
|
||||
async def cancel(self, maf_run_id: str) -> dict[str, Any]:
|
||||
"""Cancel all active DeerFlow runs for a MAF run (two-phase cascade).
|
||||
|
||||
Phase 1: mark all active seat runs as ``cancelling``.
|
||||
Phase 2: actually cancel each DeerFlow run, then mark the seat run
|
||||
as ``cancelled`` (success) or ``cancel_failed`` (failure).
|
||||
|
||||
Returns a structured result so the caller (dispatcher → router) can
|
||||
decide whether to finalize the parent run as ``cancelled`` or leave it
|
||||
in a non-terminal ``cancelling`` / ``cancel_failed`` state. A failed
|
||||
cancel must NEVER masquerade as cancelled.
|
||||
|
||||
Result shape::
|
||||
|
||||
{
|
||||
"all_cancelled": bool,
|
||||
"cancelled_run_ids": [...], # seat_run_ids that succeeded
|
||||
"failed_run_ids": [...], # seat_run_ids where cancel failed
|
||||
"still_active_run_ids": [...], # seat_run_ids with no deerflow id
|
||||
}
|
||||
"""
|
||||
seat_infos = await self._service.store.seat_runs.cancel_all_active(maf_run_id)
|
||||
cancelled_run_ids: list[str] = []
|
||||
failed_run_ids: list[str] = []
|
||||
still_active_run_ids: list[str] = []
|
||||
for info in seat_infos:
|
||||
seat_run_id = info["seat_run_id"]
|
||||
deerflow_run_id = info.get("deerflow_run_id")
|
||||
if not deerflow_run_id:
|
||||
# No DeerFlow run to cancel — record as still-active/unknown.
|
||||
await self._service.store.seat_runs.mark_cancel_unknown(
|
||||
seat_run_id, error="no deerflow_run_id recorded"
|
||||
)
|
||||
still_active_run_ids.append(seat_run_id)
|
||||
continue
|
||||
if await self._client.cancel_run(deerflow_run_id):
|
||||
await self._service.store.seat_runs.mark_cancelled(seat_run_id)
|
||||
cancelled_run_ids.append(seat_run_id)
|
||||
else:
|
||||
await self._service.store.seat_runs.mark_cancel_failed(
|
||||
seat_run_id, error="DeerFlow cancel_run returned False"
|
||||
)
|
||||
failed_run_ids.append(seat_run_id)
|
||||
all_cancelled = not failed_run_ids and not still_active_run_ids and bool(seat_infos)
|
||||
# If there were no active seat runs at all, treat as fully cancelled
|
||||
# (nothing left to cancel).
|
||||
if not seat_infos:
|
||||
all_cancelled = True
|
||||
return {
|
||||
"all_cancelled": all_cancelled,
|
||||
"cancelled_run_ids": cancelled_run_ids,
|
||||
"failed_run_ids": failed_run_ids,
|
||||
"still_active_run_ids": still_active_run_ids,
|
||||
}
|
||||
|
||||
# ── P1.6: audit event persistence ───────────────────────────────────────
|
||||
|
||||
async def _emit_critical(self, run_id: str, event: dict[str, Any]) -> None:
|
||||
"""Emit a critical audit event. Failure raises AuditEventError."""
|
||||
try:
|
||||
await self._service.append_event(
|
||||
run_id=run_id,
|
||||
user_id=self._user_id,
|
||||
event_type=event["event_type"],
|
||||
agent_id=event.get("agent_id"),
|
||||
turn_index=event.get("turn_index"),
|
||||
payload=event.get("payload"),
|
||||
)
|
||||
except Exception as exc:
|
||||
logger.error("CRITICAL audit event %s failed to persist for run %s", event.get("event_type"), run_id, exc_info=True)
|
||||
raise AuditEventError(
|
||||
f"Critical audit event '{event.get('event_type')}' failed to persist: {exc}"
|
||||
) from exc
|
||||
|
||||
async def _emit(self, run_id: str, event: dict[str, Any]) -> None:
|
||||
"""Emit a non-critical event (agent.message.delta). Failure degrades gracefully.
|
||||
|
||||
Dedup: events with a source_event_id are deduped at the DB level via
|
||||
the (run_id, source_event_id) unique constraint — durable across restarts.
|
||||
The in-memory _seen_source_ids set is a fast-path cache only.
|
||||
"""
|
||||
source_id = event.get("source_event_id")
|
||||
if source_id:
|
||||
if source_id in self._seen_source_ids:
|
||||
return
|
||||
self._seen_source_ids.add(source_id)
|
||||
|
||||
event_type = event.get("event_type", "")
|
||||
if event_type in _CRITICAL_EVENT_TYPES:
|
||||
await self._emit_critical(run_id, event)
|
||||
return
|
||||
try:
|
||||
await self._service.append_event(
|
||||
run_id=run_id,
|
||||
user_id=self._user_id,
|
||||
event_type=event_type,
|
||||
agent_id=event.get("agent_id"),
|
||||
turn_index=event.get("turn_index"),
|
||||
payload=event.get("payload"),
|
||||
source_event_id=source_id,
|
||||
)
|
||||
except Exception:
|
||||
logger.warning("non-critical event %s failed for run %s (degraded)", event_type, run_id, exc_info=True)
|
||||
|
||||
# ── internal helpers ────────────────────────────────────────────────────
|
||||
|
||||
def _latest_ai_text(self, messages: list[dict[str, Any]]) -> str:
|
||||
for m in reversed(messages):
|
||||
if not isinstance(m, dict):
|
||||
continue
|
||||
if (m.get("type") or m.get("role")) not in {"ai", "assistant"}:
|
||||
continue
|
||||
text = self._message_text(m)
|
||||
if text.strip():
|
||||
return text
|
||||
return ""
|
||||
|
||||
def _message_text(self, message: dict[str, Any]) -> str:
|
||||
content = message.get("content")
|
||||
if isinstance(content, str):
|
||||
return content
|
||||
if isinstance(content, list):
|
||||
parts = [p.get("text", "") for p in content if isinstance(p, dict) and p.get("type") == "text"]
|
||||
return "\n".join(parts)
|
||||
return ""
|
||||
|
||||
def _tool_calls_since_last_human(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
|
||||
last_human = -1
|
||||
for i, m in enumerate(messages):
|
||||
if isinstance(m, dict) and (m.get("type") or m.get("role")) in {"human", "user"}:
|
||||
last_human = i
|
||||
out: list[dict[str, Any]] = []
|
||||
for m in messages[last_human + 1:]:
|
||||
if not isinstance(m, dict):
|
||||
continue
|
||||
if (m.get("type") or m.get("role")) not in {"ai", "assistant"}:
|
||||
continue
|
||||
for tc in m.get("tool_calls") or []:
|
||||
if not isinstance(tc, dict):
|
||||
continue
|
||||
name = tc.get("name") or ""
|
||||
if not name:
|
||||
continue
|
||||
out.append({"name": name, "args": tc.get("args") or {}, "id": tc.get("id") or ""})
|
||||
return out
|
||||
|
||||
def _extract_usage(self, messages: list[dict[str, Any]]) -> dict[str, Any] | None:
|
||||
for m in reversed(messages):
|
||||
if not isinstance(m, dict):
|
||||
continue
|
||||
usage = m.get("usage_metadata") or m.get("usage")
|
||||
if isinstance(usage, dict) and usage:
|
||||
return usage
|
||||
return None
|
||||
@@ -0,0 +1,171 @@
|
||||
"""MAF run dispatcher — launches WorkflowRunner after create_run succeeds.
|
||||
|
||||
The dispatcher is the bridge between the HTTP layer (router) and the workflow
|
||||
execution layer (WorkflowRunner). It:
|
||||
|
||||
1. Checks MAF SDK availability BEFORE creating the run (so the user gets a
|
||||
clean 503 rather than a run that will fail).
|
||||
2. Launches ``WorkflowRunner.execute`` as a background asyncio task.
|
||||
3. Tracks task handles for cancellation.
|
||||
4. **Resume**: after an approval decision, the router calls
|
||||
``dispatcher.resume(run_id, user_id)`` to restore the workflow from its
|
||||
checkpoint.
|
||||
5. **Cancel cascade**: ``dispatcher.cancel(run_id)`` cancels both the
|
||||
background task AND the DeerFlow sub-runs. If the task handle is gone
|
||||
(process restart), it rebuilds a runner from persisted ``seat_runs`` and
|
||||
cascades cancel to DeerFlow.
|
||||
6. Never silently degrades to sequential DeerFlow execution — if the SDK is
|
||||
missing or the workflow fails, the run is marked ``failed``.
|
||||
|
||||
Usage (from the router)::
|
||||
|
||||
from app.maf_roundtable.dispatcher import get_dispatcher
|
||||
dispatcher = get_dispatcher(request.app)
|
||||
await dispatcher.dispatch(session, run, user_id=user_id)
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import logging
|
||||
from typing import Any
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class MafSdkNotAvailableError(RuntimeError):
|
||||
"""Raised when the MAF SDK is not installed and a run is requested."""
|
||||
|
||||
|
||||
class MafRunDispatcher:
|
||||
"""Manages background MAF workflow execution tasks."""
|
||||
|
||||
def __init__(self, app: Any) -> None:
|
||||
self._app = app
|
||||
self._tasks: dict[str, asyncio.Task] = {}
|
||||
|
||||
def check_sdk_available(self) -> None:
|
||||
"""Raise MafSdkNotAvailableError if the MAF SDK is not installed."""
|
||||
try:
|
||||
import agent_framework # noqa: F401
|
||||
except ImportError as exc:
|
||||
raise MafSdkNotAvailableError(
|
||||
"agent_framework SDK is not installed; run 'uv sync --extra maf' to enable MAF workflows"
|
||||
) from exc
|
||||
|
||||
async def dispatch(self, session: dict[str, Any], run: dict[str, Any], *, user_id: str) -> None:
|
||||
"""Launch the workflow for a newly created run as a background task.
|
||||
|
||||
The task is tracked so it can be cancelled via ``cancel(run_id)``.
|
||||
"""
|
||||
from app.maf_roundtable.workflow_runner import WorkflowRunner
|
||||
|
||||
run_id = run["id"]
|
||||
service = getattr(self._app.state, "maf_roundtable_service", None)
|
||||
if service is None:
|
||||
raise MafSdkNotAvailableError("MAF roundtable service not available")
|
||||
|
||||
runner = WorkflowRunner(self._app, service=service, user_id=user_id)
|
||||
|
||||
task = asyncio.create_task(self._execute(runner, session, run, run_id))
|
||||
self._tasks[run_id] = task
|
||||
task.add_done_callback(lambda t, rid=run_id: self._tasks.pop(rid, None))
|
||||
|
||||
async def _execute(self, runner: Any, session: dict[str, Any], run: dict[str, Any], run_id: str) -> None:
|
||||
"""Execute the workflow, catching all exceptions (they're already persisted by the runner)."""
|
||||
try:
|
||||
await runner.execute(session, run)
|
||||
except Exception:
|
||||
# The runner already persists the failure. Log for observability.
|
||||
logger.exception("MAF workflow execution failed for run %s", run_id)
|
||||
|
||||
async def resume(self, run_id: str, *, user_id: str) -> dict[str, Any] | None:
|
||||
"""Resume a workflow from its checkpoint after an approval decision.
|
||||
|
||||
Called by the router after ``decide_approval`` succeeds. Loads the
|
||||
runner (rebuilding if the process restarted), then calls
|
||||
``runner.resume(run_id)`` which restores ``RoundtableState.from_dict()``
|
||||
and executes the approved action (at-most-once).
|
||||
"""
|
||||
from app.maf_roundtable.workflow_runner import WorkflowRunner
|
||||
|
||||
service = getattr(self._app.state, "maf_roundtable_service", None)
|
||||
if service is None:
|
||||
raise MafSdkNotAvailableError("MAF roundtable service not available")
|
||||
|
||||
runner = WorkflowRunner(self._app, service=service, user_id=user_id)
|
||||
return await runner.resume(run_id)
|
||||
|
||||
async def cancel(self, run_id: str) -> dict[str, Any]:
|
||||
"""Cancel a running workflow AND cascade to DeerFlow sub-runs.
|
||||
|
||||
Returns a structured cancel result so the router can decide whether to
|
||||
finalize the parent run as ``cancelled`` (all sub-runs confirmed
|
||||
cancelled / already terminal) or leave it non-terminal (some sub-runs
|
||||
failed to cancel — must not masquerade as cancelled).
|
||||
|
||||
Result shape::
|
||||
|
||||
{
|
||||
"all_cancelled": bool,
|
||||
"cancelled_run_ids": [...],
|
||||
"failed_run_ids": [...],
|
||||
"still_active_run_ids": [...],
|
||||
}
|
||||
"""
|
||||
from app.maf_roundtable.workflow_runner import WorkflowRunner
|
||||
|
||||
_EMPTY = {"all_cancelled": False, "cancelled_run_ids": [], "failed_run_ids": [], "still_active_run_ids": []}
|
||||
|
||||
# P1c cancel order: the parent run is already in ``cancelling`` (the
|
||||
# router sets it before calling here). We then (1) cascade-cancel the
|
||||
# DeerFlow seat runs first and confirm/record the outcome, and only
|
||||
# (2) cancel the local MAF asyncio task LAST. The router finalizes the
|
||||
# parent run as ``cancelled`` only when every sub-run confirmed
|
||||
# cancelled — a failed cascade must never masquerade as cancelled.
|
||||
service = getattr(self._app.state, "maf_roundtable_service", None)
|
||||
if service is None:
|
||||
return _EMPTY
|
||||
|
||||
run = await service.store.runs.get_run(run_id)
|
||||
if run is None:
|
||||
return _EMPTY
|
||||
|
||||
session = await service.store.sessions.get_session(run["session_id"], user_id=None)
|
||||
if session is None:
|
||||
return _EMPTY
|
||||
|
||||
user_id = session.get("user_id", "default")
|
||||
runner = WorkflowRunner(self._app, service=service, user_id=user_id)
|
||||
|
||||
# Step 1: cascade cancel to DeerFlow sub-runs (works even after a
|
||||
# process restart — the runner reads persisted seat_runs).
|
||||
try:
|
||||
result = await runner.cancel(run_id)
|
||||
except Exception: # noqa: BLE001
|
||||
logger.exception("MAF cancel cascade failed for run %s", run_id)
|
||||
result = dict(_EMPTY)
|
||||
|
||||
# Step 2: cancel the local MAF asyncio task LAST (after the external
|
||||
# sub-runs have been addressed), so we never drop the orchestrator
|
||||
# before its sub-runs are cancelled/recorded.
|
||||
task = self._tasks.get(run_id)
|
||||
if task is not None and not task.done():
|
||||
task.cancel()
|
||||
try:
|
||||
await task
|
||||
except (asyncio.CancelledError, Exception): # noqa: BLE001
|
||||
pass
|
||||
|
||||
return result
|
||||
|
||||
|
||||
_dispatchers: dict[int, MafRunDispatcher] = {}
|
||||
|
||||
|
||||
def get_dispatcher(app: Any) -> MafRunDispatcher:
|
||||
"""Get or create the dispatcher for an app instance (keyed by id)."""
|
||||
app_id = id(app)
|
||||
if app_id not in _dispatchers:
|
||||
_dispatchers[app_id] = MafRunDispatcher(app)
|
||||
return _dispatchers[app_id]
|
||||
@@ -0,0 +1,286 @@
|
||||
"""Translate DeerFlow runtime SSE events into MAF roundtable event types.
|
||||
|
||||
Maps raw StreamBridge chunks (LangGraph Platform-aligned: ``metadata``,
|
||||
``values``, ``updates``, ``messages``, ``error``, ``end``) into the durable
|
||||
MAF event taxonomy persisted to ``maf_roundtable_events``.
|
||||
|
||||
Design constraints:
|
||||
- Pure functions only (no I/O, no state).
|
||||
- Never fabricates events: only emits what the runtime actually produced.
|
||||
- Skill events come ONLY from structured tool/skill metadata, never from
|
||||
guessing based on AI text content.
|
||||
- All payloads are sanitized (credentials/tokens/cookies stripped).
|
||||
- Supports source_event_id for dedup (messages + updates may overlap).
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
from app.maf_roundtable.sanitize import sanitize_payload
|
||||
|
||||
|
||||
def normalize_stream_event(
|
||||
sse_event: str,
|
||||
data: Any,
|
||||
*,
|
||||
agent_id: str,
|
||||
turn_index: int,
|
||||
) -> list[dict[str, Any]]:
|
||||
"""Convert a single DeerFlow SSE frame into zero or more MAF event dicts.
|
||||
|
||||
Each returned dict has:
|
||||
``{event_type, agent_id, turn_index, payload, source_event_id?}``.
|
||||
"""
|
||||
if sse_event == "metadata":
|
||||
return [_make("run.started", agent_id, turn_index, {"run_id": _get(data, "run_id"), "thread_id": _get(data, "thread_id")})]
|
||||
|
||||
if sse_event == "messages":
|
||||
return _normalize_messages(data, agent_id, turn_index)
|
||||
|
||||
if sse_event == "updates":
|
||||
return _normalize_updates(data, agent_id, turn_index)
|
||||
|
||||
if sse_event == "error":
|
||||
return [_make("run.failed", agent_id, turn_index, {"message": _get(data, "message", ""), "name": _get(data, "name", "")})]
|
||||
|
||||
# Structured skill lifecycle events (emitted by DeerFlow skill middleware,
|
||||
# never guessed from AI text content).
|
||||
if sse_event in ("invoke_skill", "skill_search_step"):
|
||||
skill_name = _get(data, "skill_name", "") or ""
|
||||
if sse_event == "invoke_skill":
|
||||
return [_make("skill.started", agent_id, turn_index, {"skill_name": skill_name, "message": _get(data, "message", "")})]
|
||||
return [_make("skill.selected", agent_id, turn_index, {"skill_name": skill_name, "message": _get(data, "message", "")})]
|
||||
|
||||
if sse_event == "skill_result":
|
||||
return [_make("skill.completed", agent_id, turn_index, {"skill_name": _get(data, "skill_name", ""), "message": _get(data, "message", "")})]
|
||||
|
||||
if sse_event == "skill_error":
|
||||
return [_make("skill.failed", agent_id, turn_index, {"skill_name": _get(data, "skill_name", ""), "error": _get(data, "reason", "") or _get(data, "message", "")})]
|
||||
|
||||
if sse_event == "artifact_created":
|
||||
return [_make("artifact.created", agent_id, turn_index, {"artifact_type": _get(data, "artifact_type", ""), "artifact_id": _get(data, "artifact_id", ""), "title": _get(data, "title", "")})]
|
||||
|
||||
return []
|
||||
|
||||
|
||||
def make_turn_started(agent_id: str, turn_index: int, payload: dict[str, Any] | None = None) -> dict[str, Any]:
|
||||
return _make("agent.turn_started", agent_id, turn_index, payload or {})
|
||||
|
||||
|
||||
def make_turn_completed(
|
||||
agent_id: str,
|
||||
turn_index: int,
|
||||
*,
|
||||
content: str,
|
||||
usage: dict[str, Any] | None = None,
|
||||
metadata: dict[str, Any] | None = None,
|
||||
) -> dict[str, Any]:
|
||||
payload: dict[str, Any] = {"content": content}
|
||||
if usage:
|
||||
payload["usage"] = usage
|
||||
if metadata:
|
||||
payload["metadata"] = metadata
|
||||
return _make("agent.message.completed", agent_id, turn_index, payload)
|
||||
|
||||
|
||||
def make_run_completed(agent_id: str | None, turn_index: int, payload: dict[str, Any] | None = None) -> dict[str, Any]:
|
||||
return _make("run.completed", agent_id or "", turn_index, payload or {})
|
||||
|
||||
|
||||
def make_run_failed(agent_id: str | None, turn_index: int, *, error_code: str, message: str) -> dict[str, Any]:
|
||||
return _make("run.failed", agent_id or "", turn_index, {"error_code": error_code, "message": message})
|
||||
|
||||
|
||||
def make_run_cancelled(agent_id: str | None, turn_index: int) -> dict[str, Any]:
|
||||
return _make("run.cancelled", agent_id or "", turn_index, {})
|
||||
|
||||
|
||||
# ── skill lifecycle events ─────────────────────────────────────────────────
|
||||
|
||||
|
||||
def make_skill_selected(agent_id: str, turn_index: int, *, skill_name: str, skill_id: str = "") -> dict[str, Any]:
|
||||
return _make("skill.selected", agent_id, turn_index, {"skill_name": skill_name, "skill_id": skill_id})
|
||||
|
||||
|
||||
def make_skill_started(agent_id: str, turn_index: int, *, skill_name: str, skill_id: str = "") -> dict[str, Any]:
|
||||
return _make("skill.started", agent_id, turn_index, {"skill_name": skill_name, "skill_id": skill_id})
|
||||
|
||||
|
||||
def make_skill_completed(agent_id: str, turn_index: int, *, skill_name: str, result_preview: str = "") -> dict[str, Any]:
|
||||
return _make("skill.completed", agent_id, turn_index, {"skill_name": skill_name, "result_preview": _truncate(result_preview, 500)})
|
||||
|
||||
|
||||
def make_skill_failed(agent_id: str, turn_index: int, *, skill_name: str, error: str = "") -> dict[str, Any]:
|
||||
return _make("skill.failed", agent_id, turn_index, {"skill_name": skill_name, "error": _truncate(error, 500)})
|
||||
|
||||
|
||||
# ── artifact events ────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def make_artifact_created(agent_id: str, turn_index: int, *, artifact_type: str, artifact_id: str = "", title: str = "") -> dict[str, Any]:
|
||||
return _make("artifact.created", agent_id, turn_index, {"artifact_type": artifact_type, "artifact_id": artifact_id, "title": title})
|
||||
|
||||
|
||||
# ── approval lifecycle events ──────────────────────────────────────────────
|
||||
|
||||
|
||||
def make_action_waiting_approval(agent_id: str, turn_index: int, *, action_id: str, approval_id: str, tool_name: str, summary: str = "") -> dict[str, Any]:
|
||||
return _make("action.waiting_approval", agent_id, turn_index, {"action_id": action_id, "approval_id": approval_id, "tool_name": tool_name, "summary": _truncate(summary, 500)})
|
||||
|
||||
|
||||
def make_action_approved(agent_id: str, turn_index: int, *, action_id: str, approval_id: str, decided_by: str = "") -> dict[str, Any]:
|
||||
return _make("action.approved", agent_id, turn_index, {"action_id": action_id, "approval_id": approval_id, "decided_by": decided_by})
|
||||
|
||||
|
||||
def make_action_rejected(agent_id: str, turn_index: int, *, action_id: str, approval_id: str, decided_by: str = "") -> dict[str, Any]:
|
||||
return _make("action.rejected", agent_id, turn_index, {"action_id": action_id, "approval_id": approval_id, "decided_by": decided_by})
|
||||
|
||||
|
||||
# ── workflow checkpoint events ─────────────────────────────────────────────
|
||||
|
||||
|
||||
def make_workflow_checkpointed(agent_id: str | None, turn_index: int, *, checkpoint_id: str, reason: str = "") -> dict[str, Any]:
|
||||
return _make("workflow.checkpointed", agent_id or "", turn_index, {"checkpoint_id": checkpoint_id, "reason": reason})
|
||||
|
||||
|
||||
# ── internal helpers ──────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def _make(event_type: str, agent_id: str, turn_index: int, payload: dict[str, Any], source_event_id: str | None = None) -> dict[str, Any]:
|
||||
ev: dict[str, Any] = {
|
||||
"event_type": event_type,
|
||||
"agent_id": agent_id,
|
||||
"turn_index": turn_index,
|
||||
"payload": sanitize_payload(payload),
|
||||
}
|
||||
if source_event_id:
|
||||
ev["source_event_id"] = source_event_id
|
||||
return ev
|
||||
|
||||
|
||||
def _get(data: Any, key: str, default: Any = None) -> Any:
|
||||
if isinstance(data, dict):
|
||||
return data.get(key, default)
|
||||
return default
|
||||
|
||||
|
||||
def _normalize_messages(data: Any, agent_id: str, turn_index: int) -> list[dict[str, Any]]:
|
||||
"""Handle ``messages`` SSE event (streaming token deltas).
|
||||
|
||||
Format: ``[message_id, {type, content, ...}]`` (messages-tuple mode).
|
||||
"""
|
||||
events: list[dict[str, Any]] = []
|
||||
if not isinstance(data, (list, tuple)) or len(data) < 2:
|
||||
return events
|
||||
msg_id = str(data[0]) if data[0] else None
|
||||
msg = data[1] if len(data) > 1 else None
|
||||
if not isinstance(msg, dict):
|
||||
return events
|
||||
|
||||
msg_type = msg.get("type") or msg.get("role") or ""
|
||||
content = msg.get("content")
|
||||
|
||||
if msg_type in ("ai", "assistant"):
|
||||
tool_calls = msg.get("tool_calls")
|
||||
if tool_calls:
|
||||
for tc in tool_calls:
|
||||
if not isinstance(tc, dict):
|
||||
continue
|
||||
tc_id = tc.get("id", "")
|
||||
events.append(_make("tool.requested", agent_id, turn_index, {
|
||||
"tool_name": tc.get("name", ""),
|
||||
"tool_call_id": tc_id,
|
||||
"args": _summarize_args(tc.get("args")),
|
||||
}, source_event_id=f"{msg_id}:{tc_id}" if msg_id and tc_id else None))
|
||||
if content:
|
||||
text = _extract_text(content)
|
||||
if text:
|
||||
events.append(_make("agent.message.delta", agent_id, turn_index, {"text": text}, source_event_id=msg_id))
|
||||
|
||||
elif msg_type == "tool":
|
||||
tc_id = msg.get("tool_call_id", "")
|
||||
status = msg.get("status", "completed")
|
||||
event_type = "tool.completed" if status != "error" else "tool.failed"
|
||||
events.append(_make(event_type, agent_id, turn_index, {
|
||||
"tool_name": msg.get("name", ""),
|
||||
"tool_call_id": tc_id,
|
||||
"content_preview": _truncate(_extract_text(content), 500),
|
||||
"status": status,
|
||||
}, source_event_id=f"tool:{tc_id}" if tc_id else None))
|
||||
|
||||
return events
|
||||
|
||||
|
||||
def _normalize_updates(data: Any, agent_id: str, turn_index: int) -> list[dict[str, Any]]:
|
||||
"""Handle ``updates`` SSE event (node completion with full output).
|
||||
|
||||
Only emits tool lifecycle events from structured data. Does NOT guess
|
||||
skill execution from text content.
|
||||
"""
|
||||
events: list[dict[str, Any]] = []
|
||||
if not isinstance(data, dict):
|
||||
return events
|
||||
|
||||
for node_name, node_output in data.items():
|
||||
if not isinstance(node_output, dict):
|
||||
continue
|
||||
messages = node_output.get("messages")
|
||||
if not isinstance(messages, list):
|
||||
continue
|
||||
for msg in messages:
|
||||
if not isinstance(msg, dict):
|
||||
continue
|
||||
msg_type = msg.get("type") or msg.get("role") or ""
|
||||
if msg_type in ("ai", "assistant"):
|
||||
tool_calls = msg.get("tool_calls")
|
||||
if tool_calls:
|
||||
for tc in tool_calls:
|
||||
if not isinstance(tc, dict):
|
||||
continue
|
||||
tc_id = tc.get("id", "")
|
||||
events.append(_make("tool.started", agent_id, turn_index, {
|
||||
"tool_name": tc.get("name", ""),
|
||||
"tool_call_id": tc_id,
|
||||
"node": node_name,
|
||||
}, source_event_id=f"upd:{tc_id}" if tc_id else None))
|
||||
elif msg_type == "tool":
|
||||
tc_id = msg.get("tool_call_id", "")
|
||||
status = msg.get("status", "completed")
|
||||
event_type = "tool.completed" if status != "error" else "tool.failed"
|
||||
events.append(_make(event_type, agent_id, turn_index, {
|
||||
"tool_name": msg.get("name", ""),
|
||||
"tool_call_id": tc_id,
|
||||
"content_preview": _truncate(_extract_text(msg.get("content")), 500),
|
||||
"status": status,
|
||||
"node": node_name,
|
||||
}, source_event_id=f"upd:tool:{tc_id}" if tc_id else None))
|
||||
return events
|
||||
|
||||
|
||||
def _extract_text(content: Any) -> str:
|
||||
if isinstance(content, str):
|
||||
return content
|
||||
if isinstance(content, list):
|
||||
parts = []
|
||||
for p in content:
|
||||
if isinstance(p, dict) and p.get("type") == "text":
|
||||
parts.append(p.get("text", ""))
|
||||
elif isinstance(p, str):
|
||||
parts.append(p)
|
||||
return "\n".join(parts)
|
||||
return ""
|
||||
|
||||
|
||||
def _truncate(text: str, max_len: int) -> str:
|
||||
if len(text) <= max_len:
|
||||
return text
|
||||
return text[:max_len] + "..."
|
||||
|
||||
|
||||
def _summarize_args(args: Any) -> dict[str, Any] | None:
|
||||
if not isinstance(args, dict):
|
||||
return None
|
||||
from app.maf_roundtable.sanitize import sanitize
|
||||
result = sanitize(args)
|
||||
return result if isinstance(result, dict) else None
|
||||
@@ -0,0 +1,333 @@
|
||||
"""Controlled DeerFlow runtime invocation client for MAF roundtable.
|
||||
|
||||
All invocations require an explicit ``ExecutionPrincipal`` — the server-generated
|
||||
identity derived ONLY from the authenticated MAF session owner. No raw tokens,
|
||||
cookies, or credentials ever pass into events, checkpoints, or prompts.
|
||||
|
||||
Two invocation modes (the adapter uses mode 2):
|
||||
1. Direct checkpointer access for thread creation and message reads.
|
||||
2. In-process ``start_run`` via a typed internal request that carries the
|
||||
principal's user identity (never ``user=None``).
|
||||
|
||||
Security invariants:
|
||||
- ExecutionPrincipal is constructed ONLY from the MAF session's user_id.
|
||||
- The internal request object explicitly carries the principal's user so
|
||||
downstream code sees a real identity, not a None placeholder.
|
||||
- Agent access is enforced server-side (enforce_access=True).
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import uuid
|
||||
from dataclasses import dataclass
|
||||
from datetime import UTC, datetime
|
||||
from typing import Any
|
||||
|
||||
from langgraph.checkpoint.base import empty_checkpoint
|
||||
|
||||
from deerflow.runtime.user_context import reset_current_user, set_current_user
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def _serialize_tool_result(result: Any) -> Any:
|
||||
"""Convert a tool result to a JSON-safe dict/list/str/int/float/bool/None."""
|
||||
if result is None:
|
||||
return None
|
||||
if isinstance(result, (str, int, float, bool)):
|
||||
return result
|
||||
if isinstance(result, (list, tuple)):
|
||||
return [_serialize_tool_result(v) for v in result]
|
||||
if isinstance(result, dict):
|
||||
return {str(k): _serialize_tool_result(v) for k, v in result.items()}
|
||||
return str(result)[:1000]
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ExecutionPrincipal:
|
||||
"""Server-generated execution identity for a MAF seat run.
|
||||
|
||||
Constructed ONLY from the authenticated MAF session owner. Never from
|
||||
request body, query params, or client-supplied data.
|
||||
"""
|
||||
|
||||
user_id: str
|
||||
session_id: str
|
||||
run_id: str
|
||||
|
||||
def __post_init__(self) -> None:
|
||||
if not self.user_id or not self.user_id.strip():
|
||||
raise ValueError("ExecutionPrincipal requires a non-empty user_id")
|
||||
|
||||
|
||||
class _PrincipalUser:
|
||||
"""Minimal CurrentUser protocol implementation backed by ExecutionPrincipal."""
|
||||
|
||||
def __init__(self, principal: ExecutionPrincipal) -> None:
|
||||
self.id = principal.user_id
|
||||
|
||||
|
||||
class _InternalState:
|
||||
"""Typed state container for the internal run request.
|
||||
|
||||
Carries the principal's user identity explicitly — never None — so
|
||||
downstream access checks and run metadata attribution work correctly.
|
||||
"""
|
||||
|
||||
def __init__(self, principal: ExecutionPrincipal) -> None:
|
||||
self.user = _PrincipalUser(principal)
|
||||
self.auth = None
|
||||
|
||||
|
||||
@dataclass
|
||||
class _InternalRunRequest:
|
||||
"""Typed internal request for in-process agent run invocation.
|
||||
|
||||
Replaces the former ``SimpleNamespace(app=..., state=SimpleNamespace(user=None))``
|
||||
pattern. The state explicitly carries the principal's user identity.
|
||||
"""
|
||||
|
||||
app: Any
|
||||
state: _InternalState
|
||||
|
||||
@classmethod
|
||||
def from_principal(cls, app: Any, principal: ExecutionPrincipal) -> _InternalRunRequest:
|
||||
return cls(app=app, state=_InternalState(principal))
|
||||
|
||||
|
||||
class DeerFlowRuntimeClient:
|
||||
"""Controlled entry point for invoking the DeerFlow Agent Runtime from MAF.
|
||||
|
||||
All calls require an ExecutionPrincipal. The client:
|
||||
- Sets the user ContextVar before each invocation.
|
||||
- Creates threads with proper user attribution.
|
||||
- Invokes start_run with server-generated identity.
|
||||
- Never passes raw tokens or credentials downstream.
|
||||
"""
|
||||
|
||||
def __init__(self, app: Any) -> None:
|
||||
self._app = app
|
||||
|
||||
@property
|
||||
def app(self) -> Any:
|
||||
return self._app
|
||||
|
||||
async def create_thread(self, principal: ExecutionPrincipal) -> str:
|
||||
"""Create a DeerFlow thread owned by the principal's user.
|
||||
|
||||
The user ContextVar is set so thread_store.create records the correct
|
||||
user_id in thread_meta.
|
||||
"""
|
||||
token = set_current_user(_PrincipalUser(principal))
|
||||
try:
|
||||
checkpointer = self._app.state.checkpointer
|
||||
thread_store = self._app.state.thread_store
|
||||
thread_id = str(uuid.uuid4())
|
||||
await thread_store.create(
|
||||
thread_id,
|
||||
assistant_id=None,
|
||||
metadata={
|
||||
"thread_type": "maf_roundtable",
|
||||
"system": True,
|
||||
"maf_session_id": principal.session_id,
|
||||
"maf_run_id": principal.run_id,
|
||||
},
|
||||
)
|
||||
config = {"configurable": {"thread_id": thread_id, "checkpoint_ns": ""}}
|
||||
await checkpointer.aput(
|
||||
config,
|
||||
empty_checkpoint(),
|
||||
{"step": -1, "source": "input", "writes": None, "parents": {}, "created_at": datetime.now(UTC).isoformat()},
|
||||
{},
|
||||
)
|
||||
return thread_id
|
||||
finally:
|
||||
reset_current_user(token)
|
||||
|
||||
async def start_agent_run(
|
||||
self,
|
||||
principal: ExecutionPrincipal,
|
||||
*,
|
||||
thread_id: str,
|
||||
agent_id: str,
|
||||
message: str,
|
||||
model_name: str | None = None,
|
||||
reasoning_effort: str | None = None,
|
||||
thinking_enabled: bool = True,
|
||||
subagent_enabled: bool = False,
|
||||
excluded_tools: list[str] | None = None,
|
||||
memory_recall_disabled: bool | None = None,
|
||||
memory_injection_enabled: bool | None = None,
|
||||
turn_index: int = 0,
|
||||
capability_snapshot: dict[str, Any] | None = None,
|
||||
write_policy: str = "confirm_high_risk",
|
||||
approved_tool: str | None = None,
|
||||
approved_action_id: str | None = None,
|
||||
) -> Any:
|
||||
"""Start a DeerFlow agent run under the principal's identity.
|
||||
|
||||
Returns the RunRecord (with .task and .run_id). The caller must await
|
||||
the task and handle exceptions.
|
||||
|
||||
WriteGuard activation: when ``write_policy != "auto"`` the run context
|
||||
carries ``maf_run_id`` (the activation flag the WriteGuard middleware
|
||||
checks) plus the per-run data the interceptor needs to record a
|
||||
pending action. ``excluded_tools`` here MUST only contain tools the
|
||||
user explicitly disabled — write tools are no longer excluded (the
|
||||
middleware intercepts them instead, keeping them visible to the model).
|
||||
"""
|
||||
from app.gateway.routers.thread_runs import RunCreateRequest
|
||||
from app.gateway.services import RUN_SCOPE_BACKGROUND_CHILD, start_run
|
||||
|
||||
context: dict[str, Any] = {
|
||||
"agent_name": agent_id,
|
||||
"model_name": model_name or "",
|
||||
"mode": "pro",
|
||||
"reasoning_effort": reasoning_effort or "medium",
|
||||
"thinking_enabled": thinking_enabled,
|
||||
"is_plan_mode": False,
|
||||
"subagent_enabled": subagent_enabled,
|
||||
"thread_id": thread_id,
|
||||
}
|
||||
if memory_recall_disabled is not None:
|
||||
context["memory_recall_disabled"] = memory_recall_disabled
|
||||
if memory_injection_enabled is not None:
|
||||
context["memory_injection_enabled"] = memory_injection_enabled
|
||||
|
||||
# WriteGuard activation + per-run data (server-generated identity only).
|
||||
# ``maf_run_id`` is the flag the WriteGuard middleware checks to decide
|
||||
# whether to intercept; the rest is the data the interceptor reads.
|
||||
context["maf_run_id"] = principal.run_id
|
||||
context["maf_session_id"] = principal.session_id
|
||||
context["maf_user_id"] = principal.user_id
|
||||
context["agent_id"] = agent_id
|
||||
context["turn_index"] = turn_index
|
||||
context["write_policy"] = write_policy
|
||||
if capability_snapshot is not None:
|
||||
context["capability_snapshot"] = capability_snapshot
|
||||
# Post-approval deterministic execution: when set, the WriteGuard
|
||||
# middleware passes this single tool through without interception.
|
||||
# ``maf_approved_action_id`` binds the passthrough to a specific
|
||||
# approved action — the middleware validates both tool name AND
|
||||
# action_id so a model calling another tool with the same name is
|
||||
# still intercepted (defense-in-depth when combined with direct
|
||||
# tool execution that bypasses the LLM).
|
||||
if approved_tool:
|
||||
context["maf_approved_tool"] = approved_tool
|
||||
if approved_action_id:
|
||||
context["maf_approved_action_id"] = approved_action_id
|
||||
|
||||
body = RunCreateRequest(
|
||||
assistant_id="lead_agent",
|
||||
input={"messages": [{"type": "human", "content": [{"type": "text", "text": message}], "additional_kwargs": {}}]},
|
||||
metadata={"run_scope": RUN_SCOPE_BACKGROUND_CHILD, "maf_run_id": principal.run_id},
|
||||
config={"recursion_limit": 1000},
|
||||
context=context,
|
||||
excluded_tools=excluded_tools or [],
|
||||
on_disconnect="continue",
|
||||
multitask_strategy="reject",
|
||||
)
|
||||
# Typed internal request carrying the principal's identity — never user=None.
|
||||
request = _InternalRunRequest.from_principal(self._app, principal)
|
||||
|
||||
token = set_current_user(_PrincipalUser(principal))
|
||||
try:
|
||||
record = await start_run(
|
||||
body,
|
||||
thread_id,
|
||||
request,
|
||||
run_scope=RUN_SCOPE_BACKGROUND_CHILD,
|
||||
)
|
||||
return record
|
||||
finally:
|
||||
reset_current_user(token)
|
||||
|
||||
async def read_thread_messages(self, principal: ExecutionPrincipal, thread_id: str) -> list[dict[str, Any]]:
|
||||
"""Read the latest checkpoint messages from a thread."""
|
||||
from deerflow.runtime.serialization import serialize_channel_values
|
||||
|
||||
token = set_current_user(_PrincipalUser(principal))
|
||||
try:
|
||||
checkpointer = self._app.state.checkpointer
|
||||
config = {"configurable": {"thread_id": thread_id, "checkpoint_ns": ""}}
|
||||
ct = await checkpointer.aget_tuple(config)
|
||||
if ct is None:
|
||||
return []
|
||||
checkpoint = getattr(ct, "checkpoint", {}) or {}
|
||||
values = serialize_channel_values(checkpoint.get("channel_values", {}) or {})
|
||||
return values.get("messages") or []
|
||||
finally:
|
||||
reset_current_user(token)
|
||||
|
||||
async def execute_tool_directly(
|
||||
self,
|
||||
*,
|
||||
thread_id: str,
|
||||
agent_id: str,
|
||||
tool_name: str,
|
||||
params: dict[str, Any],
|
||||
principal: ExecutionPrincipal,
|
||||
turn_index: int,
|
||||
capability_snapshot: dict[str, Any] | None,
|
||||
write_policy: str,
|
||||
approved_action_id: str,
|
||||
action_record: dict[str, Any] | None,
|
||||
model_name: str | None = None,
|
||||
excluded_tools: list[str] | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Execute a DeerFlow tool directly without LLM involvement.
|
||||
|
||||
For post-approval deterministic execution this delegates to the harness
|
||||
``execute_approved_tool``, which runs the call through the **real**
|
||||
LangGraph ``ToolNode`` / ``ToolRuntime`` / middleware chain (state
|
||||
recovered from the thread checkpoint), not a faked runtime. No raw
|
||||
params enter any prompt, checkpoint, or model context.
|
||||
|
||||
Returns ``{"status": "succeeded", "result": ...}`` or
|
||||
``{"status": "failed", "error": "..."}``. A security rejection
|
||||
(unauthorized / disabled / nonexistent tool, context mismatch) is a
|
||||
``failed`` outcome and the tool executes 0 times.
|
||||
"""
|
||||
from deerflow.config import get_app_config
|
||||
from deerflow.tools.approved_tool_executor import execute_approved_tool
|
||||
|
||||
app_config = get_app_config()
|
||||
checkpointer = getattr(self._app.state, "checkpointer", None)
|
||||
store = getattr(self._app.state, "store", None)
|
||||
|
||||
return await execute_approved_tool(
|
||||
app_config=app_config,
|
||||
checkpointer=checkpointer,
|
||||
store=store,
|
||||
thread_id=thread_id,
|
||||
user_id=principal.user_id,
|
||||
session_id=principal.session_id,
|
||||
run_id=principal.run_id,
|
||||
agent_id=agent_id,
|
||||
turn_index=turn_index,
|
||||
model_name=model_name,
|
||||
excluded_tools=excluded_tools,
|
||||
capability_snapshot=capability_snapshot,
|
||||
write_policy=write_policy,
|
||||
tool_name=tool_name,
|
||||
params=params,
|
||||
approved_action_id=approved_action_id,
|
||||
action_record=action_record,
|
||||
)
|
||||
|
||||
async def cancel_run(self, deerflow_run_id: str) -> bool:
|
||||
"""Cancel a DeerFlow run by its run_id."""
|
||||
run_manager = getattr(self._app.state, "run_manager", None)
|
||||
if run_manager is None:
|
||||
return False
|
||||
try:
|
||||
await run_manager.cancel(deerflow_run_id, action="interrupt")
|
||||
return True
|
||||
except Exception as exc: # noqa: BLE001
|
||||
# Log only the exception type — never the raw message/traceback,
|
||||
# which may carry params or credentials.
|
||||
logger.warning(
|
||||
"cancel DeerFlow run %s failed (%s)", deerflow_run_id, type(exc).__name__
|
||||
)
|
||||
return False
|
||||
@@ -0,0 +1,103 @@
|
||||
"""Recursive sanitization for MAF roundtable events, payloads, and logs.
|
||||
|
||||
Strips credentials, tokens, cookies, passwords, secrets, and API keys from
|
||||
nested data structures before they reach the event store, context builder,
|
||||
or log output. Applied uniformly to tool arguments, tool results, fact
|
||||
ledger entries, and event payloads.
|
||||
|
||||
Design:
|
||||
- Pure functions, no I/O.
|
||||
- Recursive: handles nested dicts, lists, and strings.
|
||||
- Key-based: redacts values whose key matches a sensitive pattern.
|
||||
- Value-based: redacts string values that look like tokens/keys.
|
||||
- Never raises: malformed input passes through unchanged (best-effort).
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from typing import Any
|
||||
|
||||
_SENSITIVE_KEYS = frozenset({
|
||||
"token", "access_token", "refresh_token", "id_token",
|
||||
"authorization", "auth", "auth_token", "authtoken",
|
||||
"cookie", "cookies", "set-cookie",
|
||||
"password", "passwd", "pwd",
|
||||
"secret", "secret_key", "client_secret",
|
||||
"api_key", "apikey", "api-key",
|
||||
"private_key", "private-key",
|
||||
"credential", "credentials",
|
||||
"session_id", "sessionid",
|
||||
"x-api-key", "x-auth-token",
|
||||
})
|
||||
|
||||
_KEY_PATTERN = re.compile(
|
||||
r"(token|authorization|cookie|password|passwd|secret|api[_-]?key|private[_-]?key|credential|bearer)",
|
||||
re.IGNORECASE,
|
||||
)
|
||||
|
||||
_VALUE_PATTERNS = [
|
||||
re.compile(r"^Bearer\s+\S+", re.IGNORECASE),
|
||||
re.compile(r"^(sk|pk|ak|rk)[_-][A-Za-z0-9]{16,}$"),
|
||||
re.compile(r"^eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}"),
|
||||
re.compile(r"^[A-Za-z0-9+/]{40,}={0,2}$"),
|
||||
]
|
||||
|
||||
_INLINE_SECRET_PATTERN = re.compile(
|
||||
r"(token|password|passwd|secret|api[_-]?key|authorization|cookie)\s*[=:]\s*\S+",
|
||||
re.IGNORECASE,
|
||||
)
|
||||
|
||||
_REDACTED = "***REDACTED***"
|
||||
_MAX_DEPTH = 12
|
||||
|
||||
|
||||
def sanitize(data: Any, *, _depth: int = 0) -> Any:
|
||||
"""Recursively sanitize sensitive fields from a data structure."""
|
||||
if _depth > _MAX_DEPTH:
|
||||
return data
|
||||
if isinstance(data, dict):
|
||||
return _sanitize_dict(data, _depth)
|
||||
if isinstance(data, (list, tuple)):
|
||||
return [sanitize(item, _depth=_depth + 1) for item in data]
|
||||
if isinstance(data, str):
|
||||
return _sanitize_value_str(data)
|
||||
return data
|
||||
|
||||
|
||||
def sanitize_payload(payload: dict[str, Any] | None) -> dict[str, Any] | None:
|
||||
"""Sanitize an event payload dict. Returns None if input is None."""
|
||||
if payload is None:
|
||||
return None
|
||||
result = sanitize(payload)
|
||||
return result if isinstance(result, dict) else payload
|
||||
|
||||
|
||||
def _sanitize_dict(d: dict[str, Any], depth: int) -> dict[str, Any]:
|
||||
out: dict[str, Any] = {}
|
||||
for key, value in d.items():
|
||||
key_lower = str(key).lower().replace("-", "_")
|
||||
if key_lower in _SENSITIVE_KEYS or _KEY_PATTERN.search(key_lower):
|
||||
out[key] = _REDACTED
|
||||
elif isinstance(value, dict):
|
||||
out[key] = _sanitize_dict(value, depth + 1)
|
||||
elif isinstance(value, (list, tuple)):
|
||||
out[key] = [sanitize(item, _depth=depth + 1) for item in value]
|
||||
elif isinstance(value, str):
|
||||
out[key] = _sanitize_value_str(value)
|
||||
else:
|
||||
out[key] = value
|
||||
return out
|
||||
|
||||
|
||||
def _sanitize_value_str(s: str) -> str:
|
||||
# Never skip sanitization based on length — long strings (error traces,
|
||||
# log dumps, seat-run errors) may embed credentials deep inside.
|
||||
for pat in _VALUE_PATTERNS:
|
||||
if pat.match(s):
|
||||
return _REDACTED
|
||||
if _INLINE_SECRET_PATTERN.search(s):
|
||||
return _INLINE_SECRET_PATTERN.sub(
|
||||
lambda m: m.group(0).split("=")[0].split(":")[0] + "=***REDACTED***", s
|
||||
)
|
||||
return s
|
||||
@@ -30,8 +30,8 @@ class ParticipantInput(BaseModel):
|
||||
display_name: str = Field(default="", max_length=255)
|
||||
role: MafParticipantRole = "seat"
|
||||
sort_order: int = 0
|
||||
# Frozen at creation — the agent's tools / skills snapshot.
|
||||
capability_snapshot: dict[str, Any] | None = None
|
||||
# Subtractive only: tools removed from the server-resolved allow-list for this seat.
|
||||
excluded_tools: list[str] = Field(default_factory=list)
|
||||
|
||||
|
||||
class CreateSessionRequest(BaseModel):
|
||||
@@ -48,8 +48,8 @@ class CreateSessionRequest(BaseModel):
|
||||
# Optional: omitted → MafRoundtableConfig.default_write_policy.
|
||||
write_policy: MafWritePolicy | None = None
|
||||
participants: list[ParticipantInput] = Field(default_factory=list)
|
||||
# Frozen at creation — the full session capability snapshot (agents + tools + skills).
|
||||
capability_snapshot: dict[str, Any] | None = None
|
||||
# Subtractive session-wide tool exclusions (applied per seat when building snapshot).
|
||||
excluded_tools: list[str] = Field(default_factory=list)
|
||||
|
||||
|
||||
# Fields that must not be explicitly set to null on PUT (→ 422).
|
||||
|
||||
@@ -30,11 +30,15 @@ reserved / not-yet-executing state) rather than pretending to be ``running``.
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from typing import Any
|
||||
|
||||
from app.maf_roundtable.sanitize import sanitize, sanitize_payload
|
||||
from deerflow.config.maf_roundtable_config import MafRoundtableConfig
|
||||
from deerflow.persistence.maf_roundtable.store import MafRoundtableStore
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class MafDisabledError(RuntimeError):
|
||||
"""Raised when a write is attempted while the feature flag is off."""
|
||||
@@ -64,11 +68,67 @@ class MafForbiddenError(PermissionError):
|
||||
self.ident = ident
|
||||
|
||||
|
||||
class MafConfigurationError(RuntimeError):
|
||||
"""MAF is enabled but a required safety prerequisite is missing.
|
||||
|
||||
Raised by :func:`validate_maf_prerequisites` on the startup path so the
|
||||
feature can never come up in a half-safe state ("MAF on, approval guard not
|
||||
mounted"). The gateway lifespan catches this and forces the feature OFF
|
||||
(clearly logged) rather than aborting the whole (experimental, opt-in)
|
||||
service.
|
||||
"""
|
||||
|
||||
|
||||
def validate_maf_prerequisites() -> None:
|
||||
"""Fail loudly if MAF is enabled without its full safety stack in place.
|
||||
|
||||
Checks, in order:
|
||||
1. ``write_guard.enabled`` is true (the approval guard is mounted);
|
||||
2. ``write_guard.provider`` is complete (``policy_use`` + ``interceptor_use``);
|
||||
3. the bridge factories actually resolve (the app-layer guard is importable);
|
||||
4. ``MAF_ACTION_SECRET_KEY`` is set (action params are encrypted with it).
|
||||
|
||||
Raises ``MafConfigurationError`` on the first unmet condition. Callers on
|
||||
the startup path treat that as "force the feature off"; direct unit-test
|
||||
construction of :class:`MafRoundtableService` does NOT call this.
|
||||
"""
|
||||
import os
|
||||
|
||||
from deerflow.config.write_guard_config import get_write_guard_config
|
||||
from deerflow.reflection import resolve_variable
|
||||
|
||||
wg = get_write_guard_config()
|
||||
if not wg.enabled:
|
||||
raise MafConfigurationError(
|
||||
"maf_roundtable.enabled=true requires write_guard.enabled=true "
|
||||
"(the approval guard must be mounted)"
|
||||
)
|
||||
provider = wg.provider
|
||||
if provider is None or not provider.policy_use or not provider.interceptor_use:
|
||||
raise MafConfigurationError(
|
||||
"maf_roundtable.enabled=true requires a complete write_guard.provider "
|
||||
"(policy_use + interceptor_use)"
|
||||
)
|
||||
try:
|
||||
resolve_variable(provider.policy_use)
|
||||
resolve_variable(provider.interceptor_use)
|
||||
except Exception as exc: # noqa: BLE001
|
||||
raise MafConfigurationError(
|
||||
f"write_guard bridge factories are not resolvable: {exc}"
|
||||
) from exc
|
||||
if not (os.getenv("MAF_ACTION_SECRET_KEY") or "").strip():
|
||||
raise MafConfigurationError(
|
||||
"maf_roundtable.enabled=true requires the MAF_ACTION_SECRET_KEY env var"
|
||||
)
|
||||
|
||||
|
||||
# Session statuses that may be edited (config changes).
|
||||
_EDITABLE_STATUSES = {"draft", "completed", "failed", "cancelled"}
|
||||
# Session statuses that mean a run is in flight (no config edits). ``starting``
|
||||
# is the transient CAS-claim state between "claimed" and "run row created".
|
||||
_RUNNING_STATUSES = {"starting", "running", "waiting_approval", "waiting_input"}
|
||||
# ``cancel_failed`` blocks edits because the cancel cascade is incomplete and
|
||||
# the may still have active sub-runs.
|
||||
_RUNNING_STATUSES = {"starting", "running", "waiting_approval", "waiting_input", "cancelling", "cancel_failed"}
|
||||
|
||||
|
||||
class MafRoundtableService:
|
||||
@@ -79,14 +139,37 @@ class MafRoundtableService:
|
||||
enabled: bool,
|
||||
admin_diagnostic_access: bool,
|
||||
config: MafRoundtableConfig | None = None,
|
||||
agent_store: Any | None = None,
|
||||
app_config: Any | None = None,
|
||||
) -> None:
|
||||
self._store = store
|
||||
self._enabled = enabled
|
||||
self._admin_diagnostic_access = admin_diagnostic_access
|
||||
self._agent_store = agent_store
|
||||
self._app_config = app_config
|
||||
# Defaults source for create_session; falls back to the pydantic
|
||||
# defaults when no config is injected (keeps unit tests lightweight).
|
||||
self._config = config or MafRoundtableConfig()
|
||||
|
||||
# Startup validation: if the MAF feature is enabled, the
|
||||
# ``MAF_ACTION_SECRET_KEY`` env var MUST be set — external-write
|
||||
# action params are encrypted with it and there is no default key.
|
||||
# A missing key forces the feature off (write paths then return 503)
|
||||
# rather than running with a publicly-known key. This never aborts
|
||||
# Gateway startup (the feature is experimental / opt-in).
|
||||
if enabled:
|
||||
import os
|
||||
|
||||
key = os.getenv("MAF_ACTION_SECRET_KEY", "")
|
||||
if not key or not key.strip():
|
||||
logger.error(
|
||||
"[maf-roundtable] MAF_ACTION_SECRET_KEY is not set — "
|
||||
"disabling the feature (write paths will return 503). "
|
||||
"Set a 32+ char random string before enabling "
|
||||
"maf_roundtable.enabled."
|
||||
)
|
||||
enabled = False
|
||||
self._enabled = enabled
|
||||
|
||||
@property
|
||||
def store(self) -> MafRoundtableStore:
|
||||
return self._store
|
||||
@@ -132,8 +215,52 @@ class MafRoundtableService:
|
||||
) -> dict[str, Any]:
|
||||
self._require_enabled()
|
||||
cfg = self._config
|
||||
# Config-driven defaults: an omitted field falls back to the deployed
|
||||
# MafRoundtableConfig value; an explicit request value always wins.
|
||||
from app.maf_roundtable.capability_snapshot import (
|
||||
AgentNotAccessibleError,
|
||||
InvalidExcludedToolsError,
|
||||
build_trusted_capability_snapshot,
|
||||
seat_snapshot_for_agent,
|
||||
)
|
||||
from deerflow.config import get_app_config
|
||||
|
||||
app_config = self._app_config or get_app_config()
|
||||
raw_participants = list(body.get("participants") or [])
|
||||
# Strip any client-supplied snapshot / tool metadata — never trusted.
|
||||
participants: list[dict[str, Any]] = []
|
||||
for p in raw_participants:
|
||||
participants.append(
|
||||
{
|
||||
"agent_id": p.get("agent_id"),
|
||||
"display_name": p.get("display_name", ""),
|
||||
"role": p.get("role", "seat"),
|
||||
"sort_order": p.get("sort_order", 0),
|
||||
"thread_id": p.get("thread_id"),
|
||||
"excluded_tools": p.get("excluded_tools") or [],
|
||||
}
|
||||
)
|
||||
|
||||
try:
|
||||
trusted_snapshot = await build_trusted_capability_snapshot(
|
||||
user_id=user_id,
|
||||
participants=participants,
|
||||
app_config=app_config,
|
||||
agent_store=self._agent_store,
|
||||
session_model_name=body.get("model_name"),
|
||||
session_reasoning_effort=body.get("reasoning_effort"),
|
||||
session_excluded_tools=body.get("excluded_tools"),
|
||||
)
|
||||
except AgentNotAccessibleError as exc:
|
||||
raise MafForbiddenError("agent", exc.agent_id) from exc
|
||||
except InvalidExcludedToolsError as exc:
|
||||
raise MafConflictError(
|
||||
f"excluded_tools not allowed for agent {exc.agent_id}: {exc.tools}"
|
||||
) from exc
|
||||
|
||||
for p in participants:
|
||||
aid = p.get("agent_id")
|
||||
if aid:
|
||||
p["capability_snapshot"] = seat_snapshot_for_agent(trusted_snapshot, str(aid))
|
||||
|
||||
session_data: dict[str, Any] = {
|
||||
"user_id": user_id,
|
||||
"title": body.get("title", ""),
|
||||
@@ -146,10 +273,9 @@ class MafRoundtableService:
|
||||
"manager_agent_id": body.get("manager_agent_id"),
|
||||
"max_rounds": body.get("max_rounds") if body.get("max_rounds") is not None else cfg.default_max_rounds,
|
||||
"write_policy": body.get("write_policy") or cfg.default_write_policy,
|
||||
"capability_snapshot": body.get("capability_snapshot"),
|
||||
"capability_snapshot": trusted_snapshot,
|
||||
}
|
||||
session = await self._store.sessions.create_session(session_data)
|
||||
participants = body.get("participants") or []
|
||||
if participants:
|
||||
await self._store.participants.replace_participants(session["id"], participants)
|
||||
return await self.get_session(session_id=session["id"], user_id=user_id, is_admin=is_admin)
|
||||
@@ -287,6 +413,76 @@ class MafRoundtableService:
|
||||
raise MafForbiddenError("run", run_id)
|
||||
raise MafNotFoundError("run", run_id)
|
||||
|
||||
async def start_cancel(self, *, run_id: str, user_id: str | None, is_admin: bool = False) -> dict[str, Any]:
|
||||
"""Phase 1 of two-phase cancel: atomically set run+session to ``cancelling``.
|
||||
|
||||
The caller (router) then calls ``dispatcher.cancel(run_id)`` to
|
||||
cascade to DeerFlow, then calls ``cancel_run`` to finalize to
|
||||
``cancelled``.
|
||||
"""
|
||||
self._require_enabled()
|
||||
if not user_id:
|
||||
raise MafNotFoundError("run", run_id)
|
||||
|
||||
result = await self._store.start_cancel_atomically(run_id=run_id, owner_user_id=user_id)
|
||||
if result is not None:
|
||||
return result
|
||||
|
||||
# Classify the miss.
|
||||
run = await self._store.runs.get_run(run_id)
|
||||
if run is None:
|
||||
raise MafNotFoundError("run", run_id)
|
||||
if is_admin:
|
||||
raise MafForbiddenError("run", run_id)
|
||||
raise MafNotFoundError("run", run_id)
|
||||
|
||||
async def finalize_cancel(self, *, run_id: str, user_id: str | None, is_admin: bool = False) -> dict[str, Any]:
|
||||
"""Phase 2 of two-phase cancel: finalize ``cancelling`` → ``cancelled``."""
|
||||
return await self.cancel_run(run_id=run_id, user_id=user_id, is_admin=is_admin)
|
||||
|
||||
async def mark_cancel_failed(
|
||||
self,
|
||||
*,
|
||||
run_id: str,
|
||||
user_id: str | None,
|
||||
is_admin: bool = False,
|
||||
reason: str = "",
|
||||
) -> dict[str, Any]:
|
||||
"""Mark a cancelling run as ``cancel_failed`` (non-terminal).
|
||||
|
||||
Used when the dispatcher's cancel cascade could not confirm all
|
||||
DeerFlow sub-runs were cancelled. The run AND session both enter
|
||||
``cancel_failed`` atomically so their statuses never diverge.
|
||||
The user can retry cancel later — ``cancel_run_atomically``
|
||||
accepts ``cancel_failed`` as a valid input state.
|
||||
A failed cancel must NEVER masquerade as ``cancelled``.
|
||||
"""
|
||||
self._require_enabled()
|
||||
if not user_id:
|
||||
raise MafNotFoundError("run", run_id)
|
||||
|
||||
scope = self._write_scope_user(user_id, is_admin)
|
||||
run = await self._store.runs.get_run(run_id)
|
||||
if run is None:
|
||||
raise MafNotFoundError("run", run_id)
|
||||
# Owner (or admin) check.
|
||||
session = await self._store.sessions.get_session(run["session_id"], user_id=scope)
|
||||
if session is None:
|
||||
if is_admin and await self._store.sessions.get_session(run["session_id"], user_id=None) is not None:
|
||||
raise MafForbiddenError("run", run_id)
|
||||
raise MafNotFoundError("run", run_id)
|
||||
|
||||
safe_reason = str(sanitize(reason))[:500] if reason else "one or more sub-runs could not be cancelled"
|
||||
updated = await self._store.mark_cancel_failed_atomically(
|
||||
run_id=run_id,
|
||||
owner_user_id=user_id,
|
||||
error_code="CancelCascadeIncomplete",
|
||||
error_message=safe_reason,
|
||||
)
|
||||
if updated is None:
|
||||
raise MafNotFoundError("run", run_id)
|
||||
return updated
|
||||
|
||||
# ── events ─────────────────────────────────────────────────────────────
|
||||
|
||||
async def append_event(
|
||||
@@ -298,6 +494,7 @@ class MafRoundtableService:
|
||||
agent_id: str | None = None,
|
||||
turn_index: int | None = None,
|
||||
payload: dict[str, Any] | None = None,
|
||||
source_event_id: str | None = None,
|
||||
is_admin: bool = False,
|
||||
) -> dict[str, Any]:
|
||||
"""Append an event to a run's stream (internal / executor only).
|
||||
@@ -324,7 +521,8 @@ class MafRoundtableService:
|
||||
event_type=event_type,
|
||||
agent_id=agent_id,
|
||||
turn_index=turn_index,
|
||||
payload=payload,
|
||||
payload=sanitize_payload(payload),
|
||||
source_event_id=source_event_id,
|
||||
)
|
||||
|
||||
async def list_events(
|
||||
|
||||
@@ -0,0 +1,235 @@
|
||||
"""Deterministic post-approval tool executor for the MAF roundtable.
|
||||
|
||||
After a human approves an external-write action, this executor calls the
|
||||
approved DeerFlow tool **directly** with the **decrypted original params** —
|
||||
no model free-will, no re-decision, no raw params in any prompt or checkpoint.
|
||||
|
||||
It is invoked by ``WorkflowRunner.resume()`` instead of re-running an LLM seat
|
||||
turn (which would let the model pick different arguments or a different tool).
|
||||
|
||||
Design — direct tool invocation
|
||||
-------------------------------
|
||||
1. **Atomic occupy** (``approved → running``): only the caller whose
|
||||
conditional UPDATE affects one row wins the right to execute. Concurrent
|
||||
``resume()`` or post-restart replay finds the row already ``running`` or
|
||||
terminal and bails out — at-most-once execution is guaranteed at the DB
|
||||
level, not by locking.
|
||||
2. **Direct tool call**: decrypts approved params (server-only), looks up the
|
||||
tool in DeerFlow's registry, builds a minimal ToolRuntime from the thread's
|
||||
persisted state (sandbox/thread_data), and calls ``tool.func()`` or
|
||||
``tool.ainvoke()`` directly. The LLM is never involved.
|
||||
3. **Authority**: the approved ``action_id`` is carried in the runtime context
|
||||
so the WriteGuard middleware can validate both tool name AND action_id as
|
||||
defense-in-depth (though the LLM is bypassed, so this is purely a secondary
|
||||
check).
|
||||
4. **Outcome recording**: ``succeeded`` / ``failed`` / ``unknown`` are
|
||||
recorded via the state-machine-constrained ``record_terminal_result``
|
||||
(only ``running → terminal``). ``unknown`` prohibits auto-retry.
|
||||
|
||||
Security: the decrypted params are read server-side from the encrypted secret
|
||||
and never leave this process. They do NOT appear in prompts, checkpoints,
|
||||
events, or API responses.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from typing import Any
|
||||
|
||||
from app.maf_roundtable.action_coordinator import ActionCoordinator
|
||||
from app.maf_roundtable.sanitize import sanitize
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class ToolExecutor:
|
||||
"""Executes an approved external-write action deterministically.
|
||||
|
||||
Constructed per-resume from the ``WorkflowRunner``; takes the already-built
|
||||
adapter + coordinator + runtime client so it reuses identity / sandbox /
|
||||
middleware wiring.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
*,
|
||||
adapter: Any,
|
||||
action_coordinator: ActionCoordinator,
|
||||
user_id: str,
|
||||
) -> None:
|
||||
self._adapter = adapter
|
||||
self._coordinator = action_coordinator
|
||||
self._user_id = user_id
|
||||
|
||||
async def execute(
|
||||
self,
|
||||
*,
|
||||
action_id: str,
|
||||
session_id: str,
|
||||
run_id: str,
|
||||
agent_id: str,
|
||||
thread_id: str,
|
||||
approved_tool: str,
|
||||
capability_snapshot: dict[str, Any] | None = None,
|
||||
write_policy: str = "confirm_high_risk",
|
||||
model_name: str | None = None,
|
||||
excluded_tools: list[str] | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Execute the approved tool deterministically and record the outcome.
|
||||
|
||||
Returns::
|
||||
|
||||
{"status": "succeeded"|"failed"|"skipped"|"unknown", ...}
|
||||
|
||||
``skipped`` means another caller already occupied/finished the action
|
||||
(at-most-once) — the caller should return the existing result.
|
||||
|
||||
The approved params are recovered **server-side** from the encrypted
|
||||
action secret *after* the atomic occupy. If the secret is missing or
|
||||
cannot be decrypted, ``ActionSecretUnavailableError`` is raised by the
|
||||
coordinator and turned into a terminal ``failed`` outcome here — the
|
||||
tool is NEVER called with empty params (no ``params or {}`` fallback),
|
||||
so the external side effect happens exactly zero times.
|
||||
|
||||
The actual call is delegated to the harness ``execute_approved_tool``
|
||||
(real ``ToolNode`` / ``ToolRuntime`` / middleware chain), rebuilt from
|
||||
the seat's frozen capability snapshot / model / ``excluded_tools``. The
|
||||
stored action record is passed so the harness can verify run/session/
|
||||
agent/tool consistency before executing.
|
||||
"""
|
||||
# 1. Atomic occupy — only the winner ("claimed") proceeds to execute.
|
||||
# A lost claim reflects the action's ACTUAL state (in_progress /
|
||||
# terminal) rather than a blanket "skip", so the caller can keep the
|
||||
# parent run running while another executor finishes it.
|
||||
from deerflow.persistence.maf_roundtable.actions import (
|
||||
MafActionStateMachineError,
|
||||
)
|
||||
|
||||
try:
|
||||
claim = await self._coordinator.occupy_for_execution(action_id)
|
||||
except MafActionStateMachineError as exc:
|
||||
logger.error(
|
||||
"ToolExecutor: action %s cannot be claimed: %s", action_id, exc,
|
||||
)
|
||||
return {"status": "failed", "error": f"action state machine error: {exc}"}
|
||||
|
||||
if claim != "claimed":
|
||||
existing = await self._coordinator._store.actions.get_action(action_id) # noqa: SLF001
|
||||
if claim == "in_progress":
|
||||
logger.info(
|
||||
"ToolExecutor: action %s already running elsewhere (in_progress)",
|
||||
action_id,
|
||||
)
|
||||
return {"status": "in_progress", "action": existing}
|
||||
logger.info(
|
||||
"ToolExecutor: action %s already terminal (%s) — at-most-once",
|
||||
action_id, claim,
|
||||
)
|
||||
return {"status": claim, "action": existing}
|
||||
|
||||
if not approved_tool:
|
||||
await self._coordinator.record_result(
|
||||
action_id, status="failed",
|
||||
result={"error": "no approved tool name — cannot execute"},
|
||||
)
|
||||
return {"status": "failed", "error": "no approved tool name"}
|
||||
|
||||
# 2. Recover the approved params from the server-only encrypted secret.
|
||||
# A missing/undecryptable/invalid secret is a HARD failure: record
|
||||
# the action failed and never invoke the tool (execution count == 0).
|
||||
from app.maf_roundtable.action_coordinator import ActionSecretUnavailableError
|
||||
|
||||
try:
|
||||
params = await self._coordinator.get_approved_action_params(action_id)
|
||||
except ActionSecretUnavailableError as exc:
|
||||
safe_msg = str(sanitize(exc.detail))[:500]
|
||||
logger.error(
|
||||
"ToolExecutor: action %s params unavailable (%s): %s",
|
||||
action_id, exc.reason, safe_msg,
|
||||
)
|
||||
await self._coordinator.record_result(
|
||||
action_id, status="failed",
|
||||
result={"error": f"action secret unavailable: {exc.reason}"},
|
||||
)
|
||||
return {"status": "failed", "error": safe_msg}
|
||||
|
||||
# 3. Read the stored action record (authoritative turn_index + the
|
||||
# run/session/agent/tool the harness will verify against).
|
||||
action_record = await self._coordinator._store.actions.get_action(action_id) # noqa: SLF001
|
||||
turn_index = int((action_record or {}).get("turn_index") or 0)
|
||||
|
||||
# 4. Execute via the real DeerFlow tool path — no LLM, no prompt
|
||||
# injection. The raw params are read from the encrypted secret and
|
||||
# passed straight to the tool; they never enter any model context.
|
||||
from app.maf_roundtable.runtime_client import ExecutionPrincipal
|
||||
|
||||
principal = ExecutionPrincipal(
|
||||
user_id=self._user_id,
|
||||
session_id=session_id,
|
||||
run_id=run_id,
|
||||
)
|
||||
client = self._adapter._client # noqa: SLF001 — DeerFlowRuntimeClient
|
||||
|
||||
try:
|
||||
outcome = await client.execute_tool_directly(
|
||||
thread_id=thread_id,
|
||||
agent_id=agent_id,
|
||||
tool_name=approved_tool,
|
||||
params=params,
|
||||
principal=principal,
|
||||
turn_index=turn_index,
|
||||
capability_snapshot=capability_snapshot,
|
||||
write_policy=write_policy,
|
||||
model_name=model_name,
|
||||
excluded_tools=excluded_tools,
|
||||
approved_action_id=action_id,
|
||||
action_record=action_record,
|
||||
)
|
||||
except Exception as exc:
|
||||
safe_msg = str(sanitize(str(exc)))[:500]
|
||||
logger.error(
|
||||
"ToolExecutor: direct tool call '%s' raised: %s",
|
||||
approved_tool, safe_msg,
|
||||
)
|
||||
await self._coordinator.record_result(
|
||||
action_id, status="failed", result={"error": safe_msg},
|
||||
)
|
||||
return {"status": "failed", "error": safe_msg}
|
||||
|
||||
# 5. Record terminal result (state-machine constrained: only
|
||||
# running → terminal; a lost race is a no-op).
|
||||
outcome_status = outcome.get("status")
|
||||
if outcome_status == "succeeded":
|
||||
await self._coordinator.record_result(
|
||||
action_id, status="succeeded",
|
||||
result={"tool_result": outcome.get("result")},
|
||||
)
|
||||
return {"status": "succeeded", "tool_result": outcome.get("result")}
|
||||
elif outcome_status == "unknown":
|
||||
# Inconclusive external result (timeout / disconnect / gateway):
|
||||
# record ``unknown`` — never auto-retry, a human must reconcile.
|
||||
error = outcome.get("error", "inconclusive external result")
|
||||
await self._coordinator.record_result(
|
||||
action_id, status="unknown", result={"error": error},
|
||||
)
|
||||
return {"status": "unknown", "error": error}
|
||||
else:
|
||||
error = outcome.get("error", "tool execution failed")
|
||||
await self._coordinator.record_result(
|
||||
action_id, status="failed", result={"error": error},
|
||||
)
|
||||
return {"status": "failed", "error": error}
|
||||
|
||||
async def record_unknown(self, action_id: str, *, reason: str) -> None:
|
||||
"""Record an ``unknown`` outcome (network timeout / inconclusive).
|
||||
|
||||
``unknown`` prohibits auto-retry — the action stays in ``unknown``
|
||||
until a human reconciles it.
|
||||
"""
|
||||
logger.warning(
|
||||
"ToolExecutor: action %s outcome unknown — %s (no auto-retry)",
|
||||
action_id, reason,
|
||||
)
|
||||
await self._coordinator.record_result(
|
||||
action_id, status="unknown", result={"reason": reason},
|
||||
)
|
||||
@@ -0,0 +1,606 @@
|
||||
"""MAF Workflow node executors for the roundtable experiment.
|
||||
|
||||
Each executor is a real MAF ``Executor`` subclass instance. Every seat gets
|
||||
its own executor bound to a fixed ``agent_id`` — no shared function that
|
||||
guesses the current speaker from input metadata.
|
||||
|
||||
Executors delegate to ``DeerFlowAgentAdapter.run_seat_turn()`` for actual
|
||||
model/tool execution and emit MAF events via the adapter.
|
||||
|
||||
Nodes:
|
||||
- CoordinatorExecutor: decides which seat speaks next, whether to continue.
|
||||
- SeatExecutor (one per seat): runs one seat turn via DeerFlowAgentAdapter.
|
||||
- ApprovalGateExecutor: pauses for external-write approval before proceeding.
|
||||
- FinalizerExecutor: generates the final synthesis and ends the run.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from typing import Any
|
||||
|
||||
from agent_framework import Executor, WorkflowContext, handler
|
||||
|
||||
from app.maf_roundtable.action_coordinator import (
|
||||
ActionCoordinator,
|
||||
classify_tool,
|
||||
tool_needs_approval,
|
||||
)
|
||||
from app.maf_roundtable.context_builder import build_manager_synthesis_input
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class WriteGuardConfigurationError(RuntimeError):
|
||||
"""Raised when WriteGuard should have intercepted a write tool but didn't.
|
||||
|
||||
Indicates write_guard is misconfigured (not enabled or provider missing)
|
||||
while a MAF run requires approval. The run is failed — we never fall back
|
||||
to creating generic post-hoc approval records.
|
||||
"""
|
||||
|
||||
|
||||
# ── Serializable workflow state ─────────────────────────────────────────────
|
||||
|
||||
|
||||
class RoundtableState:
|
||||
"""Serializable shared state for the MAF roundtable workflow.
|
||||
|
||||
Persisted to the run's ``maf_checkpoint_json`` so the workflow survives
|
||||
restarts and approval-pause/resume cycles.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
*,
|
||||
session_id: str,
|
||||
run_id: str,
|
||||
task_text: str,
|
||||
mode: str,
|
||||
model_name: str | None,
|
||||
reasoning_effort: str | None,
|
||||
max_rounds: int,
|
||||
write_policy: str,
|
||||
manager_agent_id: str | None,
|
||||
seat_agent_ids: list[str],
|
||||
thread_map: dict[str, str],
|
||||
capability_snapshot: dict[str, Any] | None = None,
|
||||
) -> None:
|
||||
self.session_id = session_id
|
||||
self.run_id = run_id
|
||||
self.task_text = task_text
|
||||
self.mode = mode
|
||||
self.model_name = model_name
|
||||
self.reasoning_effort = reasoning_effort
|
||||
self.max_rounds = max_rounds
|
||||
self.write_policy = write_policy
|
||||
self.manager_agent_id = manager_agent_id
|
||||
self.seat_agent_ids = seat_agent_ids
|
||||
self.thread_map = thread_map
|
||||
self.capability_snapshot = capability_snapshot
|
||||
|
||||
self.current_round = 0
|
||||
self.turn_results: list[dict[str, Any]] = []
|
||||
self.fact_ledger: dict[str, Any] = {
|
||||
"confirmed_facts": [],
|
||||
"tool_results": [],
|
||||
"conflicts": [],
|
||||
"pending_actions": [],
|
||||
}
|
||||
self.final_result: dict[str, Any] | None = None
|
||||
self.status = "running"
|
||||
self.pending_approvals: list[dict[str, Any]] = []
|
||||
|
||||
def to_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"session_id": self.session_id,
|
||||
"run_id": self.run_id,
|
||||
"task_text": self.task_text,
|
||||
"mode": self.mode,
|
||||
"model_name": self.model_name,
|
||||
"reasoning_effort": self.reasoning_effort,
|
||||
"max_rounds": self.max_rounds,
|
||||
"write_policy": self.write_policy,
|
||||
"manager_agent_id": self.manager_agent_id,
|
||||
"seat_agent_ids": self.seat_agent_ids,
|
||||
"thread_map": self.thread_map,
|
||||
"capability_snapshot": self.capability_snapshot,
|
||||
"current_round": self.current_round,
|
||||
"turn_results": self.turn_results,
|
||||
"fact_ledger": self.fact_ledger,
|
||||
"final_result": self.final_result,
|
||||
"status": self.status,
|
||||
"pending_approvals": self.pending_approvals,
|
||||
}
|
||||
|
||||
@classmethod
|
||||
def from_dict(cls, d: dict[str, Any]) -> RoundtableState:
|
||||
state = cls(
|
||||
session_id=d["session_id"],
|
||||
run_id=d["run_id"],
|
||||
task_text=d["task_text"],
|
||||
mode=d["mode"],
|
||||
model_name=d.get("model_name"),
|
||||
reasoning_effort=d.get("reasoning_effort"),
|
||||
max_rounds=d.get("max_rounds", 8),
|
||||
write_policy=d.get("write_policy", "confirm_high_risk"),
|
||||
manager_agent_id=d.get("manager_agent_id"),
|
||||
seat_agent_ids=d.get("seat_agent_ids", []),
|
||||
thread_map=d.get("thread_map", {}),
|
||||
capability_snapshot=d.get("capability_snapshot"),
|
||||
)
|
||||
state.current_round = d.get("current_round", 0)
|
||||
state.turn_results = d.get("turn_results", [])
|
||||
state.fact_ledger = d.get("fact_ledger", state.fact_ledger)
|
||||
state.final_result = d.get("final_result")
|
||||
state.status = d.get("status", "running")
|
||||
state.pending_approvals = d.get("pending_approvals", []) or d.get("pending_approval") and [d["pending_approval"]] or []
|
||||
return state
|
||||
|
||||
|
||||
# ── Coordinator executor ────────────────────────────────────────────────────
|
||||
|
||||
|
||||
class CoordinatorExecutor(Executor):
|
||||
"""Decides which seat speaks next, whether to continue or finish."""
|
||||
|
||||
def __init__(self, adapter: Any, state: RoundtableState) -> None:
|
||||
super().__init__(id="coordinator")
|
||||
self._adapter = adapter
|
||||
self._state = state
|
||||
|
||||
@handler(input=Any, output=dict)
|
||||
async def handle(self, message: Any, ctx: WorkflowContext) -> None:
|
||||
self._state.current_round += 1
|
||||
|
||||
if self._state.current_round > self._state.max_rounds:
|
||||
await ctx.send_message({"decision": "done", "reason": "max_rounds_reached"})
|
||||
return
|
||||
|
||||
if self._state.mode == "structured":
|
||||
if self._state.current_round == 1:
|
||||
await ctx.send_message({"decision": "parallel_seats", "agents": self._state.seat_agent_ids})
|
||||
return
|
||||
await ctx.send_message({"decision": "done", "reason": "structured_complete"})
|
||||
return
|
||||
|
||||
# group_chat: round-robin speaker selection
|
||||
remaining = [
|
||||
a for a in self._state.seat_agent_ids
|
||||
if not any(
|
||||
r.get("agent_id") == a and r.get("turn_index", 0) >= self._state.current_round - 1
|
||||
for r in self._state.turn_results
|
||||
)
|
||||
]
|
||||
if not remaining:
|
||||
await ctx.send_message({"decision": "done", "reason": "all_seats_spoke"})
|
||||
return
|
||||
|
||||
next_agent = remaining[(self._state.current_round - 1) % len(remaining)]
|
||||
await self._adapter._emit_critical(self._state.run_id, {
|
||||
"event_type": "manager.decision",
|
||||
"agent_id": self._state.manager_agent_id or "coordinator",
|
||||
"turn_index": self._state.current_round,
|
||||
"payload": {"next_speaker": next_agent, "reason": "round_robin", "round": self._state.current_round},
|
||||
})
|
||||
await ctx.send_message({"decision": "next_speaker", "agent_id": next_agent})
|
||||
|
||||
|
||||
# ── Seat executor (one instance per seat) ───────────────────────────────────
|
||||
|
||||
|
||||
class SeatExecutor(Executor):
|
||||
"""Runs one seat turn via DeerFlowAgentAdapter.
|
||||
|
||||
Each instance is bound to a fixed ``agent_id`` — the MAF workflow routes
|
||||
to the correct seat executor by edge, not by guessing from input.
|
||||
|
||||
Phase-2 fix: write tools are NO LONGER excluded from the seat run. The
|
||||
WriteGuard middleware (harness layer) intercepts them at execution time
|
||||
via ``wrap_tool_call``/``awrap_tool_call`` when the run context carries a
|
||||
``maf_run_id`` flag. The model therefore SEES the write-tool schema and
|
||||
can propose the call, but the real tool never executes before approval.
|
||||
``excluded_tools`` now only contains tools the user explicitly disabled
|
||||
(from the capability snapshot). The post-turn capture is retained solely
|
||||
to surface the intercepted calls in the run state / pending approval.
|
||||
"""
|
||||
|
||||
def __init__(self, adapter: Any, state: RoundtableState, agent_id: str, *, action_coordinator: ActionCoordinator | None = None) -> None:
|
||||
super().__init__(id=f"seat_{agent_id}")
|
||||
self._adapter = adapter
|
||||
self._state = state
|
||||
self._agent_id = agent_id
|
||||
self._action_coordinator = action_coordinator
|
||||
|
||||
@handler(input=Any, output=dict)
|
||||
async def handle(self, message: Any, ctx: WorkflowContext) -> None:
|
||||
thread_id = self._state.thread_map.get(self._agent_id, "")
|
||||
if not thread_id:
|
||||
await ctx.send_message({"error": f"no thread for agent {self._agent_id}", "agent_id": self._agent_id})
|
||||
return
|
||||
|
||||
prior_turns = [
|
||||
{"agent_id": r["agent_id"], "turn_index": r["turn_index"], "summary": r.get("content", "")[:500]}
|
||||
for r in self._state.turn_results
|
||||
]
|
||||
|
||||
# Read ALL capabilities from the frozen snapshot — never default-disable.
|
||||
caps = _agent_capabilities_from_snapshot(self._state.capability_snapshot, self._agent_id)
|
||||
|
||||
# Phase-2: excluded_tools contains ONLY user-disabled tools. Write tools
|
||||
# that need approval are no longer excluded — the WriteGuard middleware
|
||||
# intercepts them at execution time so the model still sees the schema.
|
||||
excluded = list(caps.get("excluded_tools", []))
|
||||
|
||||
response = await self._adapter.run_seat_turn(
|
||||
session_id=self._state.session_id,
|
||||
run_id=self._state.run_id,
|
||||
agent_id=self._agent_id,
|
||||
turn_index=self._state.current_round,
|
||||
message=self._state.task_text,
|
||||
thread_id=thread_id,
|
||||
model_name=caps.get("model_name") or self._state.model_name,
|
||||
reasoning_effort=caps.get("reasoning_effort") or self._state.reasoning_effort,
|
||||
thinking_enabled=caps.get("thinking_enabled", True),
|
||||
subagent_enabled=caps.get("subagent_enabled", False),
|
||||
task_text=self._state.task_text,
|
||||
stage_instruction=f"第{self._state.current_round}轮分析",
|
||||
prior_turns=prior_turns,
|
||||
fact_ledger=self._state.fact_ledger,
|
||||
excluded_tools=excluded,
|
||||
memory_recall_disabled=caps.get("memory_recall_disabled"),
|
||||
memory_injection_enabled=caps.get("memory_injection_enabled"),
|
||||
capability_snapshot=self._state.capability_snapshot,
|
||||
write_policy=self._state.write_policy,
|
||||
)
|
||||
|
||||
# Phase-2: the WriteGuard middleware already created pending actions for
|
||||
# intercepted write tools during the run (inside DeerFlow). We now read
|
||||
# the waiting_approval actions that match THIS agent + THIS turn to
|
||||
# surface the pending approval in the workflow state so the ApprovalGate
|
||||
# can pause. No action creation here.
|
||||
if response.tool_calls and self._state.write_policy != "auto":
|
||||
pending_calls = [
|
||||
tc for tc in response.tool_calls
|
||||
if tc.get("name") and tool_needs_approval(
|
||||
tc.get("name"), self._state.write_policy,
|
||||
self._state.capability_snapshot, self._agent_id,
|
||||
)
|
||||
]
|
||||
if pending_calls:
|
||||
all_actions = await self._store.actions.list_actions(
|
||||
run_id=self._state.run_id, status="waiting_approval"
|
||||
)
|
||||
# P1-5/P1b: candidate actions are scoped to this run + agent +
|
||||
# THIS turn (never an earlier turn's waiting actions).
|
||||
turn_actions = [
|
||||
a for a in all_actions
|
||||
if a.get("agent_id") == self._agent_id
|
||||
and a.get("turn_index") == self._state.current_round
|
||||
]
|
||||
# Every pending tool call must match EXACTLY one action, by
|
||||
# tool_call_id (logical_action_id); fall back to tool_name only
|
||||
# when the call carries no id. Any count/ID mismatch is a hard
|
||||
# failure — we never guess which action a call maps to.
|
||||
matched: list[dict[str, Any]] = []
|
||||
for tc in pending_calls:
|
||||
tc_id = tc.get("id") or ""
|
||||
tc_name = tc.get("name", "")
|
||||
if tc_id:
|
||||
hits = [
|
||||
a for a in turn_actions
|
||||
if (a.get("logical_action_id") or "") == tc_id
|
||||
]
|
||||
else:
|
||||
hits = [
|
||||
a for a in turn_actions
|
||||
if a.get("tool_name") == tc_name
|
||||
and not a.get("logical_action_id")
|
||||
]
|
||||
if len(hits) != 1:
|
||||
raise RuntimeError(
|
||||
f"seat {self._agent_id} turn {self._state.current_round}: "
|
||||
f"pending tool call '{tc_name}' (id={tc_id or '<none>'}) matched "
|
||||
f"{len(hits)} waiting actions (expected exactly 1) — refusing to guess"
|
||||
)
|
||||
matched.append(hits[0])
|
||||
|
||||
self._state.pending_approvals = [
|
||||
{
|
||||
"action_id": a["id"],
|
||||
"approval_id": a.get("approval_id", ""),
|
||||
"agent_id": self._agent_id,
|
||||
"tool_name": a.get("tool_name", ""),
|
||||
"turn_index": self._state.current_round,
|
||||
}
|
||||
for a in matched
|
||||
]
|
||||
|
||||
self._state.turn_results.append({
|
||||
"agent_id": self._agent_id,
|
||||
"turn_index": self._state.current_round,
|
||||
"content": response.content,
|
||||
"tool_calls": response.tool_calls,
|
||||
"error": response.error,
|
||||
"usage": response.usage,
|
||||
})
|
||||
|
||||
if response.tool_calls:
|
||||
for tc in response.tool_calls:
|
||||
tc_name = tc.get("name", "")
|
||||
is_intercepted = any(
|
||||
a.get("tool_name") == tc_name
|
||||
for a in (self._state.pending_approvals or [])
|
||||
)
|
||||
self._state.fact_ledger["tool_results"].append({
|
||||
"tool_name": tc_name,
|
||||
"status": "waiting_approval" if is_intercepted else "completed",
|
||||
"agent_id": self._agent_id,
|
||||
})
|
||||
|
||||
# SDK/API errors must fail the run, never silently complete.
|
||||
if response.error:
|
||||
raise RuntimeError(
|
||||
f"seat {self._agent_id} turn {self._state.current_round} failed: {response.error}"
|
||||
)
|
||||
|
||||
await ctx.send_message({"agent_id": self._agent_id, "content": response.content, "error": response.error})
|
||||
|
||||
@property
|
||||
def _store(self) -> Any:
|
||||
return self._adapter._service.store
|
||||
|
||||
def _pending_write_calls(self, tool_calls: list[dict[str, Any]]) -> list[str]:
|
||||
"""Return the names of write tool calls that the policy requires approval for."""
|
||||
names: list[str] = []
|
||||
for tc in tool_calls:
|
||||
name = tc.get("name", "")
|
||||
if name and tool_needs_approval(
|
||||
name, self._state.write_policy, self._state.capability_snapshot, self._agent_id
|
||||
):
|
||||
names.append(name)
|
||||
return names
|
||||
|
||||
|
||||
# ── Approval gate executor ──────────────────────────────────────────────────
|
||||
|
||||
|
||||
class ApprovalGateExecutor(Executor):
|
||||
"""Pauses for external-write approval before proceeding.
|
||||
|
||||
When the write policy requires approval and a seat produced external write
|
||||
tool calls, this executor:
|
||||
1. Reads the pending approvals already created by WriteGuard (zero or more).
|
||||
2. If none exist but the policy requires approval for detected write tools:
|
||||
raises ``WriteGuardConfigurationError`` — the WriteGuard middleware
|
||||
should have intercepted and recorded them. We NEVER fall back to
|
||||
creating generic post-hoc actions.
|
||||
3. Emits ``action.waiting_approval`` events.
|
||||
4. Sets the run status to ``waiting_approval``.
|
||||
|
||||
On resume (after user approves), the workflow re-enters and this executor
|
||||
checks the approval statuses. When all are decided, it routes to the
|
||||
finalizer.
|
||||
"""
|
||||
|
||||
def __init__(self, adapter: Any, state: RoundtableState, service: Any) -> None:
|
||||
super().__init__(id="approval_gate")
|
||||
self._adapter = adapter
|
||||
self._state = state
|
||||
self._service = service
|
||||
|
||||
@handler(input=Any, output=dict)
|
||||
async def handle(self, message: Any, ctx: WorkflowContext) -> None:
|
||||
# Check if we're resuming from a previous approval pause.
|
||||
if self._state.pending_approvals:
|
||||
all_decided = True
|
||||
for pa in self._state.pending_approvals:
|
||||
approval_id = pa.get("approval_id", "")
|
||||
approval = await self._service.store.approvals.get_approval(approval_id)
|
||||
if approval is None or approval["status"] == "pending":
|
||||
all_decided = False
|
||||
continue
|
||||
if approval["status"] == "approved":
|
||||
from app.maf_roundtable.event_normalizer import make_action_approved
|
||||
await self._adapter._emit_critical(self._state.run_id, make_action_approved(
|
||||
pa.get("agent_id", ""),
|
||||
self._state.current_round,
|
||||
action_id=pa.get("action_id", ""),
|
||||
approval_id=approval_id,
|
||||
decided_by=approval.get("decided_by", ""),
|
||||
))
|
||||
elif approval["status"] == "rejected":
|
||||
from app.maf_roundtable.event_normalizer import make_action_rejected
|
||||
await self._adapter._emit_critical(self._state.run_id, make_action_rejected(
|
||||
pa.get("agent_id", ""),
|
||||
self._state.current_round,
|
||||
action_id=pa.get("action_id", ""),
|
||||
approval_id=approval_id,
|
||||
decided_by=approval.get("decided_by", ""),
|
||||
))
|
||||
|
||||
if all_decided:
|
||||
self._state.pending_approvals = []
|
||||
await ctx.send_message({"decision": "approved"})
|
||||
return
|
||||
|
||||
# Still pending — stay in waiting state.
|
||||
await ctx.send_message({"decision": "waiting_approval"})
|
||||
return
|
||||
|
||||
# First entry: check if any seat produced write tool calls needing approval.
|
||||
needs_approval = self._check_needs_approval()
|
||||
if not needs_approval:
|
||||
await ctx.send_message({"decision": "approved", "policy": self._state.write_policy})
|
||||
return
|
||||
|
||||
# P0-4: WriteGuard should already have created pending actions for every
|
||||
# tool that needs approval. If we detect write tools that need approval
|
||||
# but NO pending_approvals were set by the SeatExecutor, the WriteGuard
|
||||
# middleware is misconfigured — fail the run rather than silently
|
||||
# bypassing approval.
|
||||
if not self._state.pending_approvals:
|
||||
raise WriteGuardConfigurationError(
|
||||
f"Write policy '{self._state.write_policy}' requires approval "
|
||||
f"for detected write tools, but WriteGuard did not create any "
|
||||
f"pending actions. Check that write_guard.enabled is true and "
|
||||
f"the provider is configured in config.yaml."
|
||||
)
|
||||
|
||||
# Update run status to waiting_approval.
|
||||
await self._service.store.runs.update_run(self._state.run_id, {"status": "waiting_approval"})
|
||||
await self._service.store.sessions.update_session(
|
||||
self._state.session_id, user_id=self._adapter._user_id, fields={"status": "waiting_approval"}
|
||||
)
|
||||
|
||||
await ctx.send_message({"decision": "waiting_approval"})
|
||||
|
||||
def _check_needs_approval(self) -> bool:
|
||||
"""Check if the write policy requires approval for any pending tool calls.
|
||||
|
||||
P1: uses metadata-driven classification from the capability snapshot,
|
||||
not name-prefix heuristics. Tools without metadata use a safe default
|
||||
(requires approval).
|
||||
"""
|
||||
if self._state.write_policy == "auto":
|
||||
return False
|
||||
for result in self._state.turn_results:
|
||||
for tc in result.get("tool_calls") or []:
|
||||
name = tc.get("name", "")
|
||||
if not name:
|
||||
continue
|
||||
if tool_needs_approval(name, self._state.write_policy, self._state.capability_snapshot):
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
# ── Finalizer executor ──────────────────────────────────────────────────────
|
||||
|
||||
|
||||
async def generate_final_report(adapter: Any, state: RoundtableState) -> dict[str, Any]:
|
||||
"""Run the manager synthesis (the MAF finalizer path) and set ``state.final_result``.
|
||||
|
||||
Shared by the in-graph ``FinalizerExecutor`` and ``WorkflowRunner.resume`` so
|
||||
that a run which paused for approval still gets a real synthesized report
|
||||
after its approved actions execute — resume must re-enter the finalizer
|
||||
path, not merely flip ``state.status`` to ``completed``.
|
||||
"""
|
||||
from app.maf_roundtable.event_normalizer import make_run_completed
|
||||
|
||||
manager_id = state.manager_agent_id or "coordinator"
|
||||
thread_id = state.thread_map.get(manager_id, "")
|
||||
|
||||
synthesis_input = build_manager_synthesis_input(
|
||||
task_text=state.task_text,
|
||||
seat_results=state.turn_results,
|
||||
fact_ledger=state.fact_ledger,
|
||||
)
|
||||
|
||||
if thread_id:
|
||||
response = await adapter.run_seat_turn(
|
||||
session_id=state.session_id,
|
||||
run_id=state.run_id,
|
||||
agent_id=manager_id,
|
||||
turn_index=state.current_round + 1,
|
||||
message=synthesis_input,
|
||||
thread_id=thread_id,
|
||||
model_name=state.model_name,
|
||||
reasoning_effort=state.reasoning_effort,
|
||||
task_text=synthesis_input,
|
||||
stage_instruction="综合所有席位分析,生成最终结论",
|
||||
)
|
||||
state.final_result = {"content": response.content, "agent_id": manager_id}
|
||||
else:
|
||||
state.final_result = {"content": synthesis_input, "agent_id": manager_id, "note": "no_manager_thread"}
|
||||
|
||||
await adapter._emit_critical(state.run_id, make_run_completed(manager_id, state.current_round + 1, {
|
||||
"total_rounds": state.current_round,
|
||||
"seats_completed": len(state.turn_results),
|
||||
}))
|
||||
return state.final_result
|
||||
|
||||
|
||||
class FinalizerExecutor(Executor):
|
||||
"""Generates the final synthesis and ends the run."""
|
||||
|
||||
def __init__(self, adapter: Any, state: RoundtableState) -> None:
|
||||
super().__init__(id="finalizer")
|
||||
self._adapter = adapter
|
||||
self._state = state
|
||||
|
||||
@handler(input=Any, workflow_output=dict)
|
||||
async def handle(self, message: Any, ctx: WorkflowContext) -> None:
|
||||
await generate_final_report(self._adapter, self._state)
|
||||
self._state.status = "completed"
|
||||
await ctx.yield_output({"final_result": self._state.final_result})
|
||||
|
||||
|
||||
# ── Waiting terminal executor ───────────────────────────────────────────────
|
||||
|
||||
|
||||
class WaitingTerminalExecutor(Executor):
|
||||
"""Terminal executor for the approval-waiting path.
|
||||
|
||||
When the approval gate routes here, the workflow stops. The run stays in
|
||||
``waiting_approval`` until the user decides, at which point the service
|
||||
resumes the workflow from its checkpoint.
|
||||
"""
|
||||
|
||||
def __init__(self) -> None:
|
||||
super().__init__(id="waiting_terminal")
|
||||
|
||||
@handler(input=Any, workflow_output=dict)
|
||||
async def handle(self, message: Any, ctx: WorkflowContext) -> None:
|
||||
await ctx.yield_output({"status": "waiting_approval"})
|
||||
|
||||
|
||||
# ── helpers ─────────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def _excluded_tools_from_snapshot(snapshot: dict[str, Any] | None, agent_id: str) -> list[str]:
|
||||
"""Extract excluded_tools from the frozen capability snapshot for an agent."""
|
||||
caps = _agent_capabilities_from_snapshot(snapshot, agent_id)
|
||||
return caps.get("excluded_tools", [])
|
||||
|
||||
|
||||
def _agent_capabilities_from_snapshot(snapshot: dict[str, Any] | None, agent_id: str) -> dict[str, Any]:
|
||||
"""Extract ALL capabilities from the frozen snapshot for an agent.
|
||||
|
||||
Returns a dict with keys: model_name, reasoning_effort, thinking_enabled,
|
||||
subagent_enabled, excluded_tools, memory_recall_disabled,
|
||||
memory_injection_enabled, write_policy. Missing keys default to
|
||||
permissive values (tools/skills/memory NOT disabled by default).
|
||||
"""
|
||||
if not snapshot:
|
||||
return {}
|
||||
agents = snapshot.get("agents")
|
||||
if not isinstance(agents, list):
|
||||
return {}
|
||||
for a in agents:
|
||||
if isinstance(a, dict) and a.get("agent_id") == agent_id:
|
||||
return {
|
||||
"model_name": a.get("model_name"),
|
||||
"reasoning_effort": a.get("reasoning_effort"),
|
||||
"thinking_enabled": a.get("thinking_enabled", True),
|
||||
"subagent_enabled": a.get("subagent_enabled", False),
|
||||
"excluded_tools": a.get("excluded_tools") or [],
|
||||
"memory_recall_disabled": a.get("memory_recall_disabled"),
|
||||
"memory_injection_enabled": a.get("memory_injection_enabled"),
|
||||
"write_policy": a.get("write_policy"),
|
||||
}
|
||||
return {}
|
||||
|
||||
|
||||
def _is_high_risk_tool(tool_name: str, snapshot: dict[str, Any] | None = None) -> bool:
|
||||
"""Determine if a tool is high-risk using capability snapshot metadata.
|
||||
|
||||
P1 fix: no longer guesses risk from name prefixes (``create_`` /
|
||||
``delete_`` etc.). Instead, reads the per-tool ``side_effect`` and
|
||||
``risk_level`` from the frozen capability snapshot. Tools without
|
||||
metadata use a **safe default** (R3 write → high-risk → requires approval).
|
||||
"""
|
||||
side_effect, risk_level = classify_tool(tool_name, snapshot)
|
||||
if side_effect in ("read", "skill"):
|
||||
return False
|
||||
risk_order = {"R0": 0, "R1": 1, "R2": 2, "R3": 3, "R4": 4}
|
||||
return risk_order.get(risk_level, 3) >= 3
|
||||
@@ -0,0 +1,139 @@
|
||||
"""MAF WorkflowBuilder graph construction for the roundtable experiment.
|
||||
|
||||
Creates real MAF Workflow graphs using the official SDK's WorkflowBuilder.
|
||||
The SDK is imported lazily so the Gateway starts without it when the feature
|
||||
flag is off.
|
||||
|
||||
Two topologies:
|
||||
- ``structured``: coordinator → parallel seats → approval gate → finalizer
|
||||
- ``group_chat``: coordinator loop (dynamic speaker selection) → finalizer
|
||||
|
||||
Each node is a real MAF ``Executor`` subclass instance (from
|
||||
``workflow_executors.py``). The builder uses the SDK's actual API:
|
||||
``WorkflowBuilder(start_executor=...)``, ``add_edge``, ``add_fan_out_edges``,
|
||||
``add_fan_in_edges``, ``add_switch_case_edge_group``, ``build()``.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from typing import Any
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def build_structured_workflow(
|
||||
*,
|
||||
coordinator: Any,
|
||||
seat_executors: list[Any],
|
||||
approval_gate: Any,
|
||||
finalizer: Any,
|
||||
waiting_terminal: Any,
|
||||
) -> Any:
|
||||
"""Build a structured (fixed-topology) MAF Workflow.
|
||||
|
||||
Topology: coordinator → parallel seat executors → approval gate → finalizer.
|
||||
The approval gate conditionally routes to waiting_terminal (pause) or finalizer.
|
||||
"""
|
||||
from agent_framework import Case, Default, WorkflowBuilder
|
||||
|
||||
builder = WorkflowBuilder(
|
||||
start_executor=coordinator,
|
||||
name="maf-structured-roundtable",
|
||||
output_from=[finalizer, waiting_terminal],
|
||||
)
|
||||
|
||||
# coordinator → seats → approval gate. Handle 0/1/≥2 seats since the SDK's
|
||||
# FanOut/FanIn edge groups require at least two members.
|
||||
if len(seat_executors) >= 2:
|
||||
builder.add_fan_out_edges(coordinator, seat_executors)
|
||||
builder.add_fan_in_edges(seat_executors, approval_gate)
|
||||
elif len(seat_executors) == 1:
|
||||
builder.add_edge(coordinator, seat_executors[0])
|
||||
builder.add_edge(seat_executors[0], approval_gate)
|
||||
else:
|
||||
# No seats — coordinator feeds the approval gate directly.
|
||||
builder.add_edge(coordinator, approval_gate)
|
||||
|
||||
# approval gate → conditional: approved → finalizer, waiting → waiting_terminal
|
||||
builder.add_switch_case_edge_group(approval_gate, [
|
||||
Case(condition=lambda out: isinstance(out, dict) and out.get("decision") == "waiting_approval", target=waiting_terminal),
|
||||
Default(target=finalizer),
|
||||
])
|
||||
|
||||
return builder.build()
|
||||
|
||||
|
||||
def build_group_chat_workflow(
|
||||
*,
|
||||
coordinator: Any,
|
||||
seat_executors: list[Any],
|
||||
approval_gate: Any,
|
||||
finalizer: Any,
|
||||
waiting_terminal: Any,
|
||||
seat_agent_ids: list[str],
|
||||
) -> Any:
|
||||
"""Build a dynamic group-chat MAF Workflow.
|
||||
|
||||
The coordinator selects the next speaker each round via switch-case edges.
|
||||
Loop terminates on: coordinator signals completion, max_rounds reached.
|
||||
"""
|
||||
from agent_framework import Case, Default, WorkflowBuilder
|
||||
|
||||
builder = WorkflowBuilder(
|
||||
start_executor=coordinator,
|
||||
name="maf-groupchat-roundtable",
|
||||
output_from=[finalizer, waiting_terminal],
|
||||
)
|
||||
|
||||
# coordinator → switch-case: route to the selected seat, or to approval gate
|
||||
cases = []
|
||||
for i, agent_id in enumerate(seat_agent_ids):
|
||||
cases.append(Case(
|
||||
condition=lambda out, aid=agent_id: isinstance(out, dict) and out.get("agent_id") == aid,
|
||||
target=seat_executors[i],
|
||||
))
|
||||
# Default: coordinator said "done" → go to approval gate
|
||||
cases.append(Default(target=approval_gate))
|
||||
builder.add_switch_case_edge_group(coordinator, cases)
|
||||
|
||||
# each seat → back to coordinator (loop)
|
||||
for seat_exec in seat_executors:
|
||||
builder.add_edge(seat_exec, coordinator)
|
||||
|
||||
# approval gate → conditional: waiting → waiting_terminal, else → finalizer
|
||||
builder.add_switch_case_edge_group(approval_gate, [
|
||||
Case(condition=lambda out: isinstance(out, dict) and out.get("decision") == "waiting_approval", target=waiting_terminal),
|
||||
Default(target=finalizer),
|
||||
])
|
||||
|
||||
return builder.build()
|
||||
|
||||
|
||||
def create_workflow(
|
||||
*,
|
||||
mode: str,
|
||||
coordinator: Any,
|
||||
seat_executors: list[Any],
|
||||
approval_gate: Any,
|
||||
finalizer: Any,
|
||||
waiting_terminal: Any,
|
||||
seat_agent_ids: list[str],
|
||||
) -> Any:
|
||||
"""Factory: create the appropriate workflow for the given mode."""
|
||||
if mode == "group_chat":
|
||||
return build_group_chat_workflow(
|
||||
coordinator=coordinator,
|
||||
seat_executors=seat_executors,
|
||||
approval_gate=approval_gate,
|
||||
finalizer=finalizer,
|
||||
waiting_terminal=waiting_terminal,
|
||||
seat_agent_ids=seat_agent_ids,
|
||||
)
|
||||
return build_structured_workflow(
|
||||
coordinator=coordinator,
|
||||
seat_executors=seat_executors,
|
||||
approval_gate=approval_gate,
|
||||
finalizer=finalizer,
|
||||
waiting_terminal=waiting_terminal,
|
||||
)
|
||||
@@ -0,0 +1,483 @@
|
||||
"""MAF Workflow runner — orchestrates workflow execution for a MAF run.
|
||||
|
||||
Called after ``create_run`` to actually execute the workflow. Translates all
|
||||
MAF Workflow events into ``maf_roundtable_events`` (the single event stream
|
||||
the frontend reads). Manages run status lifecycle and checkpoint persistence.
|
||||
|
||||
There is NO sequential fallback. If the MAF SDK is missing or the workflow
|
||||
fails, the run is marked ``failed`` with a sanitized error message. The runner
|
||||
never pretends a workflow executed when it did not.
|
||||
|
||||
Usage::
|
||||
|
||||
runner = WorkflowRunner(app, service=svc, user_id="u1")
|
||||
await runner.execute(session, run)
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import time
|
||||
from datetime import UTC, datetime
|
||||
from typing import Any
|
||||
|
||||
from app.maf_roundtable.action_coordinator import ActionCoordinator
|
||||
from app.maf_roundtable.deerflow_agent_adapter import DeerFlowAgentAdapter
|
||||
from app.maf_roundtable.runtime_client import DeerFlowRuntimeClient
|
||||
from app.maf_roundtable.sanitize import sanitize
|
||||
from app.maf_roundtable.workflow_executors import (
|
||||
ApprovalGateExecutor,
|
||||
CoordinatorExecutor,
|
||||
FinalizerExecutor,
|
||||
RoundtableState,
|
||||
SeatExecutor,
|
||||
WaitingTerminalExecutor,
|
||||
_agent_capabilities_from_snapshot,
|
||||
generate_final_report,
|
||||
)
|
||||
from app.maf_roundtable.workflow_factory import create_workflow
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class MafSdkMissingError(RuntimeError):
|
||||
"""Raised when the MAF SDK (agent_framework) is not installed."""
|
||||
|
||||
|
||||
class WorkflowRunner:
|
||||
"""Executes a MAF workflow for a given session/run pair."""
|
||||
|
||||
def __init__(self, app: Any, *, service: Any, user_id: str) -> None:
|
||||
self._app = app
|
||||
self._service = service
|
||||
self._user_id = user_id
|
||||
self._client = DeerFlowRuntimeClient(app)
|
||||
self._adapter = DeerFlowAgentAdapter(self._client, service=service, user_id=user_id)
|
||||
self._action_coordinator = ActionCoordinator(service, user_id=user_id)
|
||||
|
||||
@property
|
||||
def adapter(self) -> DeerFlowAgentAdapter:
|
||||
return self._adapter
|
||||
|
||||
@property
|
||||
def action_coordinator(self) -> ActionCoordinator:
|
||||
return self._action_coordinator
|
||||
|
||||
async def execute(self, session: dict[str, Any], run: dict[str, Any]) -> None:
|
||||
"""Execute the full workflow for a session/run.
|
||||
|
||||
Transitions run status: pending → running → completed/failed/cancelled.
|
||||
Persists checkpoint (RoundtableState) after each major step so the
|
||||
workflow can resume after approval or restart.
|
||||
"""
|
||||
run_id = run["id"]
|
||||
session_id = session["id"]
|
||||
t0 = time.perf_counter()
|
||||
|
||||
# Verify the MAF SDK is available before touching anything.
|
||||
try:
|
||||
import agent_framework # noqa: F401
|
||||
except ImportError as exc:
|
||||
await self._fail_run(run_id, session_id, t0, "MafSdkMissing", "agent_framework SDK is not installed")
|
||||
raise MafSdkMissingError("agent_framework SDK is not installed") from exc
|
||||
|
||||
await self._service.store.runs.update_run(run_id, {
|
||||
"status": "running",
|
||||
"started_at": datetime.now(UTC),
|
||||
})
|
||||
|
||||
try:
|
||||
participants = await self._service.store.participants.list_participants(session_id)
|
||||
thread_map = await self._adapter.ensure_threads(session_id, run_id, participants)
|
||||
|
||||
seat_agents = [p["agent_id"] for p in participants if p.get("role") != "manager"]
|
||||
manager_id = session.get("manager_agent_id")
|
||||
|
||||
state = RoundtableState(
|
||||
session_id=session_id,
|
||||
run_id=run_id,
|
||||
task_text=session.get("task_text", ""),
|
||||
mode=session.get("mode", "structured"),
|
||||
model_name=session.get("model_name"),
|
||||
reasoning_effort=session.get("reasoning_effort"),
|
||||
max_rounds=session.get("max_rounds", 8),
|
||||
write_policy=session.get("write_policy", "confirm_high_risk"),
|
||||
manager_agent_id=manager_id,
|
||||
seat_agent_ids=seat_agents,
|
||||
thread_map=thread_map,
|
||||
capability_snapshot=session.get("capability_snapshot"),
|
||||
)
|
||||
|
||||
# Build executor instances — one per seat, each bound to a fixed agent_id.
|
||||
coordinator = CoordinatorExecutor(self._adapter, state)
|
||||
seat_executors = [
|
||||
SeatExecutor(self._adapter, state, agent_id, action_coordinator=self._action_coordinator)
|
||||
for agent_id in seat_agents
|
||||
]
|
||||
approval_gate = ApprovalGateExecutor(self._adapter, state, self._service)
|
||||
finalizer = FinalizerExecutor(self._adapter, state)
|
||||
waiting_terminal = WaitingTerminalExecutor()
|
||||
|
||||
workflow = create_workflow(
|
||||
mode=state.mode,
|
||||
coordinator=coordinator,
|
||||
seat_executors=seat_executors,
|
||||
approval_gate=approval_gate,
|
||||
finalizer=finalizer,
|
||||
waiting_terminal=waiting_terminal,
|
||||
seat_agent_ids=seat_agents,
|
||||
)
|
||||
|
||||
await self._run_workflow(workflow, state)
|
||||
|
||||
# Persist final state. waiting_approval is NOT a terminal state —
|
||||
# it must NOT write finished_at. Only completed/failed/cancelled do.
|
||||
latency = int((time.perf_counter() - t0) * 1000)
|
||||
final_status = state.status
|
||||
token_usage = _aggregate_token_usage(state.turn_results)
|
||||
|
||||
update_fields: dict[str, Any] = {
|
||||
"status": final_status,
|
||||
"latency_ms": latency,
|
||||
"maf_checkpoint": state.to_dict(),
|
||||
"token_usage": token_usage,
|
||||
}
|
||||
# Only write finished_at for terminal statuses.
|
||||
if final_status in ("completed", "failed", "cancelled"):
|
||||
update_fields["finished_at"] = datetime.now(UTC)
|
||||
|
||||
await self._service.store.runs.update_run(run_id, update_fields)
|
||||
|
||||
session_fields: dict[str, Any] = {"status": final_status}
|
||||
if final_status == "completed":
|
||||
session_fields["final_result"] = state.final_result
|
||||
if final_status != "waiting_approval":
|
||||
session_fields["fact_ledger"] = state.fact_ledger
|
||||
await self._service.store.sessions.update_session(
|
||||
session_id, user_id=self._user_id, fields=session_fields
|
||||
)
|
||||
|
||||
except MafSdkMissingError:
|
||||
raise
|
||||
except Exception as exc:
|
||||
await self._fail_run(run_id, session_id, t0, type(exc).__name__, str(exc))
|
||||
|
||||
async def _run_workflow(self, workflow: Any, state: RoundtableState) -> None:
|
||||
"""Execute the workflow graph via the MAF SDK's streaming API.
|
||||
|
||||
Consumes ``WorkflowEvent``s and translates them into MAF roundtable
|
||||
events. Persists the RoundtableState checkpoint after each superstep.
|
||||
"""
|
||||
from app.maf_roundtable.event_normalizer import make_workflow_checkpointed
|
||||
|
||||
async for event in workflow.run(state.task_text, stream=True, include_status_events=True):
|
||||
event_type = getattr(event, "type", "")
|
||||
executor_id = getattr(event, "executor_id", None)
|
||||
|
||||
if event_type == "superstep_completed":
|
||||
# Persist checkpoint after each superstep.
|
||||
iteration = getattr(event, "iteration", None)
|
||||
await self._service.store.runs.update_run(state.run_id, {
|
||||
"maf_checkpoint": state.to_dict(),
|
||||
})
|
||||
await self._adapter._emit_critical(state.run_id, make_workflow_checkpointed(
|
||||
executor_id, state.current_round,
|
||||
checkpoint_id=f"superstep-{iteration}",
|
||||
reason="superstep_completed",
|
||||
))
|
||||
|
||||
elif event_type == "executor_failed":
|
||||
details = getattr(event, "details", None)
|
||||
error_msg = str(details) if details else "executor failed"
|
||||
raise RuntimeError(f"MAF executor '{executor_id}' failed: {error_msg}")
|
||||
|
||||
# Check if the workflow ended in a waiting_approval state.
|
||||
if state.status == "waiting_approval" or state.pending_approvals:
|
||||
state.status = "waiting_approval"
|
||||
|
||||
async def _fail_run(self, run_id: str, session_id: str, t0: float, error_code: str, error_message: str) -> None:
|
||||
"""Mark a run as failed with a sanitized error message."""
|
||||
latency = int((time.perf_counter() - t0) * 1000)
|
||||
safe_message = str(sanitize(error_message))[:500]
|
||||
logger.error("MAF workflow failed for run %s: %s", run_id, safe_message, exc_info=True)
|
||||
await self._service.store.runs.update_run(run_id, {
|
||||
"status": "failed",
|
||||
"finished_at": datetime.now(UTC),
|
||||
"error_code": error_code,
|
||||
"error_message_safe": safe_message,
|
||||
"latency_ms": latency,
|
||||
})
|
||||
await self._service.store.sessions.update_session(session_id, user_id=self._user_id, fields={
|
||||
"status": "failed",
|
||||
})
|
||||
|
||||
async def cancel(self, run_id: str) -> dict[str, Any]:
|
||||
"""Cancel a running workflow (cascades to all active seat runs).
|
||||
|
||||
Returns the structured cancel result from the adapter so the caller
|
||||
can decide whether to finalize the parent run as ``cancelled`` or
|
||||
leave it non-terminal when some sub-runs failed to cancel.
|
||||
"""
|
||||
return await self._adapter.cancel(run_id)
|
||||
|
||||
async def resume(self, run_id: str) -> dict[str, Any] | None:
|
||||
"""Resume a workflow from its persisted checkpoint after an approval decision.
|
||||
|
||||
P1: ``RoundtableState.from_dict()`` is actually called here. Flow:
|
||||
|
||||
1. Load ``maf_checkpoint_json`` from the run row.
|
||||
2. Restore ``RoundtableState`` via ``from_dict()``.
|
||||
3. Check the pending approvals' status:
|
||||
- ``approved``: execute the approved action via ToolExecutor
|
||||
(at-most-once, deterministic, no LLM).
|
||||
- ``rejected`` / ``expired``: write ``action.rejected``, skip.
|
||||
- ``pending``: do NOT start a second Workflow — return immediately.
|
||||
4. After all actions are executed, determine the parent run status:
|
||||
- All succeeded → ``completed``.
|
||||
- Any failed → ``failed`` (P1-8).
|
||||
- Any unknown → ``waiting_input`` (not completed; human reconcile needed).
|
||||
- All skipped (already executed) → ``completed``.
|
||||
|
||||
Only the owner can resume (enforced by the router before calling
|
||||
``dispatcher.resume``).
|
||||
"""
|
||||
t0 = time.perf_counter()
|
||||
run = await self._service.store.runs.get_run(run_id)
|
||||
if run is None:
|
||||
return None
|
||||
|
||||
if run["status"] != "waiting_approval":
|
||||
return run
|
||||
|
||||
checkpoint = run.get("maf_checkpoint")
|
||||
if not checkpoint:
|
||||
logger.warning("Cannot resume run %s: no checkpoint", run_id)
|
||||
return run
|
||||
|
||||
state = RoundtableState.from_dict(checkpoint)
|
||||
session_id = state.session_id
|
||||
|
||||
if not state.pending_approvals:
|
||||
logger.warning("Cannot resume run %s: no pending_approvals in checkpoint", run_id)
|
||||
return run
|
||||
|
||||
# Check if any approval is still pending — if so, don't resume yet.
|
||||
any_pending = False
|
||||
for pa in state.pending_approvals:
|
||||
approval_id = pa.get("approval_id", "")
|
||||
approval = await self._service.store.approvals.get_approval(approval_id)
|
||||
if approval and approval.get("status") == "pending":
|
||||
any_pending = True
|
||||
if any_pending:
|
||||
return run
|
||||
|
||||
# P0-3 run-level CAS: only ONE concurrent resume may execute the
|
||||
# approved actions and write the parent run's final state. The winner
|
||||
# moves the run waiting_approval → running; every other concurrent
|
||||
# caller loses the CAS and returns the current run WITHOUT writing a
|
||||
# terminal status (so it can never race a completed/failed write).
|
||||
claimed_run = await self._service.store.runs.claim_for_resume(run_id)
|
||||
if not claimed_run:
|
||||
logger.info("resume(%s): lost run-level CAS — another resume is executing", run_id)
|
||||
return await self._service.store.runs.get_run(run_id)
|
||||
|
||||
# Execute each approved action (skip rejected/expired).
|
||||
action_outcomes: list[dict[str, Any]] = []
|
||||
for pa in state.pending_approvals:
|
||||
approval_id = pa.get("approval_id", "")
|
||||
action_id = pa.get("action_id", "")
|
||||
approval = await self._service.store.approvals.get_approval(approval_id)
|
||||
if approval is None:
|
||||
action_outcomes.append({"action_id": action_id, "status": "failed",
|
||||
"error": "approval not found"})
|
||||
continue
|
||||
|
||||
approval_status = approval.get("status", "pending")
|
||||
|
||||
if approval_status in ("rejected", "expired"):
|
||||
from app.maf_roundtable.event_normalizer import make_action_rejected
|
||||
# Conditional transition (waiting_approval → rejected) — never
|
||||
# overwrite a terminal state via a generic update.
|
||||
await self._service.store.actions.mark_rejected(action_id)
|
||||
await self._adapter._emit_critical(run_id, make_action_rejected(
|
||||
pa.get("agent_id", ""),
|
||||
state.current_round,
|
||||
action_id=action_id,
|
||||
approval_id=approval_id,
|
||||
decided_by=approval.get("decided_by", ""),
|
||||
))
|
||||
action_outcomes.append({"action_id": action_id, "status": "rejected"})
|
||||
continue
|
||||
|
||||
if approval_status != "approved":
|
||||
action_outcomes.append({"action_id": action_id, "status": "failed",
|
||||
"error": f"unexpected approval status: {approval_status}"})
|
||||
continue
|
||||
|
||||
# Approved — execute deterministically via ToolExecutor.
|
||||
agent_id = pa.get("agent_id", "")
|
||||
thread_id = state.thread_map.get(agent_id, "")
|
||||
tool_name = pa.get("tool_name", "")
|
||||
|
||||
# Conditional transition (waiting_approval → approved). The
|
||||
# authoritative at-most-once gate is the ToolExecutor's
|
||||
# approved → running claim below; this just advances the state
|
||||
# machine without ever clobbering a terminal status.
|
||||
await self._service.store.actions.mark_approved(action_id)
|
||||
|
||||
from app.maf_roundtable.event_normalizer import make_action_approved
|
||||
await self._adapter._emit_critical(run_id, make_action_approved(
|
||||
agent_id,
|
||||
state.current_round,
|
||||
action_id=action_id,
|
||||
approval_id=approval_id,
|
||||
decided_by=approval.get("decided_by", ""),
|
||||
))
|
||||
|
||||
# Params are recovered server-side inside ToolExecutor (after the
|
||||
# atomic occupy). A missing/undecryptable secret fails the action
|
||||
# there — it is never coerced into empty params, so the tool is
|
||||
# never called (execution count == 0) and the parent run fails.
|
||||
if thread_id and tool_name:
|
||||
from app.maf_roundtable.tool_executor import ToolExecutor
|
||||
|
||||
executor = ToolExecutor(
|
||||
adapter=self._adapter,
|
||||
action_coordinator=self._action_coordinator,
|
||||
user_id=self._user_id,
|
||||
)
|
||||
try:
|
||||
outcome = await executor.execute(
|
||||
action_id=action_id,
|
||||
session_id=session_id,
|
||||
run_id=run_id,
|
||||
agent_id=agent_id,
|
||||
thread_id=thread_id,
|
||||
approved_tool=tool_name,
|
||||
capability_snapshot=state.capability_snapshot,
|
||||
write_policy=state.write_policy,
|
||||
model_name=state.model_name,
|
||||
excluded_tools=list(
|
||||
_agent_capabilities_from_snapshot(
|
||||
state.capability_snapshot, agent_id
|
||||
).get("excluded_tools")
|
||||
or []
|
||||
),
|
||||
)
|
||||
except Exception as exc:
|
||||
safe_msg = str(sanitize(str(exc)))[:500]
|
||||
logger.error("ToolExecutor for action %s failed: %s", action_id, safe_msg)
|
||||
outcome = {"status": "failed", "error": safe_msg}
|
||||
else:
|
||||
outcome = {"status": "failed", "error": f"no thread_id or tool_name for action {action_id}"}
|
||||
|
||||
action_outcomes.append({
|
||||
"action_id": action_id,
|
||||
"tool_name": tool_name,
|
||||
"status": outcome.get("status"),
|
||||
"error": outcome.get("error"),
|
||||
})
|
||||
|
||||
state.fact_ledger["pending_actions"].append({
|
||||
"action_id": action_id,
|
||||
"tool_name": tool_name,
|
||||
"outcome": outcome.get("status"),
|
||||
})
|
||||
|
||||
# P0-3: determine parent run status from action outcomes.
|
||||
statuses = {o.get("status") for o in action_outcomes}
|
||||
|
||||
# While any action is still in_progress (another executor running it),
|
||||
# the parent run stays running — never write finished_at, never finalize.
|
||||
if "in_progress" in statuses:
|
||||
state.status = "running"
|
||||
await self._service.store.runs.update_run(run_id, {
|
||||
"status": "running",
|
||||
"maf_checkpoint": state.to_dict(),
|
||||
})
|
||||
logger.info("resume(%s): action(s) still in_progress — run stays running", run_id)
|
||||
return await self._service.store.runs.get_run(run_id)
|
||||
|
||||
state.pending_approvals = []
|
||||
|
||||
has_unknown = "unknown" in statuses
|
||||
has_failed = "failed" in statuses
|
||||
all_resolved = statuses <= {"succeeded", "skipped", "rejected"}
|
||||
|
||||
if has_unknown:
|
||||
state.status = "waiting_input" # human reconciliation needed
|
||||
elif has_failed:
|
||||
state.status = "failed"
|
||||
elif all_resolved:
|
||||
# Re-enter the MAF finalizer path to synthesize the real report —
|
||||
# do NOT just flip the status to completed.
|
||||
try:
|
||||
await generate_final_report(self._adapter, state)
|
||||
state.status = "completed"
|
||||
except Exception as exc: # noqa: BLE001
|
||||
safe_msg = str(sanitize(str(exc)))[:500]
|
||||
logger.error("resume(%s): finalizer failed: %s", run_id, safe_msg)
|
||||
state.status = "failed"
|
||||
action_outcomes.append({"action_id": "", "status": "failed",
|
||||
"error": f"finalizer failed: {safe_msg}"})
|
||||
else:
|
||||
state.status = "failed"
|
||||
|
||||
# Persist final state.
|
||||
latency = int((time.perf_counter() - t0) * 1000)
|
||||
token_usage = _aggregate_token_usage(state.turn_results)
|
||||
update_fields: dict[str, Any] = {
|
||||
"status": state.status,
|
||||
"latency_ms": latency,
|
||||
"maf_checkpoint": state.to_dict(),
|
||||
"token_usage": token_usage,
|
||||
}
|
||||
if state.status in ("completed", "failed", "cancelled"):
|
||||
update_fields["finished_at"] = datetime.now(UTC)
|
||||
if state.status == "failed":
|
||||
errors = [o.get("error") for o in action_outcomes if o.get("error")]
|
||||
update_fields["error_code"] = "ActionExecutionFailed"
|
||||
update_fields["error_message_safe"] = str(sanitize("; ".join(errors)))[:500]
|
||||
|
||||
await self._service.store.runs.update_run(run_id, update_fields)
|
||||
|
||||
session_fields: dict[str, Any] = {"status": state.status}
|
||||
if state.status == "completed":
|
||||
session_fields["final_result"] = state.final_result
|
||||
session_fields["fact_ledger"] = state.fact_ledger
|
||||
await self._service.store.sessions.update_session(
|
||||
session_id, user_id=self._user_id, fields=session_fields
|
||||
)
|
||||
|
||||
return await self._service.store.runs.get_run(run_id)
|
||||
|
||||
|
||||
def _aggregate_token_usage(turn_results: list[dict[str, Any]]) -> dict[str, Any]:
|
||||
"""Aggregate token usage across all seat turns into a run-level summary."""
|
||||
total_input = 0
|
||||
total_output = 0
|
||||
total_total = 0
|
||||
per_seat: list[dict[str, Any]] = []
|
||||
for turn in turn_results:
|
||||
usage = turn.get("usage")
|
||||
if not isinstance(usage, dict):
|
||||
continue
|
||||
inp = usage.get("input_tokens", 0) or usage.get("prompt_tokens", 0) or 0
|
||||
out = usage.get("output_tokens", 0) or usage.get("completion_tokens", 0) or 0
|
||||
tot = usage.get("total_tokens", 0) or (inp + out)
|
||||
total_input += inp
|
||||
total_output += out
|
||||
total_total += tot
|
||||
per_seat.append({
|
||||
"agent_id": turn.get("agent_id", ""),
|
||||
"turn_index": turn.get("turn_index", 0),
|
||||
"input_tokens": inp,
|
||||
"output_tokens": out,
|
||||
"total_tokens": tot,
|
||||
})
|
||||
return {
|
||||
"total_input_tokens": total_input,
|
||||
"total_output_tokens": total_output,
|
||||
"total_tokens": total_total,
|
||||
"per_seat": per_seat,
|
||||
}
|
||||
@@ -0,0 +1,210 @@
|
||||
"""Application-layer bridge between the harness ``WriteGuardMiddleware`` and
|
||||
the MAF ``ActionCoordinator``.
|
||||
|
||||
The harness middleware (``deerflow.agents.middlewares.write_guard_middleware``)
|
||||
is constructed once at agent-build time and cannot hold per-run state. It
|
||||
resolves two factories — ``make_policy`` / ``make_interceptor`` — by dotted
|
||||
path (``resolve_variable``). These factories return lightweight singleton
|
||||
objects that, at interception time, read the MAF service + per-run data from
|
||||
the run context.
|
||||
|
||||
Wiring
|
||||
------
|
||||
``register_write_guard_service(service)`` is called from ``deps.py`` once the
|
||||
``MafRoundtableService`` is built, stashing a module-level reference. The
|
||||
factories use it to build an ``ActionCoordinator`` on demand.
|
||||
|
||||
Per-run data (``session_id`` / ``run_id`` / ``agent_id`` / ``turn_index`` /
|
||||
``write_policy`` / ``capability_snapshot``) is injected into the DeerFlow run
|
||||
context by ``runtime_client.start_agent_run`` (see Task 1.4) and read back
|
||||
here from the ``run_context`` dict the middleware forwards.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from typing import Any
|
||||
|
||||
from app.maf_roundtable.action_coordinator import (
|
||||
ActionCoordinator,
|
||||
tool_needs_approval,
|
||||
)
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# Module-level reference to the MAF service, set by ``register_write_guard_service``.
|
||||
# Resolved lazily so importing this module never requires the service to exist.
|
||||
_maf_service: Any = None
|
||||
|
||||
|
||||
def register_write_guard_service(service: Any) -> None:
|
||||
"""Stash the MAF service so the WriteGuard factories can reach it.
|
||||
|
||||
Called once from ``app.gateway.deps`` after ``MafRoundtableService`` is built.
|
||||
"""
|
||||
global _maf_service
|
||||
_maf_service = service
|
||||
|
||||
|
||||
def _get_service() -> Any:
|
||||
if _maf_service is None: # pragma: no cover - defensive; wiring is enforced at startup
|
||||
raise RuntimeError(
|
||||
"WriteGuard bridge used before register_write_guard_service() — "
|
||||
"MAF service is not wired."
|
||||
)
|
||||
return _maf_service
|
||||
|
||||
|
||||
def _coordinator_for_context(run_context: dict) -> ActionCoordinator:
|
||||
"""Build an ActionCoordinator bound to the run's user identity.
|
||||
|
||||
The user_id is sourced ONLY from the server-injected run context (set by
|
||||
``runtime_client`` from the authenticated ``ExecutionPrincipal``), never
|
||||
from tool arguments.
|
||||
"""
|
||||
service = _get_service()
|
||||
user_id = str(run_context.get("maf_user_id") or run_context.get("user_id") or "")
|
||||
return ActionCoordinator(service, user_id=user_id)
|
||||
|
||||
|
||||
# ── Policy ─────────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
class MafWriteGuardPolicy:
|
||||
"""Decides whether a tool call must be intercepted for approval.
|
||||
|
||||
Reads the per-run ``write_policy`` and ``capability_snapshot`` from the
|
||||
run context. Uses the same metadata-driven classification as the rest of
|
||||
the ActionCoordinator (never name-prefix heuristics). Tools without
|
||||
metadata use the safe default (treated as a write requiring approval).
|
||||
"""
|
||||
|
||||
def should_intercept(self, tool_name: str, args: Any, run_context: dict | None = None) -> bool: # noqa: ANN401
|
||||
"""Decide interception from the run context (read vs write aware).
|
||||
|
||||
Reads / skills (``side_effect`` of ``read`` / ``skill``) are NEVER
|
||||
intercepted, so they pass straight through — including on the sync
|
||||
path. Writes are gated by the active write policy via the same
|
||||
metadata-driven ``tool_needs_approval`` classification used everywhere
|
||||
else (never name-prefix heuristics). When no run context is available
|
||||
we defer to the interceptor (legacy behaviour).
|
||||
"""
|
||||
if not tool_name:
|
||||
return False
|
||||
if not run_context:
|
||||
# Cannot classify without context — let the interceptor decide.
|
||||
return True
|
||||
write_policy = str(run_context.get("write_policy") or "confirm_high_risk")
|
||||
capability_snapshot = run_context.get("capability_snapshot")
|
||||
agent_id = str(run_context.get("agent_id") or "")
|
||||
return tool_needs_approval(tool_name, write_policy, capability_snapshot, agent_id)
|
||||
|
||||
|
||||
# ── Interceptor ────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
class MafWriteGuardInterceptor:
|
||||
"""Records an intercepted write tool call as a pending action + approval.
|
||||
|
||||
Implements the harness ``WriteGuardInterceptor`` Protocol. Uses the
|
||||
single-transaction ``store.create_pending_action_bundle`` (Task 2) so an
|
||||
action + secret + approval + audit event are written atomically — a
|
||||
partial action never reaches the database.
|
||||
"""
|
||||
|
||||
async def intercept(
|
||||
self,
|
||||
*,
|
||||
tool_name: str,
|
||||
args: Any, # noqa: ANN401
|
||||
tool_call_id: str,
|
||||
run_context: dict,
|
||||
) -> dict[str, Any]:
|
||||
write_policy = str(run_context.get("write_policy") or "confirm_high_risk")
|
||||
capability_snapshot = run_context.get("capability_snapshot")
|
||||
agent_id = str(run_context.get("agent_id") or "")
|
||||
run_id = str(run_context.get("maf_run_id") or "")
|
||||
session_id = str(run_context.get("maf_session_id") or "")
|
||||
turn_index = int(run_context.get("turn_index") or 0)
|
||||
|
||||
# Apply the real policy now that we have the run context.
|
||||
if not tool_needs_approval(tool_name, write_policy, capability_snapshot, agent_id):
|
||||
return {"status": "allowed", "tool_name": tool_name}
|
||||
|
||||
coordinator = _coordinator_for_context(run_context)
|
||||
raw_args = args if isinstance(args, dict) else {"value": str(args)}
|
||||
|
||||
created = await coordinator.intercept_write_tool_calls(
|
||||
run_id=run_id,
|
||||
session_id=session_id,
|
||||
agent_id=agent_id,
|
||||
turn_index=turn_index,
|
||||
tool_calls=[{"name": tool_name, "id": tool_call_id, "args": raw_args}],
|
||||
capability_snapshot=capability_snapshot,
|
||||
write_policy=write_policy,
|
||||
)
|
||||
|
||||
if not created:
|
||||
return {"status": "allowed", "tool_name": tool_name}
|
||||
|
||||
action = created[0]
|
||||
return {
|
||||
"status": "approval_required",
|
||||
"action_id": action.get("id", ""),
|
||||
"approval_id": action.get("approval_id", ""),
|
||||
"tool_name": tool_name,
|
||||
}
|
||||
|
||||
async def validate_approved_action(
|
||||
self,
|
||||
*,
|
||||
tool_name: str,
|
||||
run_context: dict,
|
||||
) -> bool:
|
||||
"""Validate a post-approval deterministic execution against the store.
|
||||
|
||||
Field presence is NOT trusted: this queries the bound action and confirms
|
||||
it is ``running`` (the executor already occupied it), belongs to the
|
||||
current ``run_id`` / ``session_id`` / ``agent_id``, and its ``tool_name``
|
||||
matches. Returns True only when every check holds; otherwise the
|
||||
middleware fails closed and the tool does not run.
|
||||
"""
|
||||
action_id = str(run_context.get("maf_approved_action_id") or "")
|
||||
if not action_id:
|
||||
return False
|
||||
approved_tool = str(run_context.get("maf_approved_tool") or "")
|
||||
if approved_tool and tool_name != approved_tool:
|
||||
return False
|
||||
|
||||
run_id = str(run_context.get("maf_run_id") or "")
|
||||
session_id = str(run_context.get("maf_session_id") or "")
|
||||
agent_id = str(run_context.get("agent_id") or "")
|
||||
|
||||
service = _get_service()
|
||||
action = await service.store.actions.get_action(action_id)
|
||||
if action is None:
|
||||
return False
|
||||
if action.get("status") != "running":
|
||||
return False
|
||||
if run_id and str(action.get("run_id") or "") != run_id:
|
||||
return False
|
||||
if session_id and str(action.get("session_id") or "") != session_id:
|
||||
return False
|
||||
if agent_id and str(action.get("agent_id") or "") != agent_id:
|
||||
return False
|
||||
if str(action.get("tool_name") or "") != tool_name:
|
||||
return False
|
||||
return True
|
||||
|
||||
|
||||
# ── Factories resolved by the harness via resolve_variable ──────────────────
|
||||
|
||||
|
||||
def make_policy(**_: Any) -> MafWriteGuardPolicy:
|
||||
"""Factory for the harness ``resolve_variable`` resolution."""
|
||||
return MafWriteGuardPolicy()
|
||||
|
||||
|
||||
def make_interceptor(**_: Any) -> MafWriteGuardInterceptor:
|
||||
"""Factory for the harness ``resolve_variable`` resolution."""
|
||||
return MafWriteGuardInterceptor()
|
||||
Reference in new issue
Block a user