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
+151
@@ -0,0 +1,151 @@
|
||||
"""Configuration for the WriteGuard middleware.
|
||||
|
||||
The WriteGuard middleware intercepts external-write tool calls so they can be
|
||||
recorded for human approval **before** the underlying tool executes. It is
|
||||
activated per-run via a ``maf_run_id`` flag in the run context, so legacy
|
||||
single-agent runs are completely unaffected (the middleware no-ops).
|
||||
|
||||
This module is harness-only: it defines the config schema and the
|
||||
``WriteGuardPolicy`` / ``WriteGuardInterceptor`` Protocols. The concrete
|
||||
implementations live in the application layer (``app.maf_roundtable``) and are
|
||||
resolved at runtime via ``resolve_variable`` from the ``use`` dotted path.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any, Protocol, runtime_checkable
|
||||
|
||||
from pydantic import BaseModel, Field
|
||||
|
||||
|
||||
class WriteGuardProviderConfig(BaseModel):
|
||||
"""Configuration for the application-layer WriteGuard implementations.
|
||||
|
||||
``policy_use`` resolves to a callable/class implementing
|
||||
``WriteGuardPolicy``; ``interceptor_use`` resolves to one implementing
|
||||
``WriteGuardInterceptor``. Both are resolved lazily by the harness via
|
||||
``deerflow.reflection.resolve_variable`` so the harness never imports
|
||||
``app.*``.
|
||||
"""
|
||||
|
||||
policy_use: str = Field(
|
||||
description="Dotted path to the WriteGuardPolicy factory, e.g. 'app.maf_roundtable.write_guard_bridge:make_policy'"
|
||||
)
|
||||
interceptor_use: str = Field(
|
||||
description="Dotted path to the WriteGuardInterceptor factory, e.g. 'app.maf_roundtable.write_guard_bridge:make_interceptor'"
|
||||
)
|
||||
config: dict = Field(default_factory=dict, description="Implementation-specific settings passed as kwargs")
|
||||
|
||||
|
||||
class WriteGuardConfig(BaseModel):
|
||||
"""Configuration for the WriteGuard middleware.
|
||||
|
||||
When ``enabled`` and a ``provider`` is configured, the harness appends a
|
||||
``WriteGuardMiddleware`` to the runtime middleware chain. The middleware
|
||||
itself only acts when the run context carries a ``maf_run_id`` flag —
|
||||
every other run is a pass-through.
|
||||
"""
|
||||
|
||||
enabled: bool = Field(default=False, description="Enable the WriteGuard middleware in the chain")
|
||||
provider: WriteGuardProviderConfig | None = Field(
|
||||
default=None, description="Application-layer policy/interceptor factories"
|
||||
)
|
||||
|
||||
|
||||
_write_guard_config: WriteGuardConfig | None = None
|
||||
|
||||
|
||||
def get_write_guard_config() -> WriteGuardConfig:
|
||||
"""Get the write-guard config, returning defaults if not loaded."""
|
||||
global _write_guard_config
|
||||
if _write_guard_config is None:
|
||||
_write_guard_config = WriteGuardConfig()
|
||||
return _write_guard_config
|
||||
|
||||
|
||||
def load_write_guard_config_from_dict(data: dict) -> WriteGuardConfig:
|
||||
"""Load write-guard config from a dict (called during AppConfig loading)."""
|
||||
global _write_guard_config
|
||||
_write_guard_config = WriteGuardConfig.model_validate(data)
|
||||
return _write_guard_config
|
||||
|
||||
|
||||
def reset_write_guard_config() -> None:
|
||||
"""Reset the cached config instance. Used in tests to prevent singleton leaks."""
|
||||
global _write_guard_config
|
||||
_write_guard_config = None
|
||||
|
||||
|
||||
# ── Protocols (harness ↔ application contract) ─────────────────────────────
|
||||
|
||||
|
||||
@runtime_checkable
|
||||
class WriteGuardPolicy(Protocol):
|
||||
"""Decides whether a given tool call must be intercepted for approval.
|
||||
|
||||
Implementations are constructed by the application layer and passed into
|
||||
the harness ``WriteGuardMiddleware``. They must NOT import deerflow.*
|
||||
(the harness owns this Protocol definition).
|
||||
"""
|
||||
|
||||
def should_intercept(self, tool_name: str, args: Any, run_context: dict | None = None) -> bool: # noqa: ANN401
|
||||
"""Return True if the tool call must be recorded for approval before execution.
|
||||
|
||||
``run_context`` (the shared run-context dict) lets the policy distinguish
|
||||
reads from writes using the frozen capability snapshot + write policy, so
|
||||
read tools are never intercepted (they pass straight through, including
|
||||
on the sync path) while writes are gated by the active write policy.
|
||||
"""
|
||||
...
|
||||
|
||||
|
||||
@runtime_checkable
|
||||
class WriteGuardInterceptor(Protocol):
|
||||
"""Records an intercepted write tool call (action + approval + audit event).
|
||||
|
||||
The interceptor is responsible for the full create-pending-action flow
|
||||
(see ``store.create_pending_action_bundle``). It receives the run context
|
||||
dict (the same one ``request.runtime.context`` exposes) so it can resolve
|
||||
the current ``session_id`` / ``run_id`` / ``agent_id`` / ``turn_index``
|
||||
and the write policy. It returns a dict describing the interception
|
||||
outcome so the middleware can build the ToolMessage the model sees in
|
||||
place of the real tool result.
|
||||
|
||||
Expected return shape::
|
||||
|
||||
{
|
||||
"status": "approval_required" | "allowed",
|
||||
"action_id": "<id when approval_required>",
|
||||
"approval_id": "<id when approval_required>",
|
||||
"tool_name": "<name>",
|
||||
}
|
||||
"""
|
||||
|
||||
async def intercept(
|
||||
self,
|
||||
*,
|
||||
tool_name: str,
|
||||
args: Any, # noqa: ANN401
|
||||
tool_call_id: str,
|
||||
run_context: dict,
|
||||
) -> dict[str, Any]:
|
||||
"""Record the tool call for approval. Never executes the real tool."""
|
||||
...
|
||||
|
||||
async def validate_approved_action(
|
||||
self,
|
||||
*,
|
||||
tool_name: str,
|
||||
run_context: dict,
|
||||
) -> bool:
|
||||
"""Validate a post-approval deterministic execution before it runs.
|
||||
|
||||
Called on the async path when the run context binds ``maf_approved_tool``
|
||||
+ ``maf_approved_action_id``. Must query the stored action and confirm:
|
||||
its status is ``running`` (the executor already occupied it), it belongs
|
||||
to the current ``run_id`` / ``session_id`` / ``agent_id``, and its
|
||||
``tool_name`` matches. Returns True only when all hold — the middleware
|
||||
fails closed (blocks the call) otherwise. Field-existence alone is NOT
|
||||
sufficient.
|
||||
"""
|
||||
...
|
||||
Reference in new issue
Block a user