feat(maf): Phase 5 - action coordinator, approval flow, frontend MAF roundtable pages

- Backend: action_coordinator, capability_snapshot, event_normalizer, tool_executor updates
- Backend: approved_tool_executor with write guard, action leases, migration script
- Frontend: maf-roundtable module (API client, event timeline, approval cards, fact flow panel)
- Frontend: MafRoutes, MafSessionsPage, MafRunDetailPage
- Tests: action_leases, migration_phase5, phase5_entry_e2e, real_write_e2e/http_e2e
- Docs: update implementation plan

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
董宏凯andCursor committed 2026-08-02 13:07:21 +08:00
1 parent 21c4c898e7
commit f82363d81f
55 files changed
+6304 -167

No files matched your search

@@ -17,15 +17,74 @@
from __future__ import annotations
import re
from typing import Literal
from pydantic import BaseModel, Field
from pydantic import BaseModel, Field, field_validator
# ── shared enums (config + API schemas) ───────────────────────────────────
MafMode = Literal["structured", "group_chat"]
MafWritePolicy = Literal["auto", "confirm_high_risk", "confirm_all_writes"]
MafParticipantRole = Literal["manager", "seat"]
MafToolSideEffect = Literal["read", "skill", "write"]
MafRiskLevel = Literal["R0", "R1", "R2", "R3", "R4"]
class MafToolMetadata(BaseModel):
"""Deployment-owned side-effect classification for one actual tool name.
This lives in the MAF configuration rather than in the browser request or
model output. The key in ``MafRoundtableConfig.tool_metadata`` must be the
exact runtime tool name (including the MCP server prefix when applicable).
"""
side_effect: MafToolSideEffect = Field(
description="Tool side effect class used by the MAF WriteGuard",
)
risk_level: MafRiskLevel = Field(
description="External action risk level used by MAF approval policy",
)
target_key_fields: list[str] = Field(
default_factory=list,
description=(
"仅服务端配置的、用于派生目标租约键的顶层参数字段。"
"参数值只参与稳定哈希,绝不直接写入 target_key。"
),
)
target_key_namespace: str = Field(
default="default",
min_length=1,
max_length=96,
description="服务端目标键命名空间;用于隔离不同租户/业务域。",
)
@field_validator("target_key_fields")
@classmethod
def _validate_target_key_fields(cls, fields: list[str]) -> list[str]:
"""Only allow explicit top-level server-owned argument names.
In particular, a model/client supplied ``target_key`` is never a
valid input. Nested paths are deliberately unsupported: a production
adapter must register the exact stable business-id fields it owns.
"""
valid = re.compile(r"^[A-Za-z_][A-Za-z0-9_]{0,63}$")
normalized: list[str] = []
for field in fields:
if not isinstance(field, str) or not valid.fullmatch(field):
raise ValueError("target_key_fields must be simple top-level argument names")
if field == "target_key":
raise ValueError("target_key must not be supplied as a target key input")
if field not in normalized:
normalized.append(field)
return normalized
@field_validator("target_key_namespace")
@classmethod
def _validate_target_key_namespace(cls, namespace: str) -> str:
if not re.fullmatch(r"[A-Za-z0-9_.:-]{1,96}", namespace):
raise ValueError("target_key_namespace contains unsupported characters")
return namespace
class MafRoundtableConfig(BaseModel):
@@ -74,11 +133,39 @@ class MafRoundtableConfig(BaseModel):
default=True,
description="席位输出未通过 SeatTurnOutput 校验时是否允许一次定向格式修复",
)
# Server-trusted metadata keyed by the exact runtime tool name. Do not
# infer this from MCP server names or prefixes: the actual discovered name
# is what the capability snapshot and runtime WriteGuard see.
tool_metadata: dict[str, MafToolMetadata] = Field(
default_factory=dict,
description="MAF 专用工具副作用/风险元数据,键必须是实际运行时 tool name",
)
approval_timeout_seconds: int = Field(
default=3600,
ge=60,
le=604800,
description="外部写入审批有效期(秒);到期后自动拒绝,绝不执行。",
)
approval_scan_interval_seconds: int = Field(
default=10,
ge=1,
le=3600,
description="MAF approval expiry scan interval in seconds",
)
target_lease_seconds: int = Field(
default=900,
ge=30,
le=7200,
description="外部业务目标写入租约有效期(秒);过期运行中的动作转 unknown。",
)
__all__ = [
"MafMode",
"MafParticipantRole",
"MafRiskLevel",
"MafRoundtableConfig",
"MafToolMetadata",
"MafToolSideEffect",
"MafWritePolicy",
]
@@ -1,9 +1,9 @@
"""Microsoft Agent Framework (MAF) roundtable experiment persistence.
Six independent tables — **no foreign keys to the legacy ``roundtable_*``
Nine independent tables — **no foreign keys to the legacy ``roundtable_*``
tables** — so the existing multi-agent roundtable keeps its current behavior,
schema, and recovery semantics untouched. The MAF experiment is fully
isolated: it has its own session / participant / run / event / action /
isolated: it has its own session / participant / run / event / action / lease /
approval tables.
Boundary: this package lives in the harness layer (``deerflow.*``) and never
@@ -18,7 +18,8 @@ Tables (see the implementation plan §8):
- ``maf_roundtable_runs`` — one execution run of a session
- ``maf_roundtable_events`` — monotonic per-run event stream (``(run_id, seq)`` unique)
- ``maf_roundtable_actions`` — external write / tool actions (idempotency-keyed)
- ``maf_roundtable_approvals`` — pending human-approval requests
- ``maf_roundtable_action_leases`` — active target-write leases
- ``maf_roundtable_approvals`` — pending human-approval requests
- ``maf_roundtable_seat_runs`` — MAF↔DeerFlow run mapping (survives restart)
- ``maf_roundtable_action_secrets`` — encrypted actual execution params (server-only)
"""
@@ -32,6 +33,7 @@ from deerflow.persistence.maf_roundtable.actions import MafActionRepository
from deerflow.persistence.maf_roundtable.approvals import MafApprovalRepository
from deerflow.persistence.maf_roundtable.events import MafEventRepository
from deerflow.persistence.maf_roundtable.model import (
MafRoundtableActionLeaseRow,
MafRoundtableActionRow,
MafRoundtableActionSecretRow,
MafRoundtableApprovalRow,
@@ -54,6 +56,7 @@ __all__ = [
"MafEventRepository",
"MafParticipantRepository",
"MafRoundtableActionRow",
"MafRoundtableActionLeaseRow",
"MafRoundtableActionSecretRow",
"MafRoundtableApprovalRow",
"MafRoundtableEventRow",
@@ -10,6 +10,7 @@ store does not re-redact.
from __future__ import annotations
from collections.abc import Mapping
from datetime import UTC, datetime
from typing import Any
from uuid import uuid4
@@ -50,6 +51,19 @@ def action_to_dict(row: MafRoundtableActionRow) -> dict[str, Any]:
}
def action_to_public_dict(action: Mapping[str, Any]) -> dict[str, Any]:
"""Return the allow-listed action representation exposed by MAF HTTP APIs.
Target lease keys and idempotency keys are persistence/coordinator
details. They must never cross the public boundary.
"""
public = dict(action)
public.pop("target_key", None)
public.pop("idempotency_key", None)
return public
# Back-compat alias for internal callers that used the old private name.
_to_dict = action_to_dict
@@ -1,9 +1,9 @@
"""ORM models for the MAF (Microsoft Agent Framework) roundtable experiment.
Six independent tables — **no foreign keys to the legacy ``roundtable_*``
Nine independent tables — **no foreign keys to the legacy ``roundtable_*``
tables** (``roundtable_jobs`` / ``roundtable_drafts`` /
``roundtable_task_drafts``). The MAF experiment is fully isolated: it has its
own session / participant / run / event / action / approval tables, keyed by
own session / participant / run / event / action / lease / approval tables, keyed by
its own surrogate ids, so the legacy multi-agent roundtable keeps its current
behavior, schema, and recovery semantics untouched.
@@ -14,6 +14,7 @@ Tables (see the implementation plan §8):
- ``maf_roundtable_runs`` — one execution run of a session
- ``maf_roundtable_events`` — monotonic per-run event stream (``(run_id, seq)`` unique)
- ``maf_roundtable_actions`` — external write / tool actions (idempotency-keyed)
- ``maf_roundtable_action_leases`` — active target-write leases (one per target key)
- ``maf_roundtable_approvals`` — pending human-approval requests
User isolation: ``maf_roundtable_sessions.user_id`` is the owner; all child
@@ -263,7 +264,42 @@ class MafRoundtableActionRow(Base):
)
# ── 6. approvals ──────────────────────────────────────────────────────────
# ── 6. target leases ──────────────────────────────────────────────────────
class MafRoundtableActionLeaseRow(Base):
"""One active, short-lived lease for a server-derived external target key.
The key is opaque (a stable SHA-256 digest) and is never sourced from a
browser/model field. ``target_key`` is the primary key, which makes the
database — not an in-process mutex — arbitrate concurrent writes across
workers and restarts. A lease belongs to exactly one action and is removed
with a known terminal result; an ``unknown`` result deliberately retains a
manual-reconciliation barrier.
"""
__tablename__ = "maf_roundtable_action_leases"
__table_args__ = (
UniqueConstraint("action_id", name="uq_maf_action_leases_action"),
)
target_key: Mapped[str] = mapped_column(String(255), primary_key=True)
action_id: Mapped[str] = mapped_column(
String(64),
ForeignKey("maf_roundtable_actions.id", ondelete="CASCADE"),
nullable=False,
index=True,
)
lease_expires_at: Mapped[datetime] = mapped_column(
BeijingDateTime(), nullable=False, index=True
)
created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=_now)
updated_at: Mapped[datetime] = mapped_column(
BeijingDateTime(), nullable=False, default=_now, onupdate=_now
)
# ── 7. approvals ──────────────────────────────────────────────────────────
class MafRoundtableApprovalRow(Base):
@@ -297,7 +333,7 @@ class MafRoundtableApprovalRow(Base):
)
# ── 7. seat runs (Phase 2: MAF↔DeerFlow run mapping) ─────────────────────
# ── 8. seat runs (Phase 2: MAF↔DeerFlow run mapping) ─────────────────────
class MafRoundtableSeatRunRow(Base):
@@ -370,7 +406,7 @@ class MafRoundtableSeatRunRow(Base):
)
# ── 8. action secrets (encrypted actual execution params, server-only) ────
# ── 9. action secrets (encrypted actual execution params, server-only) ────
class MafRoundtableActionSecretRow(Base):
@@ -403,6 +439,7 @@ class MafRoundtableActionSecretRow(Base):
__all__ = [
"MafRoundtableActionRow",
"MafRoundtableActionLeaseRow",
"MafRoundtableActionSecretRow",
"MafRoundtableApprovalRow",
"MafRoundtableEventRow",
@@ -14,19 +14,24 @@ another's transactions.
from __future__ import annotations
from datetime import UTC, datetime
from datetime import UTC, datetime, timedelta
from typing import Any
from uuid import uuid4
from sqlalchemy import func, select, update
from sqlalchemy import delete, func, select, update
from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from deerflow.persistence.maf_roundtable.action_secrets import MafActionSecretRepository
from deerflow.persistence.maf_roundtable.actions import MafActionRepository, action_to_dict
from deerflow.persistence.maf_roundtable.actions import (
MafActionRepository,
MafActionStateMachineError,
action_to_dict,
)
from deerflow.persistence.maf_roundtable.approvals import MafApprovalRepository
from deerflow.persistence.maf_roundtable.events import MafEventRepository
from deerflow.persistence.maf_roundtable.model import (
MafRoundtableActionLeaseRow,
MafRoundtableActionRow,
MafRoundtableActionSecretRow,
MafRoundtableApprovalRow,
@@ -315,6 +320,7 @@ class MafRoundtableStore:
approval_payload: dict[str, Any] | None,
audit_event_agent_id: str,
audit_event_turn_index: int,
approval_expires_at: datetime | None = None,
) -> dict[str, Any]:
"""Create an action + secret + approval + audit event in ONE transaction.
@@ -432,6 +438,7 @@ class MafRoundtableStore:
status="pending",
summary=approval_summary,
payload_redacted_json=approval_payload,
expires_at=approval_expires_at,
created_at=now,
updated_at=now,
))
@@ -482,10 +489,308 @@ class MafRoundtableStore:
return result
raise RuntimeError(
f"create_pending_action_bundle failed after {_MAX_BUNDLE_RETRIES} attempts "
f"for idempotency_key={idempotency_key}"
f"create_pending_action_bundle failed after {_MAX_BUNDLE_RETRIES} attempts"
) from last_error
async def claim_action_for_execution(self, action_id: str, *, lease_seconds: int) -> str:
"""Atomically claim an approved action and its external-target lease.
The action CAS and the target lease live in one transaction. A second
approved action for the same target receives ``target_busy`` and is not
executed. An expired lease owned by a still-running action is treated
as an ambiguous external outcome: the old action becomes ``unknown``
and the caller receives ``target_reconciliation_required`` rather than
being allowed to write over it.
"""
# Pre-Phase-5 actions have no server-derived target key. Preserve the
# original conditional UPDATE CAS for them; replacing it with a
# read-then-write transaction would weaken their existing cross-worker
# at-most-once guarantee on SQLite (where FOR UPDATE is a no-op).
existing = await self.actions.get_action(action_id)
if existing is None:
raise MafActionStateMachineError(f"action {action_id} not found during claim")
if not existing.get("target_key"):
return await self.actions.claim_for_execution(action_id)
now = _now()
expiry = now + timedelta(seconds=max(1, lease_seconds))
last_error: Exception | None = None
for _attempt in range(4):
try:
async with self._sf() as db:
async with db.begin():
action = (
await db.execute(
select(MafRoundtableActionRow)
.where(MafRoundtableActionRow.id == action_id)
.with_for_update()
)
).scalars().first()
if action is None:
raise MafActionStateMachineError(
f"action {action_id} not found during claim"
)
if action.status == "running":
return "in_progress"
if action.status in ("succeeded", "failed", "unknown", "rejected"):
return str(action.status)
if action.status != "approved":
raise MafActionStateMachineError(
f"action {action_id} cannot be claimed from state '{action.status}'"
)
# Legacy rows can be executed at most once with the old
# action CAS. All new actions receive a target key from
# ActionCoordinator; never manufacture one from client
# input here.
if action.target_key:
lease = (
await db.execute(
select(MafRoundtableActionLeaseRow)
.where(MafRoundtableActionLeaseRow.target_key == action.target_key)
.with_for_update()
)
).scalars().first()
if lease is not None and lease.action_id != action.id:
owner = (
await db.execute(
select(MafRoundtableActionRow)
.where(MafRoundtableActionRow.id == lease.action_id)
.with_for_update()
)
).scalars().first()
if owner is not None and owner.status == "unknown":
# Unknown means the remote side effect may
# have happened. Keep the lease as a
# durable manual-reconciliation barrier;
# another write to the same object must not
# silently leapfrog it.
return "target_reconciliation_required"
if lease.lease_expires_at > now:
return "target_busy"
if owner is not None and owner.status == "running":
owner.status = "unknown"
owner.result_redacted_json = {
"error_code": "target_lease_expired_during_execution"
}
owner.finished_at = now
owner.updated_at = now
# Retain the lease as an explicit manual
# reconciliation barrier. It is released
# only by a future audited reconciliation
# flow, never by automatic replay.
lease.lease_expires_at = now
lease.updated_at = now
return "target_reconciliation_required"
await db.delete(lease)
elif lease is not None and lease.action_id == action.id:
# This can only occur after a failed local
# terminal-result write. Do not treat it as a
# new execution opportunity.
return "in_progress"
db.add(MafRoundtableActionLeaseRow(
target_key=action.target_key,
action_id=action.id,
lease_expires_at=expiry,
created_at=now,
updated_at=now,
))
action.status = "running"
action.attempt_count = int(action.attempt_count or 0) + 1
action.started_at = now
action.updated_at = now
await db.flush()
return "claimed"
except IntegrityError as exc:
# The target-key primary key is the cross-worker arbitration
# point. On a collision retry and observe the winning lease.
last_error = exc
continue
raise RuntimeError(f"could not claim action lease for {action_id}") from last_error
async def record_action_terminal_result(
self,
action_id: str,
*,
status: str,
result: dict[str, Any] | None = None,
external_object_id: str | None = None,
) -> dict[str, Any] | None:
"""Persist a terminal result and release a known target lease atomically.
``unknown`` is intentionally different: its target lease remains as a
manual-reconciliation barrier because the remote side effect may have
completed even though the local process cannot prove it.
"""
if status not in ("succeeded", "failed", "unknown"):
raise ValueError(f"invalid action result status: {status}")
now = _now()
async with self._sf() as db:
async with db.begin():
action = (
await db.execute(
select(MafRoundtableActionRow)
.where(MafRoundtableActionRow.id == action_id)
.with_for_update()
)
).scalars().first()
if action is None or action.status != "running":
return None
action.status = status
action.result_redacted_json = result
action.external_object_id = external_object_id
action.finished_at = now
action.updated_at = now
if status != "unknown":
# A known success or known failure has a deterministic
# outcome, so the next approved action may acquire the
# target. ``unknown`` deliberately retains the barrier.
await db.execute(
delete(MafRoundtableActionLeaseRow).where(
MafRoundtableActionLeaseRow.action_id == action_id
)
)
await db.flush()
return action_to_dict(action)
async def expire_due_approvals(
self, *, run_id: str | None = None, now: datetime | None = None
) -> list[dict[str, Any]]:
"""Expire due approvals and reject unexecuted actions with audit events.
Expiry is deliberately a fail-closed transition: only an action still
waiting for approval becomes rejected; a later/running action is never
overwritten. The approval, action and critical event are committed in
one transaction so polling sees a coherent terminal decision.
"""
current = now or _now()
last_error: Exception | None = None
for _attempt in range(4):
try:
async with self._sf() as db:
async with db.begin():
stmt = select(MafRoundtableApprovalRow).where(
MafRoundtableApprovalRow.status == "pending",
MafRoundtableApprovalRow.expires_at.is_not(None),
MafRoundtableApprovalRow.expires_at <= current,
)
if run_id is not None:
stmt = stmt.where(MafRoundtableApprovalRow.run_id == run_id)
approvals = (await db.execute(stmt.with_for_update())).scalars().all()
if not approvals:
return []
max_seq_by_run: dict[str, int] = {}
expired: list[dict[str, Any]] = []
for approval in approvals:
approval.status = "expired"
approval.decided_by = "system:approval_timeout"
approval.decided_at = current
approval.updated_at = current
action = None
if approval.action_id:
action = (
await db.execute(
select(MafRoundtableActionRow)
.where(MafRoundtableActionRow.id == approval.action_id)
.with_for_update()
)
).scalars().first()
if action is not None and action.status == "waiting_approval":
action.status = "rejected"
action.finished_at = current
action.updated_at = current
if approval.run_id and action is not None:
seq = max_seq_by_run.get(approval.run_id)
if seq is None:
seq = int((
await db.execute(
select(func.max(MafRoundtableEventRow.seq)).where(
MafRoundtableEventRow.run_id == approval.run_id
)
)
).scalar_one() or 0)
seq += 1
max_seq_by_run[approval.run_id] = seq
db.add(MafRoundtableEventRow(
id=uuid4().hex,
session_id=approval.session_id,
run_id=approval.run_id,
seq=seq,
event_type="action.rejected",
agent_id=approval.requested_by_agent_id,
turn_index=action.turn_index,
source_event_id=f"approval-expired:{approval.id}",
payload_json={
"action_id": action.id,
"approval_id": approval.id,
"reason": "approval_expired",
},
created_at=current,
))
expired.append({
"id": approval.id,
"run_id": approval.run_id,
"action_id": approval.action_id,
})
await db.flush()
return expired
except IntegrityError as exc:
last_error = exc
continue
raise RuntimeError("could not persist expired MAF approvals") from last_error
async def recover_expired_action_leases(
self, *, run_id: str, now: datetime | None = None
) -> list[dict[str, Any]]:
"""Mark stale in-flight writes ``unknown`` during restart recovery.
No tool is re-run. A lease that survived a process death cannot prove
whether the remote side effect completed, so the only safe recovery is
an explicit human reconciliation path.
"""
current = now or _now()
async with self._sf() as db:
async with db.begin():
rows = (
await db.execute(
select(MafRoundtableActionLeaseRow, MafRoundtableActionRow)
.join(
MafRoundtableActionRow,
MafRoundtableActionLeaseRow.action_id == MafRoundtableActionRow.id,
)
.where(
MafRoundtableActionRow.run_id == run_id,
MafRoundtableActionLeaseRow.lease_expires_at <= current,
)
.with_for_update()
)
).all()
recovered: list[dict[str, Any]] = []
for lease, action in rows:
if action.status == "running":
action.status = "unknown"
action.result_redacted_json = {
"error_code": "target_lease_expired_during_execution"
}
action.finished_at = current
action.updated_at = current
recovered.append(action_to_dict(action))
# Keep a durable block for manual reconciliation;
# automatically deleting it would allow a later write
# to overtake an ambiguous external side effect.
lease.lease_expires_at = current
lease.updated_at = current
elif action.status != "unknown":
await db.delete(lease)
await db.flush()
return recovered
__all__ = [
"MafActionRepository",
@@ -37,6 +37,7 @@ passing all secret-derived params and the stored action record as plain data.
from __future__ import annotations
import json
import logging
import uuid
from typing import Any, TypedDict
@@ -477,6 +478,15 @@ def _interpret_tool_node_result(result: Any, tool_name: str) -> dict[str, Any]:
if _is_inconclusive_text(text):
return {"status": "unknown", "error": _ERROR_CODE_INCONCLUSIVE}
return {"status": "failed", "error": _ERROR_CODE_FAILED}
# LangChain may serialize a structured tool return into a JSON string
# inside ToolMessage.content. Recover only the safe, allow-listed
# fields so an external object id can be audited without exposing
# arbitrary tool output.
if isinstance(content, str):
try:
content = json.loads(content)
except (TypeError, ValueError):
pass
return {"status": "succeeded", "result": _safe_success_payload(content)}
return {"status": "succeeded", "result": {"executed": True}}
@@ -0,0 +1,77 @@
"""Test-only real external-write tool for MAF approval E2E tests.
This module is deliberately not registered in ``config.yaml``. Tests add the
tool to an isolated ``AppConfig`` and set ``MAF_E2E_OUTBOX_DIR`` to a temporary
directory. It is a real LangChain ``StructuredTool`` and therefore exercises
the same LangGraph ``ToolNode`` path as a configured production tool without
touching a business system.
"""
from __future__ import annotations
import json
import os
import re
import threading
from pathlib import Path
from langchain.tools import tool
_OPERATION_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$")
_TEST_BLOCK_STARTED: threading.Event | None = None
_TEST_BLOCK_RELEASE: threading.Event | None = None
def configure_test_block(
*, started: threading.Event | None = None, release: threading.Event | None = None
) -> None:
"""Install a test-only barrier for lease contention tests.
The hook is inert unless a test explicitly supplies both events. It keeps
the write inside the real synchronous ToolNode call while allowing the
second MAF run to observe the first target lease as ``running``.
"""
global _TEST_BLOCK_STARTED, _TEST_BLOCK_RELEASE
_TEST_BLOCK_STARTED = started
_TEST_BLOCK_RELEASE = release
def clear_test_block() -> None:
configure_test_block()
@tool("maf_test_outbox_write", parse_docstring=True)
def maf_test_outbox_write(operation_id: str, value: str) -> dict[str, object]:
"""Append one controlled write record to the test outbox.
Args:
operation_id: Stable idempotency identifier for the test action.
value: Test payload written only to the temporary outbox.
"""
outbox_dir = (os.getenv("MAF_E2E_OUTBOX_DIR") or "").strip()
if not outbox_dir:
raise RuntimeError("MAF_E2E_OUTBOX_DIR is not configured")
if not _OPERATION_ID.fullmatch(operation_id):
raise ValueError("invalid test outbox operation id")
if _TEST_BLOCK_STARTED is not None and _TEST_BLOCK_RELEASE is not None:
_TEST_BLOCK_STARTED.set()
_TEST_BLOCK_RELEASE.wait()
directory = Path(outbox_dir).resolve()
directory.mkdir(parents=True, exist_ok=True)
record_path = directory / f"{operation_id}.jsonl"
with record_path.open("a", encoding="utf-8", newline="") as record_file:
record_file.write(
json.dumps({"operation_id": operation_id, "value": value}, ensure_ascii=False)
+ "\n"
)
return {
"executed": True,
"external_object_id": operation_id,
"safe_summary": "test outbox write completed",
}
__all__ = ["clear_test_block", "configure_test_block", "maf_test_outbox_write"]
@@ -11,6 +11,7 @@ under ``confirm_high_risk``).
from __future__ import annotations
from collections.abc import Mapping
from typing import Any
_DEFAULT_SIDE_EFFECT = "write"
@@ -42,15 +43,52 @@ def resolve_tool_metadata(
tool_name: str,
*,
config_extra: dict[str, Any] | None = None,
) -> dict[str, str]:
"""Return ``{name, tool_name, side_effect, risk_level}`` for one tool."""
maf_metadata: Mapping[str, Any] | None = None,
) -> dict[str, Any]:
"""Return trusted metadata for one tool.
Precedence is intentionally server-only and explicit:
1. MAF deployment metadata keyed by the exact runtime tool name;
2. existing server ``ToolConfig`` extras;
3. the curated built-in allow-list;
4. conservative ``write`` / ``R3`` fallback.
``maf_metadata`` is passed by the application while building a frozen
capability snapshot. It is never accepted from a session request or a
model message.
"""
side = _DEFAULT_SIDE_EFFECT
risk = _DEFAULT_RISK_LEVEL
if config_extra:
if config_extra.get("side_effect"):
side = str(config_extra["side_effect"])
if config_extra.get("risk_level"):
risk = str(config_extra["risk_level"])
target_key_fields: list[str] = []
target_key_namespace = "default"
registered = maf_metadata.get(tool_name) if maf_metadata else None
if registered is not None:
candidate_side = registered.get("side_effect") if isinstance(registered, Mapping) else getattr(registered, "side_effect", None)
candidate_risk = registered.get("risk_level") if isinstance(registered, Mapping) else getattr(registered, "risk_level", None)
if candidate_side in {"read", "skill", "write"}:
side = str(candidate_side)
if candidate_risk in {"R0", "R1", "R2", "R3", "R4"}:
risk = str(candidate_risk)
candidate_fields = registered.get("target_key_fields") if isinstance(registered, Mapping) else getattr(registered, "target_key_fields", None)
candidate_namespace = registered.get("target_key_namespace") if isinstance(registered, Mapping) else getattr(registered, "target_key_namespace", None)
if isinstance(candidate_fields, list) and all(isinstance(item, str) for item in candidate_fields):
target_key_fields = list(candidate_fields)
if isinstance(candidate_namespace, str) and candidate_namespace:
target_key_namespace = candidate_namespace
elif config_extra:
candidate_side = config_extra.get("side_effect")
candidate_risk = config_extra.get("risk_level")
if candidate_side in {"read", "skill", "write"}:
side = str(candidate_side)
if candidate_risk in {"R0", "R1", "R2", "R3", "R4"}:
risk = str(candidate_risk)
candidate_fields = config_extra.get("target_key_fields")
candidate_namespace = config_extra.get("target_key_namespace")
if isinstance(candidate_fields, list) and all(isinstance(item, str) for item in candidate_fields):
target_key_fields = list(candidate_fields)
if isinstance(candidate_namespace, str) and candidate_namespace:
target_key_namespace = candidate_namespace
elif tool_name in _BUILTIN_METADATA:
side, risk = _BUILTIN_METADATA[tool_name]
return {
@@ -58,4 +96,6 @@ def resolve_tool_metadata(
"tool_name": tool_name,
"side_effect": side,
"risk_level": risk,
"target_key_fields": target_key_fields,
"target_key_namespace": target_key_namespace,
}