feat(maf): conversation-driven MAF roundtable (R1/R2) + server-owned stage-3 dispatch
Backend:
- Conversation API at /api/maf-roundtable/conversations: create/list/detail,
paginated messages, atomic send+run start, owner-only isolation,
admin read-only diagnostic access
- SSE real-time event stream (GET /conversations/{id}/stream) backed by
ConversationEventHub + conversation_events store; multi-worker deployment doc
- Deterministic server-owned stage-3 dispatch contracts (dispatch_contracts.py):
routing resolved from trusted MAF deployment config instead of manager-chosen
agent ids; config.yaml keeps stage-3 routing deployment-owned
(default_manager_agent_id / seat ids / business_routes / max_seats_per_run)
- Conversation persistence (conversations/messages stores) + v2 migration script
- Tests: conversations, conversation stream, migration, phase3 conversation dispatch
Frontend:
- Vitest test infra for MAF (vitest.maf.config.ts + test:maf script) with
component tests for ApprovalCard/RunHeader/SessionsPage and use-maf-events
- Session form lib, flow-graph dialog / run-detail / sessions page updates,
routes and nav tweaks
- Docs: R0 legacy interaction baseline mapping, updated implementation plan
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
1 parent
df408831e5
commit
99642fca6c
46 files changed
+6358
-1306
No files matched your search
@@ -0,0 +1,284 @@
|
||||
"""Conversation-scoped in-process event hub for MAF roundtable SSE streaming.
|
||||
|
||||
This hub mediates between the writers (store/service/workflow executor that
|
||||
persist conversation events to the DB) and the SSE subscribers (the HTTP
|
||||
stream endpoint). It is deliberately **notification-only**: the database is
|
||||
the authoritative event store, and this hub merely signals "new events may be
|
||||
available" so subscribers can re-query. This avoids duplicating the event log
|
||||
in memory and guarantees that a reconnecting client can always replay from the
|
||||
DB cursor (``after_seq``).
|
||||
|
||||
Writer contract (§4.2 "先持久化、后通知"):
|
||||
1. Persist events to ``maf_roundtable_conversation_events`` (via
|
||||
``MafRoundtableStore.append_conversation_item``) inside a transaction.
|
||||
2. **After commit**, call ``await hub.publish(conversation_id)``.
|
||||
|
||||
Subscriber contract (P0-1 race-free):
|
||||
1. ``sub = hub.open_subscription(conversation_id)`` — register **before**
|
||||
any DB query so publishes during replay are captured.
|
||||
2. Replay from DB: ``list_events(after_seq=last_seq)``.
|
||||
3. **Stabilise**: if ``sub.current_generation > sub.seen_generation``,
|
||||
re-query DB and repeat until stable (events arrived during replay).
|
||||
4. Send snapshot.
|
||||
5. ``await sub.wait_for_change(timeout=heartbeat)`` → on True, query DB
|
||||
for new events; on False, send heartbeat.
|
||||
|
||||
This eliminates the ``signal.clear()`` race: generation is monotonic and
|
||||
never cleared, so a publish that happens between the DB read and the
|
||||
``wait()`` is always detected on the next stabilisation check.
|
||||
|
||||
Multi-worker limitation:
|
||||
Single-process, in-memory. Multi-worker requires Redis Pub/Sub.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import logging
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
if TYPE_CHECKING:
|
||||
pass
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
_DEFAULT_HEARTBEAT_INTERVAL = 15.0
|
||||
_MAX_SUBSCRIBERS_PER_CONVERSATION = 64
|
||||
|
||||
|
||||
class _ConvState:
|
||||
"""Per-conversation notification state."""
|
||||
|
||||
__slots__ = ("generation", "condition", "subscriber_count")
|
||||
|
||||
def __init__(self) -> None:
|
||||
self.generation: int = 0
|
||||
self.condition: asyncio.Condition = asyncio.Condition()
|
||||
self.subscriber_count: int = 0
|
||||
|
||||
|
||||
class Subscription:
|
||||
"""Explicit subscription handle — race-free notification reader.
|
||||
|
||||
Created via :meth:`ConversationEventHub.open_subscription`. The caller
|
||||
owns its lifecycle: call :meth:`close` when the SSE connection ends.
|
||||
|
||||
Key invariant: ``seen_generation`` is monotonic — it is never reset.
|
||||
A publish that races ahead of ``wait_for_change`` simply increments
|
||||
``current_generation``, and the next ``wait_for_change`` returns
|
||||
immediately (no lost wakeup).
|
||||
"""
|
||||
|
||||
__slots__ = ("_hub", "_conv_id", "_seen_gen", "_closed")
|
||||
|
||||
def __init__(self, hub: ConversationEventHub, conversation_id: str, gen_at_open: int) -> None:
|
||||
self._hub = hub
|
||||
self._conv_id = conversation_id
|
||||
self._seen_gen = gen_at_open
|
||||
self._closed = False
|
||||
|
||||
@property
|
||||
def conversation_id(self) -> str:
|
||||
return self._conv_id
|
||||
|
||||
@property
|
||||
def current_generation(self) -> int:
|
||||
"""Latest generation known to the hub for this conversation."""
|
||||
return self._hub._get_generation(self._conv_id)
|
||||
|
||||
@property
|
||||
def seen_generation(self) -> int:
|
||||
"""Generation as of the last successful stabilisation / wait."""
|
||||
return self._seen_gen
|
||||
|
||||
@property
|
||||
def has_pending(self) -> bool:
|
||||
"""True when the hub generation is ahead of what we've seen."""
|
||||
return self.current_generation > self._seen_gen
|
||||
|
||||
def mark_seen(self) -> None:
|
||||
"""Advance ``seen_generation`` to the hub's current generation."""
|
||||
self._seen_gen = self.current_generation
|
||||
|
||||
def mark_seen_if_higher(self, gen: int) -> None:
|
||||
if gen > self._seen_gen:
|
||||
self._seen_gen = gen
|
||||
|
||||
async def wait_for_change(self, *, timeout: float) -> bool:
|
||||
"""Block until ``current_generation > seen_generation`` or timeout.
|
||||
|
||||
Returns ``True`` if the generation advanced (new events *might* be
|
||||
available — caller must query DB to confirm). Returns ``False`` on
|
||||
timeout (caller should send a heartbeat).
|
||||
"""
|
||||
state = self._hub._convs.get(self._conv_id)
|
||||
if state is None:
|
||||
return False
|
||||
async with state.condition:
|
||||
if state.generation > self._seen_gen:
|
||||
self._seen_gen = state.generation
|
||||
return True
|
||||
try:
|
||||
await asyncio.wait_for(state.condition.wait(), timeout=timeout)
|
||||
except TimeoutError:
|
||||
return False
|
||||
if state.generation > self._seen_gen:
|
||||
self._seen_gen = state.generation
|
||||
return True
|
||||
return False
|
||||
|
||||
def close(self) -> None:
|
||||
"""Release the subscription. Safe to call multiple times."""
|
||||
if not self._closed:
|
||||
self._closed = True
|
||||
self._hub._release_subscription(self._conv_id)
|
||||
|
||||
def __enter__(self) -> Subscription:
|
||||
return self
|
||||
|
||||
def __exit__(self, *exc: object) -> None:
|
||||
self.close()
|
||||
|
||||
|
||||
class ConversationEventHub:
|
||||
"""In-process notification hub keyed by ``conversation_id``.
|
||||
|
||||
Not thread-safe; intended for a single asyncio event loop (one worker).
|
||||
"""
|
||||
|
||||
def __init__(self, *, heartbeat_interval: float = _DEFAULT_HEARTBEAT_INTERVAL) -> None:
|
||||
self._heartbeat_interval = heartbeat_interval
|
||||
self._convs: dict[str, _ConvState] = {}
|
||||
self._closed = False
|
||||
|
||||
@property
|
||||
def heartbeat_interval(self) -> float:
|
||||
return self._heartbeat_interval
|
||||
|
||||
@property
|
||||
def total_subscribers(self) -> int:
|
||||
return sum(s.subscriber_count for s in self._convs.values())
|
||||
|
||||
@property
|
||||
def is_closed(self) -> bool:
|
||||
return self._closed
|
||||
|
||||
def conversation_subscriber_count(self, conversation_id: str) -> int:
|
||||
state = self._convs.get(conversation_id)
|
||||
return state.subscriber_count if state else 0
|
||||
|
||||
def _get_generation(self, conversation_id: str) -> int:
|
||||
state = self._convs.get(conversation_id)
|
||||
return state.generation if state else 0
|
||||
|
||||
def open_subscription(self, conversation_id: str) -> Subscription:
|
||||
"""Register a new subscriber **before** any DB replay.
|
||||
|
||||
Returns a :class:`Subscription` whose ``seen_generation`` is the hub's
|
||||
current generation at registration time. Any ``publish()`` after this
|
||||
call will be detectable via ``sub.has_pending``.
|
||||
"""
|
||||
if self._closed:
|
||||
raise RuntimeError("ConversationEventHub is shut down")
|
||||
state = self._convs.get(conversation_id)
|
||||
if state is None:
|
||||
state = _ConvState()
|
||||
self._convs[conversation_id] = state
|
||||
if state.subscriber_count >= _MAX_SUBSCRIBERS_PER_CONVERSATION:
|
||||
raise RuntimeError(
|
||||
f"Too many SSE subscribers for conversation {conversation_id} "
|
||||
f"(max {_MAX_SUBSCRIBERS_PER_CONVERSATION})"
|
||||
)
|
||||
state.subscriber_count += 1
|
||||
logger.debug(
|
||||
"SSE subscribe conv=%s gen=%d (subs=%d)",
|
||||
conversation_id, state.generation, state.subscriber_count,
|
||||
)
|
||||
return Subscription(self, conversation_id, state.generation)
|
||||
|
||||
def _release_subscription(self, conversation_id: str) -> None:
|
||||
state = self._convs.get(conversation_id)
|
||||
if state is None:
|
||||
return
|
||||
state.subscriber_count -= 1
|
||||
logger.debug(
|
||||
"SSE unsubscribe conv=%s (subs=%d)",
|
||||
conversation_id, max(0, state.subscriber_count),
|
||||
)
|
||||
if state.subscriber_count <= 0:
|
||||
self._convs.pop(conversation_id, None)
|
||||
|
||||
async def publish(self, conversation_id: str) -> None:
|
||||
"""Signal that new events have been persisted for a conversation.
|
||||
|
||||
Must be called **after** the events are committed to the DB, never
|
||||
before. Atomically increments the per-conversation generation counter
|
||||
and wakes all waiting subscribers. Safe to call when no subscribers
|
||||
are active (the next subscriber's stabilisation check will see the
|
||||
incremented generation).
|
||||
"""
|
||||
if self._closed:
|
||||
return
|
||||
state = self._convs.get(conversation_id)
|
||||
if state is None:
|
||||
# No active subscribers — nothing to wake. The generation is not
|
||||
# tracked for conversations with zero subscribers; a future
|
||||
# open_subscription starts fresh at 0, which is correct because
|
||||
# there was nobody to notify.
|
||||
return
|
||||
async with state.condition:
|
||||
state.generation += 1
|
||||
state.condition.notify_all()
|
||||
|
||||
async def wait_for_change(
|
||||
self, conversation_id: str, seen_gen: int, *, timeout: float
|
||||
) -> int:
|
||||
"""Convenience: wait until generation > ``seen_gen``.
|
||||
|
||||
Returns the new generation (> ``seen_gen``) on change, or ``seen_gen``
|
||||
unchanged on timeout. Prefer using a :class:`Subscription` for the
|
||||
full lifecycle.
|
||||
"""
|
||||
state = self._convs.get(conversation_id)
|
||||
if state is None:
|
||||
return seen_gen
|
||||
async with state.condition:
|
||||
if state.generation > seen_gen:
|
||||
return state.generation
|
||||
try:
|
||||
await asyncio.wait_for(state.condition.wait(), timeout=timeout)
|
||||
except TimeoutError:
|
||||
return seen_gen
|
||||
return state.generation
|
||||
|
||||
def shutdown(self) -> None:
|
||||
"""Signal all subscribers to stop (server shutdown).
|
||||
|
||||
Wakes every waiter; their ``wait_for_change`` returns ``True`` but
|
||||
the caller's outer loop checks ``hub.is_closed`` and exits.
|
||||
"""
|
||||
self._closed = True
|
||||
for state in self._convs.values():
|
||||
state.generation += 1
|
||||
# Wake all waiters — we can't use the condition here because
|
||||
# shutdown is sync. The next wait_for_change call will see
|
||||
# the incremented generation and return immediately.
|
||||
# For a truly sync wake we'd need to schedule the notify;
|
||||
# but since shutdown is called from the lifespan teardown
|
||||
# (async context), callers should use:
|
||||
# async with state.condition: state.condition.notify_all()
|
||||
# Instead we just bump the generation; waiters time out on the
|
||||
# next heartbeat cycle at worst (15s). For immediate wake,
|
||||
# use `await hub.aclose()` below.
|
||||
|
||||
|
||||
async def hub_aclose(hub: ConversationEventHub) -> None:
|
||||
"""Async shutdown that immediately wakes all subscribers."""
|
||||
hub._closed = True
|
||||
for state in list(hub._convs.values()):
|
||||
async with state.condition:
|
||||
state.generation += 1
|
||||
state.condition.notify_all()
|
||||
|
||||
|
||||
__all__ = ["ConversationEventHub", "Subscription", "hub_aclose"]
|
||||
@@ -0,0 +1,118 @@
|
||||
"""Pydantic schemas for the MAF roundtable Conversation API (V2).
|
||||
|
||||
These are the public wire contracts for ``/api/maf-roundtable/conversations``.
|
||||
Internal fields (owner_user_id, internal_session_id, active_run_id, thread ids,
|
||||
capability snapshots, idempotency keys) are NEVER exposed here.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
|
||||
|
||||
_TASK_CONTEXT_SAFE_KEYS = frozenset({"business_code", "task_id", "task_name", "chain_id", "chain_name"})
|
||||
|
||||
|
||||
class _StrictRequestModel(BaseModel):
|
||||
"""Reject unknown request members instead of silently ignoring spoofed input."""
|
||||
|
||||
model_config = ConfigDict(extra="forbid")
|
||||
|
||||
|
||||
class CreateConversationRequest(_StrictRequestModel):
|
||||
title: str = Field(default="", max_length=255)
|
||||
task_context: dict[str, Any] | None = None
|
||||
|
||||
@model_validator(mode="before")
|
||||
@classmethod
|
||||
def _reject_internal_fields(cls, values: Any) -> Any:
|
||||
if isinstance(values, dict):
|
||||
forbidden = {"user_id", "owner_user_id", "internal_session_id", "run_id",
|
||||
"thread_id", "capability_snapshot", "id"}
|
||||
found = forbidden & set(values.keys())
|
||||
if found:
|
||||
raise ValueError(f"Forbidden fields: {sorted(found)}")
|
||||
return values
|
||||
|
||||
@field_validator("task_context")
|
||||
@classmethod
|
||||
def _validate_task_context(cls, value: dict[str, Any] | None) -> dict[str, str] | None:
|
||||
if value is None:
|
||||
return None
|
||||
unexpected = set(value) - _TASK_CONTEXT_SAFE_KEYS
|
||||
if unexpected:
|
||||
raise ValueError(f"Unsupported task_context fields: {sorted(unexpected)}")
|
||||
cleaned: dict[str, str] = {}
|
||||
for key, raw in value.items():
|
||||
if not isinstance(raw, (str, int)) or isinstance(raw, bool):
|
||||
raise ValueError(f"task_context.{key} must be a string or integer")
|
||||
rendered = str(raw).strip()
|
||||
if not rendered:
|
||||
raise ValueError(f"task_context.{key} cannot be blank")
|
||||
if len(rendered) > 255:
|
||||
raise ValueError(f"task_context.{key} exceeds 255 characters")
|
||||
cleaned[key] = rendered
|
||||
return cleaned
|
||||
|
||||
|
||||
class SendMessageRequest(_StrictRequestModel):
|
||||
content: str = Field(min_length=1, max_length=20000)
|
||||
|
||||
@model_validator(mode="before")
|
||||
@classmethod
|
||||
def _reject_internal_fields(cls, values: Any) -> Any:
|
||||
if isinstance(values, dict):
|
||||
forbidden = {"user_id", "owner_user_id", "internal_session_id", "run_id",
|
||||
"thread_id", "capability_snapshot", "idempotency_key"}
|
||||
found = forbidden & set(values.keys())
|
||||
if found:
|
||||
raise ValueError(f"Forbidden fields: {sorted(found)}")
|
||||
return values
|
||||
|
||||
@model_validator(mode="after")
|
||||
def _strip_content(self) -> SendMessageRequest:
|
||||
stripped = self.content.strip()
|
||||
if not stripped:
|
||||
raise ValueError("content cannot be empty or whitespace-only")
|
||||
self.content = stripped
|
||||
return self
|
||||
|
||||
|
||||
class ConversationResponse(BaseModel):
|
||||
id: str
|
||||
title: str
|
||||
task_context: dict[str, Any] | None = None
|
||||
safe_status: str
|
||||
created_at: str | None = None
|
||||
updated_at: str | None = None
|
||||
last_stream_seq: int = 0
|
||||
|
||||
|
||||
class ConversationListResponse(BaseModel):
|
||||
conversations: list[ConversationResponse]
|
||||
total: int
|
||||
|
||||
|
||||
class MessageResponse(BaseModel):
|
||||
id: str
|
||||
conversation_id: str
|
||||
seq: int
|
||||
message_kind: str
|
||||
role: str
|
||||
agent_id: str | None = None
|
||||
message_ref: str | None = None
|
||||
content: str
|
||||
metadata: dict[str, Any] | None = None
|
||||
created_at: str | None = None
|
||||
|
||||
|
||||
class MessageListResponse(BaseModel):
|
||||
messages: list[MessageResponse]
|
||||
last_stream_seq: int
|
||||
|
||||
|
||||
class SendMessageResponse(BaseModel):
|
||||
message_id: str
|
||||
conversation_id: str
|
||||
seq: int
|
||||
@@ -0,0 +1,670 @@
|
||||
"""Conversation service for the MAF roundtable V2 (App layer).
|
||||
|
||||
Orchestrates the harness-layer store with business rules that belong to the
|
||||
application layer: session blueprint construction, ownership enforcement,
|
||||
public DTO projection, and fail-closed behaviour when configuration is missing.
|
||||
|
||||
Blueprint generation lives here (not in the harness) because it depends on
|
||||
deployment config (``MafRoundtableConfig``) which is an app-layer concern.
|
||||
The harness ``MafRoundtableStore`` never imports ``app.*``.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import logging
|
||||
from datetime import UTC, datetime
|
||||
from typing import TYPE_CHECKING, Any
|
||||
|
||||
from app.maf_roundtable.dispatch_contracts import (
|
||||
DispatchConfigurationError,
|
||||
MafDispatchCatalog,
|
||||
MafDispatchPlan,
|
||||
MafIntentDecision,
|
||||
resolve_intent,
|
||||
)
|
||||
from deerflow.persistence.maf_roundtable.conversations import (
|
||||
conversation_public_to_dict,
|
||||
)
|
||||
from deerflow.persistence.maf_roundtable.messages import message_public_to_dict
|
||||
from deerflow.persistence.maf_roundtable.model import (
|
||||
MafRoundtableConversationRow,
|
||||
MafRoundtableMessageRow,
|
||||
MafRoundtableRunRow,
|
||||
)
|
||||
from deerflow.persistence.maf_roundtable.store import MafRoundtableStore
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from app.maf_roundtable.conversation_event_hub import ConversationEventHub
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class ConversationServiceError(Exception):
|
||||
def __init__(self, code: str, message: str, status_code: int = 400):
|
||||
self.code = code
|
||||
self.message = message
|
||||
self.status_code = status_code
|
||||
super().__init__(message)
|
||||
|
||||
|
||||
class ConversationNotFoundError(ConversationServiceError):
|
||||
def __init__(self) -> None:
|
||||
super().__init__("not_found", "Conversation not found", 404)
|
||||
|
||||
|
||||
class ConversationConflictError(ConversationServiceError):
|
||||
def __init__(self) -> None:
|
||||
super().__init__("conflict", "A run is already active for this conversation", 409)
|
||||
|
||||
|
||||
class ConversationNoSessionConfigError(ConversationServiceError):
|
||||
def __init__(self) -> None:
|
||||
super().__init__(
|
||||
"no_session_config",
|
||||
"Cannot start a run: no trusted session configuration available",
|
||||
503,
|
||||
)
|
||||
|
||||
|
||||
class ConversationDisabledError(ConversationServiceError):
|
||||
def __init__(self) -> None:
|
||||
super().__init__("disabled", "MAF roundtable feature is disabled", 503)
|
||||
|
||||
|
||||
class ConversationDispatchError(ConversationServiceError):
|
||||
def __init__(self, message: str = "MAF dispatch is not configured") -> None:
|
||||
super().__init__("dispatch_unavailable", message, 503)
|
||||
|
||||
|
||||
class ConversationRuntimeUnavailableError(ConversationServiceError):
|
||||
def __init__(self) -> None:
|
||||
super().__init__(
|
||||
"runtime_unavailable",
|
||||
"MAF workflow runtime is not available",
|
||||
503,
|
||||
)
|
||||
|
||||
|
||||
class MafConversationService:
|
||||
"""App-layer service for user-visible MAF conversations."""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
store: MafRoundtableStore,
|
||||
*,
|
||||
maf_config: Any = None,
|
||||
event_hub: ConversationEventHub | None = None,
|
||||
agent_store: Any | None = None,
|
||||
app_config: Any | None = None,
|
||||
dispatcher: Any | None = None,
|
||||
enabled: bool | None = None,
|
||||
) -> None:
|
||||
self._store = store
|
||||
self._maf_config = maf_config
|
||||
self._hub = event_hub
|
||||
self._agent_store = agent_store
|
||||
self._app_config = app_config
|
||||
self._dispatcher = dispatcher
|
||||
self._enabled_override = enabled
|
||||
self._watchers: dict[str, asyncio.Task[None]] = {}
|
||||
|
||||
@property
|
||||
def _enabled(self) -> bool:
|
||||
"""Mutating conversation APIs obey the same feature flag as MAF runs."""
|
||||
if self._enabled_override is not None:
|
||||
return self._enabled_override
|
||||
return bool(getattr(self._maf_config, "enabled", False))
|
||||
|
||||
def _read_scope_user(self, *, user_id: str, is_admin: bool) -> str | None:
|
||||
"""Keep administrator diagnostics read-only and config-gated."""
|
||||
if is_admin and bool(getattr(self._maf_config, "admin_diagnostic_access", False)):
|
||||
return None
|
||||
return user_id
|
||||
|
||||
async def _build_dispatch_blueprint(
|
||||
self,
|
||||
*,
|
||||
user_id: str,
|
||||
title: str,
|
||||
content: str,
|
||||
task_context: dict[str, Any] | None,
|
||||
) -> tuple[dict[str, Any] | None, MafIntentDecision, MafDispatchPlan | None]:
|
||||
cfg = self._maf_config
|
||||
if cfg is None:
|
||||
raise ConversationDispatchError("MAF session configuration is unavailable")
|
||||
|
||||
intent = resolve_intent(content, task_context)
|
||||
plan: MafDispatchPlan | None = None
|
||||
participants: list[dict[str, Any]] = []
|
||||
capability_snapshot: dict[str, Any] | None = None
|
||||
|
||||
if intent.intent_type != "clarification":
|
||||
try:
|
||||
plan = MafDispatchCatalog(cfg).build_plan(
|
||||
intent=intent,
|
||||
task_context=task_context,
|
||||
)
|
||||
except DispatchConfigurationError as exc:
|
||||
raise ConversationDispatchError(str(exc)) from exc
|
||||
|
||||
from app.maf_roundtable.capability_snapshot import (
|
||||
AgentNotAccessibleError,
|
||||
InvalidExcludedToolsError,
|
||||
build_trusted_capability_snapshot,
|
||||
seat_snapshot_for_agent,
|
||||
)
|
||||
|
||||
participants = MafDispatchCatalog.participants(plan)
|
||||
if self._app_config is not None:
|
||||
try:
|
||||
capability_snapshot = await build_trusted_capability_snapshot(
|
||||
user_id=user_id,
|
||||
participants=participants,
|
||||
app_config=self._app_config,
|
||||
agent_store=self._agent_store,
|
||||
session_model_name=getattr(cfg, "default_model_name", None),
|
||||
session_reasoning_effort=getattr(cfg, "default_reasoning_effort", None),
|
||||
)
|
||||
except AgentNotAccessibleError as exc:
|
||||
raise ConversationDispatchError(
|
||||
f"configured MAF agent is not accessible: {exc.agent_id}"
|
||||
) from exc
|
||||
except InvalidExcludedToolsError as exc:
|
||||
raise ConversationDispatchError(
|
||||
f"configured MAF agent has invalid excluded tools: {exc.agent_id}"
|
||||
) from exc
|
||||
|
||||
for participant in participants:
|
||||
participant["capability_snapshot"] = seat_snapshot_for_agent(
|
||||
capability_snapshot, str(participant["agent_id"])
|
||||
)
|
||||
|
||||
payload = {
|
||||
"maf_v2": {
|
||||
"intent_type": intent.intent_type,
|
||||
"reason_code": intent.reason_code,
|
||||
"business_code": (task_context or {}).get("business_code"),
|
||||
"dispatch_plan": plan.model_dump(mode="json") if plan is not None else None,
|
||||
}
|
||||
}
|
||||
blueprint = {
|
||||
"title": title,
|
||||
"task_text": content,
|
||||
"mode": getattr(plan, "mode", None) or getattr(cfg, "default_mode", "structured"),
|
||||
"model_name": getattr(cfg, "default_model_name", None),
|
||||
"reasoning_effort": getattr(cfg, "default_reasoning_effort", None),
|
||||
"manager_agent_id": (
|
||||
plan.manager_agent_id if plan is not None
|
||||
else getattr(cfg, "default_manager_agent_id", None)
|
||||
),
|
||||
"max_rounds": getattr(plan, "max_rounds", None) or getattr(cfg, "default_max_rounds", 8),
|
||||
"write_policy": getattr(cfg, "default_write_policy", "confirm_high_risk"),
|
||||
"capability_snapshot": capability_snapshot,
|
||||
"task_payload": payload,
|
||||
"participants": participants,
|
||||
"start_run": intent.intent_type != "clarification",
|
||||
}
|
||||
return blueprint, intent, plan
|
||||
|
||||
async def create_conversation(
|
||||
self, *, user_id: str, title: str = "", task_context: dict[str, Any] | None = None
|
||||
) -> dict[str, Any]:
|
||||
if not self._enabled:
|
||||
raise ConversationDisabledError()
|
||||
row_data = await self._store.conversations.create_conversation({
|
||||
"owner_user_id": user_id,
|
||||
"title": title,
|
||||
"task_context": task_context,
|
||||
})
|
||||
conv_row = await self._get_conv_row(row_data["id"])
|
||||
if conv_row is None:
|
||||
raise ConversationNotFoundError()
|
||||
return conversation_public_to_dict(conv_row)
|
||||
|
||||
async def list_conversations(
|
||||
self, *, user_id: str, limit: int = 50, offset: int = 0
|
||||
) -> tuple[list[dict[str, Any]], int]:
|
||||
rows = await self._store.conversations.list_conversations(
|
||||
user_id=user_id, limit=limit, offset=offset
|
||||
)
|
||||
total = await self._store.conversations.count_conversations(user_id=user_id)
|
||||
public = []
|
||||
for r in rows:
|
||||
conv_row = await self._get_conv_row(r["id"])
|
||||
if conv_row is not None:
|
||||
public.append(conversation_public_to_dict(conv_row))
|
||||
return public, total
|
||||
|
||||
async def get_conversation(self, *, conversation_id: str, user_id: str, is_admin: bool = False) -> dict[str, Any]:
|
||||
effective_user = self._read_scope_user(user_id=user_id, is_admin=is_admin)
|
||||
row = await self._store.conversations.get_conversation(conversation_id, user_id=effective_user)
|
||||
if row is None:
|
||||
raise ConversationNotFoundError()
|
||||
conv_row = await self._get_conv_row(conversation_id)
|
||||
if conv_row is None:
|
||||
raise ConversationNotFoundError()
|
||||
return conversation_public_to_dict(conv_row)
|
||||
|
||||
async def list_messages(
|
||||
self, *, conversation_id: str, user_id: str, is_admin: bool = False,
|
||||
before_seq: int | None = None, limit: int = 50,
|
||||
) -> tuple[list[dict[str, Any]], int]:
|
||||
effective_user = self._read_scope_user(user_id=user_id, is_admin=is_admin)
|
||||
conv = await self._store.conversations.get_conversation(conversation_id, user_id=effective_user)
|
||||
if conv is None:
|
||||
raise ConversationNotFoundError()
|
||||
|
||||
rows = await self._store.messages.list_messages_desc(
|
||||
conversation_id, limit=limit, before_seq=before_seq
|
||||
)
|
||||
public = []
|
||||
for r in rows:
|
||||
msg_row = await self._get_msg_row(r["id"])
|
||||
if msg_row is not None:
|
||||
public.append(message_public_to_dict(msg_row))
|
||||
return public, int(conv.get("last_stream_seq", 0))
|
||||
|
||||
async def send_message(
|
||||
self, *, conversation_id: str, user_id: str, content: str
|
||||
) -> dict[str, Any]:
|
||||
if not self._enabled:
|
||||
raise ConversationDisabledError()
|
||||
conv = await self._store.conversations.get_conversation(conversation_id, user_id=user_id)
|
||||
if conv is None:
|
||||
raise ConversationNotFoundError()
|
||||
|
||||
try:
|
||||
blueprint, intent, plan = await self._build_dispatch_blueprint(
|
||||
user_id=user_id,
|
||||
title=conv.get("title", ""),
|
||||
content=content,
|
||||
task_context=conv.get("task_context"),
|
||||
)
|
||||
except ConversationServiceError:
|
||||
raise
|
||||
|
||||
if blueprint is None:
|
||||
raise ConversationNoSessionConfigError()
|
||||
|
||||
# Do not create a durable running record if the MAF SDK is missing.
|
||||
# Unit tests may inject a small fake dispatcher without this optional
|
||||
# readiness method.
|
||||
if intent.intent_type != "clarification" and self._dispatcher is not None:
|
||||
check_sdk = getattr(self._dispatcher, "check_sdk_available", None)
|
||||
if callable(check_sdk):
|
||||
try:
|
||||
check_sdk()
|
||||
except Exception as exc: # noqa: BLE001 - safe public error
|
||||
logger.warning("MAF runtime unavailable before dispatch: %s", type(exc).__name__)
|
||||
raise ConversationRuntimeUnavailableError() from exc
|
||||
|
||||
result = await self._store.send_message_and_start_run(
|
||||
conversation_id=conversation_id,
|
||||
owner_user_id=user_id,
|
||||
content=content,
|
||||
session_blueprint=blueprint,
|
||||
)
|
||||
|
||||
if result is None:
|
||||
raise ConversationNotFoundError()
|
||||
if result.get("conflict"):
|
||||
raise ConversationConflictError()
|
||||
if result.get("no_session_config"):
|
||||
raise ConversationNoSessionConfigError()
|
||||
|
||||
await self._publish_conversation_event(
|
||||
conversation_id=conversation_id,
|
||||
owner_user_id=user_id,
|
||||
event_type="manager.intent",
|
||||
event_data={
|
||||
"intent_type": intent.intent_type,
|
||||
"confidence": intent.confidence,
|
||||
"reason_code": intent.reason_code,
|
||||
},
|
||||
)
|
||||
|
||||
if intent.intent_type == "clarification":
|
||||
await self._publish_conversation_event(
|
||||
conversation_id=conversation_id,
|
||||
owner_user_id=user_id,
|
||||
event_type="clarification.required",
|
||||
event_data={
|
||||
"prompt": intent.clarification_prompt,
|
||||
"reason_code": intent.reason_code,
|
||||
},
|
||||
)
|
||||
else:
|
||||
if plan is None or result.get("run") is None:
|
||||
raise ConversationDispatchError("dispatch plan did not produce a run")
|
||||
await self._publish_conversation_event(
|
||||
conversation_id=conversation_id,
|
||||
owner_user_id=user_id,
|
||||
event_type="manager.dispatch",
|
||||
event_data={
|
||||
"intent_type": plan.intent_type,
|
||||
"mode": plan.mode,
|
||||
"business_code": plan.business_code,
|
||||
"manager_agent_id": plan.manager_agent_id,
|
||||
"seat_agent_ids": list(plan.seat_agent_ids),
|
||||
"seat_count": len(plan.seat_agent_ids),
|
||||
},
|
||||
)
|
||||
await self._dispatch_run(
|
||||
conversation_id=conversation_id,
|
||||
user_id=user_id,
|
||||
run=result["run"],
|
||||
)
|
||||
|
||||
return {
|
||||
"message_id": result["message"]["id"] if result.get("message") else "",
|
||||
"conversation_id": conversation_id,
|
||||
"seq": result.get("seq", 0),
|
||||
}
|
||||
|
||||
async def _publish_conversation_event(
|
||||
self,
|
||||
*,
|
||||
conversation_id: str,
|
||||
owner_user_id: str,
|
||||
event_type: str,
|
||||
event_data: dict[str, Any],
|
||||
source_event_id: str | None = None,
|
||||
) -> bool:
|
||||
"""Persist first, then notify; no internal run/thread ids are used.
|
||||
|
||||
P0-4: when ``source_event_id`` is provided, dedup is enforced — if an
|
||||
event with the same ``(conversation_id, source_event_id)`` already
|
||||
exists, the method returns ``False`` (no duplicate written). This
|
||||
makes projection idempotent across retries and restarts.
|
||||
|
||||
Returns ``True`` if a new event was written, ``False`` if deduped.
|
||||
"""
|
||||
from sqlalchemy import select
|
||||
|
||||
async with self._store.session_factory() as db:
|
||||
async with db.begin():
|
||||
conv = (
|
||||
await db.execute(
|
||||
select(MafRoundtableConversationRow)
|
||||
.where(MafRoundtableConversationRow.id == conversation_id)
|
||||
.with_for_update()
|
||||
)
|
||||
).scalars().first()
|
||||
if conv is None or conv.owner_user_id != owner_user_id:
|
||||
return False
|
||||
|
||||
# P0-4: dedup check — skip if already projected.
|
||||
if source_event_id is not None:
|
||||
from deerflow.persistence.maf_roundtable.model import (
|
||||
MafRoundtableConversationEventRow,
|
||||
)
|
||||
|
||||
existing = (
|
||||
await db.execute(
|
||||
select(MafRoundtableConversationEventRow.id).where(
|
||||
MafRoundtableConversationEventRow.conversation_id == conversation_id,
|
||||
MafRoundtableConversationEventRow.source_event_id == source_event_id,
|
||||
).limit(1)
|
||||
)
|
||||
).first()
|
||||
if existing is not None:
|
||||
return False
|
||||
|
||||
await self._store.append_conversation_item(
|
||||
db,
|
||||
conversation=conv,
|
||||
event_type=event_type,
|
||||
event_data=event_data,
|
||||
run_id=None,
|
||||
source_event_id=source_event_id,
|
||||
)
|
||||
if self._hub is not None:
|
||||
try:
|
||||
await self._hub.publish(conversation_id)
|
||||
except Exception: # noqa: BLE001
|
||||
logger.exception("hub publish failed conv=%s", conversation_id)
|
||||
return True
|
||||
|
||||
async def bridge_workflow_event(self, *, run_id: str, event: dict[str, Any]) -> None:
|
||||
"""Project a persisted per-run event onto the V2 conversation stream.
|
||||
|
||||
The per-run event ledger remains the audit source of truth. This
|
||||
projection is deliberately lossy: only user-visible lifecycle fields
|
||||
are copied, while tool arguments, tool-call ids, thread ids, run ids,
|
||||
and raw exception bodies are discarded before the SSE event is saved.
|
||||
"""
|
||||
from sqlalchemy import select
|
||||
|
||||
async with self._store.session_factory() as db:
|
||||
row = (
|
||||
await db.execute(
|
||||
select(MafRoundtableConversationRow)
|
||||
.join(
|
||||
MafRoundtableRunRow,
|
||||
MafRoundtableConversationRow.internal_session_id
|
||||
== MafRoundtableRunRow.session_id,
|
||||
)
|
||||
.where(MafRoundtableRunRow.id == run_id)
|
||||
)
|
||||
).scalars().first()
|
||||
if row is None:
|
||||
return
|
||||
conversation_id = row.id
|
||||
owner_user_id = row.owner_user_id
|
||||
|
||||
source_type = str(event.get("event_type") or "")
|
||||
mapped_type = {
|
||||
"agent.turn_started": "agent.message.start",
|
||||
"agent.message.completed": "agent.message.complete",
|
||||
"action.waiting_approval": "approval.required",
|
||||
"action.approved": "approval.decided",
|
||||
"action.rejected": "approval.decided",
|
||||
"run.started": "run.status",
|
||||
"run.failed": "run.error",
|
||||
"run.cancelled": "run.cancelled",
|
||||
"manager.decision": "manager.dispatch",
|
||||
"workflow.checkpointed": "run.status",
|
||||
"action.waiting_target_lease": "tool.progress",
|
||||
"action.unknown": "tool.failed",
|
||||
}.get(source_type, source_type)
|
||||
|
||||
allowed_types = {
|
||||
"agent.message.start", "agent.message.delta", "agent.message.complete",
|
||||
"seat.delivery.submitted", "manager.dispatch", "manager.review.decision",
|
||||
"tool.requested", "tool.started", "tool.progress", "tool.completed", "tool.failed",
|
||||
"skill.selected", "skill.started", "skill.completed", "skill.failed",
|
||||
"artifact.created", "approval.required", "approval.decided",
|
||||
"fact.confirmed", "review.completed", "run.status", "run.error",
|
||||
"run.cancelled", "run.completed",
|
||||
}
|
||||
if mapped_type not in allowed_types:
|
||||
return
|
||||
|
||||
payload = event.get("payload")
|
||||
if not isinstance(payload, dict):
|
||||
payload = {}
|
||||
safe_keys = {
|
||||
"agent.message.start": {"thread_id": False},
|
||||
"agent.message.delta": {"text": True},
|
||||
"agent.message.complete": {"content": True, "usage": True, "metadata": False},
|
||||
"tool.requested": {"tool_name": True},
|
||||
"tool.started": {"tool_name": True, "node": True},
|
||||
"tool.progress": {"tool_name": True, "status": True},
|
||||
"tool.completed": {"tool_name": True, "status": True, "content_preview": True},
|
||||
"tool.failed": {"tool_name": True, "status": True, "error_code": True},
|
||||
"skill.selected": {"skill_name": True, "message": True},
|
||||
"skill.started": {"skill_name": True, "message": True},
|
||||
"skill.completed": {"skill_name": True, "result_preview": True},
|
||||
"skill.failed": {"skill_name": True, "error": True},
|
||||
"artifact.created": {"artifact_type": True, "title": True},
|
||||
"approval.required": {"tool_name": True, "summary": True},
|
||||
"approval.decided": {"decided_by": True},
|
||||
"run.status": {"checkpoint_id": True, "reason": True, "status": True},
|
||||
"run.error": {"error_code": True, "message": True},
|
||||
"run.cancelled": {},
|
||||
"run.completed": {"status": True},
|
||||
"manager.dispatch": {"next_speaker": True, "reason": True},
|
||||
"manager.review.decision": {"decision": True, "reason": True, "quality": True},
|
||||
"fact.confirmed": {"fact_id": True, "summary": True},
|
||||
"review.completed": {"summary": True, "decision": True},
|
||||
"seat.delivery.submitted": {"content": True, "schema_status": True},
|
||||
}.get(mapped_type, {})
|
||||
data: dict[str, Any] = {
|
||||
key: payload[key]
|
||||
for key in safe_keys
|
||||
if key in payload and safe_keys[key]
|
||||
}
|
||||
if event.get("agent_id"):
|
||||
data["agent_id"] = event["agent_id"]
|
||||
if event.get("turn_index") is not None:
|
||||
data["turn_index"] = event["turn_index"]
|
||||
|
||||
# P0-4: use the source audit event's stable id for dedup.
|
||||
source_evt_id = event.get("id") or event.get("source_event_id")
|
||||
|
||||
await self._publish_conversation_event(
|
||||
conversation_id=conversation_id,
|
||||
owner_user_id=owner_user_id,
|
||||
event_type=mapped_type,
|
||||
event_data=data,
|
||||
source_event_id=source_evt_id,
|
||||
)
|
||||
if source_type == "agent.message.completed":
|
||||
# A completed structured seat turn is also a delivery milestone;
|
||||
# this gives the timeline a stable gate separate from raw text.
|
||||
delivery_data = {
|
||||
key: payload[key]
|
||||
for key in ("content", "schema_status")
|
||||
if key in payload
|
||||
}
|
||||
if event.get("agent_id"):
|
||||
delivery_data["agent_id"] = event["agent_id"]
|
||||
await self._publish_conversation_event(
|
||||
conversation_id=conversation_id,
|
||||
owner_user_id=owner_user_id,
|
||||
event_type="seat.delivery.submitted",
|
||||
event_data=delivery_data,
|
||||
source_event_id=f"{source_evt_id}:delivery" if source_evt_id else None,
|
||||
)
|
||||
|
||||
async def _dispatch_run(self, *, conversation_id: str, user_id: str, run: dict[str, Any]) -> None:
|
||||
if self._dispatcher is None:
|
||||
# R1 unit callers can still exercise persistence without starting
|
||||
# the optional SDK runtime. The production dependency wiring always
|
||||
# supplies a dispatcher.
|
||||
return
|
||||
session = await self._store.sessions.get_session(run["session_id"], user_id=user_id)
|
||||
if session is None:
|
||||
raise ConversationDispatchError("internal MAF session could not be loaded")
|
||||
try:
|
||||
await self._dispatcher.dispatch(session, run, user_id=user_id)
|
||||
except Exception as exc: # noqa: BLE001 - reconcile durable state
|
||||
logger.exception("MAF dispatch failed run=%s", run["id"])
|
||||
await self._mark_dispatch_failed(
|
||||
conversation_id=conversation_id,
|
||||
user_id=user_id,
|
||||
run_id=run["id"],
|
||||
error_code=type(exc).__name__[:64],
|
||||
)
|
||||
raise ConversationRuntimeUnavailableError() from exc
|
||||
|
||||
wait_for_run = getattr(self._dispatcher, "wait_for_run", None)
|
||||
if callable(wait_for_run):
|
||||
watcher = asyncio.create_task(
|
||||
self._watch_run(
|
||||
conversation_id=conversation_id,
|
||||
user_id=user_id,
|
||||
run_id=run["id"],
|
||||
wait_for_run=wait_for_run,
|
||||
)
|
||||
)
|
||||
self._watchers[run["id"]] = watcher
|
||||
watcher.add_done_callback(lambda _task, rid=run["id"]: self._watchers.pop(rid, None))
|
||||
|
||||
async def _mark_dispatch_failed(
|
||||
self, *, conversation_id: str, user_id: str, run_id: str, error_code: str
|
||||
) -> None:
|
||||
await self._store.runs.update_run(run_id, {
|
||||
"status": "failed",
|
||||
"finished_at": datetime.now(UTC),
|
||||
"error_code": error_code,
|
||||
"error_message_safe": "MAF workflow dispatch failed",
|
||||
})
|
||||
run = await self._store.runs.get_run(run_id)
|
||||
if run is not None:
|
||||
await self._store.sessions.update_session(
|
||||
run["session_id"], user_id=user_id, fields={"status": "failed"}
|
||||
)
|
||||
await self._store.conversations.set_active_run(conversation_id, None, "failed")
|
||||
await self._publish_conversation_event(
|
||||
conversation_id=conversation_id,
|
||||
owner_user_id=user_id,
|
||||
event_type="run.error",
|
||||
event_data={"status": "failed", "error_code": error_code},
|
||||
)
|
||||
|
||||
async def _watch_run(
|
||||
self,
|
||||
*,
|
||||
conversation_id: str,
|
||||
user_id: str,
|
||||
run_id: str,
|
||||
wait_for_run: Any,
|
||||
) -> None:
|
||||
try:
|
||||
await wait_for_run(run_id)
|
||||
except asyncio.CancelledError:
|
||||
raise
|
||||
except Exception:
|
||||
logger.exception("MAF conversation watcher failed run=%s", run_id)
|
||||
return
|
||||
|
||||
run = await self._store.runs.get_run(run_id)
|
||||
if run is None:
|
||||
return
|
||||
status_value = str(run.get("status") or "failed")
|
||||
terminal = status_value in {"completed", "failed", "cancelled"}
|
||||
await self._store.conversations.set_active_run(
|
||||
conversation_id,
|
||||
None if terminal else run_id,
|
||||
status_value,
|
||||
)
|
||||
event_type = {
|
||||
"completed": "run.completed",
|
||||
"failed": "run.error",
|
||||
"cancelled": "run.cancelled",
|
||||
}.get(status_value, "run.status")
|
||||
data: dict[str, Any] = {"status": status_value}
|
||||
if run.get("error_code"):
|
||||
data["error_code"] = run["error_code"]
|
||||
await self._publish_conversation_event(
|
||||
conversation_id=conversation_id,
|
||||
owner_user_id=user_id,
|
||||
event_type=event_type,
|
||||
event_data=data,
|
||||
)
|
||||
|
||||
async def _get_conv_row(self, conversation_id: str) -> MafRoundtableConversationRow | None:
|
||||
from sqlalchemy import select
|
||||
async with self._store.session_factory() as session:
|
||||
row = (
|
||||
await session.execute(
|
||||
select(MafRoundtableConversationRow).where(
|
||||
MafRoundtableConversationRow.id == conversation_id
|
||||
)
|
||||
)
|
||||
).scalars().first()
|
||||
return row
|
||||
|
||||
async def _get_msg_row(self, message_id: str) -> MafRoundtableMessageRow | None:
|
||||
from sqlalchemy import select
|
||||
async with self._store.session_factory() as session:
|
||||
row = (
|
||||
await session.execute(
|
||||
select(MafRoundtableMessageRow).where(
|
||||
MafRoundtableMessageRow.id == message_id
|
||||
)
|
||||
)
|
||||
).scalars().first()
|
||||
return row
|
||||
@@ -488,6 +488,7 @@ class DeerFlowAgentAdapter:
|
||||
raise AuditEventError(
|
||||
f"Critical audit event '{event.get('event_type')}' failed to persist: {exc}"
|
||||
) from exc
|
||||
await self._bridge_conversation_event(run_id, event)
|
||||
|
||||
async def _emit(self, run_id: str, event: dict[str, Any]) -> None:
|
||||
"""Emit a non-critical event (agent.message.delta). Failure degrades gracefully.
|
||||
@@ -518,6 +519,42 @@ class DeerFlowAgentAdapter:
|
||||
)
|
||||
except Exception:
|
||||
logger.warning("non-critical event %s failed for run %s (degraded)", event_type, run_id, exc_info=True)
|
||||
return
|
||||
await self._bridge_conversation_event(run_id, event)
|
||||
|
||||
async def _bridge_conversation_event(self, run_id: str, event: dict[str, Any]) -> None:
|
||||
"""Best-effort projection into the V2 conversation event stream.
|
||||
|
||||
The per-run audit write above remains authoritative. A projection
|
||||
failure must not cause a tool to execute twice or turn a completed
|
||||
seat run into a false runtime failure; reconnect/recovery can rebuild
|
||||
the conversation view from the audit ledger later.
|
||||
|
||||
P0-3: the entire ``app.state`` resolution is best-effort. If any link
|
||||
is missing (no app, no state, no conversation service), the projection
|
||||
is silently skipped — audit, recovery, cancel, lease, and tool
|
||||
execution safety are never affected.
|
||||
"""
|
||||
try:
|
||||
app = getattr(self._client, "app", None)
|
||||
state = getattr(app, "state", None)
|
||||
conversation_service = getattr(state, "maf_conversation_service", None)
|
||||
except Exception: # noqa: BLE001
|
||||
return
|
||||
if conversation_service is None:
|
||||
return
|
||||
bridge = getattr(conversation_service, "bridge_workflow_event", None)
|
||||
if not callable(bridge):
|
||||
return
|
||||
try:
|
||||
await bridge(run_id=run_id, event=event)
|
||||
except Exception: # noqa: BLE001 - audit already persisted
|
||||
logger.warning(
|
||||
"conversation event projection failed for run %s (%s)",
|
||||
run_id,
|
||||
event.get("event_type"),
|
||||
exc_info=True,
|
||||
)
|
||||
|
||||
# ── internal helpers ────────────────────────────────────────────────────
|
||||
|
||||
|
||||
@@ -0,0 +1,268 @@
|
||||
"""Deterministic, server-owned contracts for MAF Stage 3 dispatch.
|
||||
|
||||
The manager may describe work, but it does not get to choose arbitrary agent
|
||||
ids, threads, tools, or capabilities. Routing is resolved from the trusted
|
||||
MAF deployment configuration and the small, validated task-context allowlist.
|
||||
This module is intentionally independent of the MAF SDK so the policy can be
|
||||
tested with a weak/fake model and before any workflow is launched.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any, Literal
|
||||
|
||||
from pydantic import BaseModel, ConfigDict, Field, model_validator
|
||||
|
||||
from deerflow.config.maf_roundtable_config import MafMode
|
||||
|
||||
MafIntentType = Literal[
|
||||
"direct_answer",
|
||||
"clarification",
|
||||
"single_seat",
|
||||
"parallel_consultation",
|
||||
"chain_consultation",
|
||||
"tool_write",
|
||||
]
|
||||
|
||||
|
||||
class DispatchConfigurationError(RuntimeError):
|
||||
"""The deployment has not supplied a complete trusted route."""
|
||||
|
||||
|
||||
class InvalidDispatchPlanError(ValueError):
|
||||
"""A proposed or constructed plan violates the dispatch contract."""
|
||||
|
||||
|
||||
class MafIntentDecision(BaseModel):
|
||||
model_config = ConfigDict(extra="forbid")
|
||||
|
||||
intent_type: MafIntentType
|
||||
confidence: float = Field(ge=0.0, le=1.0)
|
||||
reason_code: str = Field(min_length=1, max_length=64)
|
||||
clarification_prompt: str | None = Field(default=None, max_length=1000)
|
||||
|
||||
@model_validator(mode="after")
|
||||
def _clarification_shape(self) -> MafIntentDecision:
|
||||
if self.intent_type == "clarification" and not self.clarification_prompt:
|
||||
raise ValueError("clarification intent requires clarification_prompt")
|
||||
if self.intent_type != "clarification" and self.clarification_prompt is not None:
|
||||
raise ValueError("only clarification intent may include clarification_prompt")
|
||||
return self
|
||||
|
||||
|
||||
class MafDispatchAssignment(BaseModel):
|
||||
model_config = ConfigDict(extra="forbid")
|
||||
|
||||
agent_id: str = Field(min_length=1, max_length=64)
|
||||
role: Literal["seat"] = "seat"
|
||||
sort_order: int = Field(ge=1, le=64)
|
||||
|
||||
|
||||
class MafDispatchPlan(BaseModel):
|
||||
"""Validated plan containing only server-selected participants."""
|
||||
|
||||
model_config = ConfigDict(extra="forbid")
|
||||
|
||||
manager_agent_id: str = Field(min_length=1, max_length=64)
|
||||
seat_agent_ids: list[str] = Field(default_factory=list, max_length=64)
|
||||
assignments: list[MafDispatchAssignment] = Field(default_factory=list, max_length=64)
|
||||
mode: MafMode = "structured"
|
||||
intent_type: MafIntentType
|
||||
business_code: str | None = Field(default=None, max_length=255)
|
||||
max_rounds: int = Field(ge=1, le=64)
|
||||
|
||||
@model_validator(mode="after")
|
||||
def _validate_shape(self) -> MafDispatchPlan:
|
||||
if self.manager_agent_id in self.seat_agent_ids:
|
||||
raise ValueError("manager agent cannot also be a seat")
|
||||
if len(set(self.seat_agent_ids)) != len(self.seat_agent_ids):
|
||||
raise ValueError("duplicate seat agent")
|
||||
assignment_ids = [assignment.agent_id for assignment in self.assignments]
|
||||
if assignment_ids != self.seat_agent_ids:
|
||||
raise ValueError("assignments must exactly match seat_agent_ids")
|
||||
if [a.sort_order for a in self.assignments] != list(range(1, len(self.assignments) + 1)):
|
||||
raise ValueError("assignments must have contiguous sort_order")
|
||||
if self.intent_type == "clarification":
|
||||
raise ValueError("clarification cannot be dispatched")
|
||||
if self.intent_type != "direct_answer" and not self.seat_agent_ids:
|
||||
raise ValueError("this intent requires at least one configured seat")
|
||||
return self
|
||||
|
||||
|
||||
def resolve_intent(content: str, task_context: dict[str, Any] | None = None) -> MafIntentDecision:
|
||||
"""Resolve the common Stage 3 intents deterministically.
|
||||
|
||||
A production model can later supply a *description* for the intent, but
|
||||
this policy remains the final validator. The fallback deliberately uses
|
||||
conservative keywords and never extracts agent/tool ids from user text.
|
||||
"""
|
||||
|
||||
text = " ".join(str(content or "").strip().split())
|
||||
lowered = text.casefold()
|
||||
if len(text) < 4 or lowered in {"?", "?", "不清楚", "不明确", "再说清楚"}:
|
||||
return MafIntentDecision(
|
||||
intent_type="clarification",
|
||||
confidence=0.99,
|
||||
reason_code="insufficient_task_detail",
|
||||
clarification_prompt="请补充希望解决的具体问题、目标和必要的业务背景。",
|
||||
)
|
||||
|
||||
write_markers = (
|
||||
"写入", "发布", "创建工单", "更新任务", "提交", "删除", "write", "publish", "create ticket",
|
||||
)
|
||||
chain_markers = ("业务链", "链式", "逐阶段", "先…再", "先...再", "chain")
|
||||
parallel_markers = ("多专家", "多角度", "并行", "同时分析", "比较", "parallel", "multi-agent")
|
||||
single_markers = ("请某个专家", "单个席位", "单专家", "single seat", "指定专家")
|
||||
|
||||
if any(marker in lowered for marker in write_markers):
|
||||
intent_type: MafIntentType = "tool_write"
|
||||
reason_code = "write_request"
|
||||
elif any(marker in lowered for marker in chain_markers):
|
||||
intent_type = "chain_consultation"
|
||||
reason_code = "chain_request"
|
||||
elif any(marker in lowered for marker in parallel_markers):
|
||||
intent_type = "parallel_consultation"
|
||||
reason_code = "parallel_request"
|
||||
elif any(marker in lowered for marker in single_markers):
|
||||
intent_type = "single_seat"
|
||||
reason_code = "single_seat_request"
|
||||
else:
|
||||
intent_type = "direct_answer"
|
||||
reason_code = "default_direct_answer"
|
||||
|
||||
return MafIntentDecision(
|
||||
intent_type=intent_type,
|
||||
confidence=0.72 if task_context else 0.68,
|
||||
reason_code=reason_code,
|
||||
)
|
||||
|
||||
|
||||
def _read(value: Any, name: str, default: Any = None) -> Any:
|
||||
if isinstance(value, dict):
|
||||
return value.get(name, default)
|
||||
return getattr(value, name, default)
|
||||
|
||||
|
||||
class MafDispatchCatalog:
|
||||
"""Resolve routes from deployment config, never from a request body."""
|
||||
|
||||
def __init__(self, maf_config: Any) -> None:
|
||||
self._config = maf_config
|
||||
|
||||
def _route(self, business_code: str | None) -> tuple[str | None, list[str], MafMode | None]:
|
||||
routes = _read(self._config, "business_routes", {}) or {}
|
||||
if business_code:
|
||||
route = routes.get(business_code)
|
||||
if route is None:
|
||||
# A supplied business code must match an explicitly configured
|
||||
# route. Falling back here would silently cross business
|
||||
# boundaries.
|
||||
return None, [], None
|
||||
return (
|
||||
_read(route, "manager_agent_id"),
|
||||
list(_read(route, "seat_agent_ids", []) or []),
|
||||
_read(route, "mode"),
|
||||
)
|
||||
return (
|
||||
_read(self._config, "default_manager_agent_id"),
|
||||
list(_read(self._config, "default_seat_agent_ids", []) or []),
|
||||
None,
|
||||
)
|
||||
|
||||
def build_plan(
|
||||
self,
|
||||
*,
|
||||
intent: MafIntentDecision,
|
||||
task_context: dict[str, Any] | None,
|
||||
) -> MafDispatchPlan:
|
||||
business_code = str((task_context or {}).get("business_code") or "").strip() or None
|
||||
manager_id, route_seats, route_mode = self._route(business_code)
|
||||
if not manager_id:
|
||||
raise DispatchConfigurationError(
|
||||
"no trusted MAF manager route is configured for this conversation"
|
||||
)
|
||||
|
||||
# The server owns the route. Intent only changes how many configured
|
||||
# seats participate; it never adds an id.
|
||||
if intent.intent_type in {"single_seat", "tool_write", "direct_answer"}:
|
||||
seat_ids = route_seats[:1]
|
||||
else:
|
||||
seat_ids = route_seats[:]
|
||||
|
||||
max_seats = int(_read(self._config, "max_seats_per_run", 16) or 16)
|
||||
if len(seat_ids) > max_seats:
|
||||
raise DispatchConfigurationError("configured MAF route exceeds max_seats_per_run")
|
||||
|
||||
try:
|
||||
plan = MafDispatchPlan(
|
||||
manager_agent_id=str(manager_id).strip(),
|
||||
seat_agent_ids=[str(agent_id).strip() for agent_id in seat_ids],
|
||||
assignments=[
|
||||
MafDispatchAssignment(agent_id=str(agent_id).strip(), sort_order=index)
|
||||
for index, agent_id in enumerate(seat_ids, start=1)
|
||||
],
|
||||
mode=route_mode or _read(self._config, "default_mode", "structured"),
|
||||
intent_type=intent.intent_type,
|
||||
business_code=business_code,
|
||||
max_rounds=int(_read(self._config, "default_max_rounds", 8) or 8),
|
||||
)
|
||||
except (TypeError, ValueError) as exc:
|
||||
raise DispatchConfigurationError("invalid trusted MAF dispatch route") from exc
|
||||
|
||||
trusted_ids = {str(manager_id), *(str(agent_id) for agent_id in route_seats)}
|
||||
validate_dispatch_plan(plan, trusted_agent_ids=trusted_ids, max_seats=max_seats)
|
||||
return plan
|
||||
|
||||
@staticmethod
|
||||
def participants(plan: MafDispatchPlan) -> list[dict[str, Any]]:
|
||||
"""Return persistence records; thread ids are intentionally absent."""
|
||||
return [
|
||||
{
|
||||
"agent_id": plan.manager_agent_id,
|
||||
"role": "manager",
|
||||
"sort_order": 0,
|
||||
"display_name": "",
|
||||
},
|
||||
*[
|
||||
{
|
||||
"agent_id": assignment.agent_id,
|
||||
"role": "seat",
|
||||
"sort_order": assignment.sort_order,
|
||||
"display_name": "",
|
||||
}
|
||||
for assignment in plan.assignments
|
||||
],
|
||||
]
|
||||
|
||||
|
||||
def validate_dispatch_plan(
|
||||
plan: MafDispatchPlan,
|
||||
*,
|
||||
trusted_agent_ids: set[str],
|
||||
max_seats: int,
|
||||
) -> None:
|
||||
"""Final allowlist check used before persistence and workflow launch."""
|
||||
|
||||
if plan.manager_agent_id not in trusted_agent_ids:
|
||||
raise InvalidDispatchPlanError("manager agent is outside the trusted route")
|
||||
if len(plan.seat_agent_ids) > max_seats:
|
||||
raise InvalidDispatchPlanError("dispatch plan exceeds the seat limit")
|
||||
if any(agent_id not in trusted_agent_ids for agent_id in plan.seat_agent_ids):
|
||||
raise InvalidDispatchPlanError("seat agent is outside the trusted route")
|
||||
if len(set(plan.seat_agent_ids)) != len(plan.seat_agent_ids):
|
||||
raise InvalidDispatchPlanError("dispatch plan contains duplicate seats")
|
||||
if plan.manager_agent_id in plan.seat_agent_ids:
|
||||
raise InvalidDispatchPlanError("manager cannot be dispatched as a seat")
|
||||
|
||||
|
||||
__all__ = [
|
||||
"DispatchConfigurationError",
|
||||
"InvalidDispatchPlanError",
|
||||
"MafDispatchAssignment",
|
||||
"MafDispatchPlan",
|
||||
"MafDispatchCatalog",
|
||||
"MafIntentDecision",
|
||||
"MafIntentType",
|
||||
"resolve_intent",
|
||||
"validate_dispatch_plan",
|
||||
]
|
||||
@@ -71,6 +71,23 @@ class MafRunDispatcher:
|
||||
self._tasks[run_id] = task
|
||||
task.add_done_callback(lambda t, rid=run_id: self._tasks.pop(rid, None))
|
||||
|
||||
async def wait_for_run(self, run_id: str) -> None:
|
||||
"""Wait for an in-process run without exposing its task to callers.
|
||||
|
||||
Conversation V2 uses this only for a server-side status bridge. The
|
||||
persisted run remains authoritative, so a missing task (for example
|
||||
after a worker restart) simply returns and lets recovery own the run.
|
||||
"""
|
||||
task = self._tasks.get(run_id)
|
||||
if task is None:
|
||||
return
|
||||
try:
|
||||
await asyncio.shield(task)
|
||||
except asyncio.CancelledError:
|
||||
raise
|
||||
except Exception: # noqa: BLE001 - runner already persisted failure
|
||||
return
|
||||
|
||||
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:
|
||||
|
||||
@@ -245,6 +245,12 @@ class HealthResponse(BaseModel):
|
||||
"""Health / feature-flag probe. The frontend reads ``enabled`` to decide
|
||||
whether to show the MAF entry. ``store_available`` is false when no DB is
|
||||
configured (memory mode) — the router then returns 503 on writes.
|
||||
|
||||
SSE fields (P1): ``sse_hub_type`` reports the hub implementation
|
||||
(``in_memory`` or future ``redis``); ``sse_multi_worker`` is ``False``
|
||||
until Redis Pub/Sub is wired; ``sse_warning`` carries a human-readable
|
||||
advisory. When multi-worker is unsupported, production deployments must
|
||||
use a single worker or fail-closed.
|
||||
"""
|
||||
|
||||
enabled: bool
|
||||
@@ -257,3 +263,6 @@ class HealthResponse(BaseModel):
|
||||
write_guard_ready: bool
|
||||
action_secret_configured: bool
|
||||
write_guard_status: str
|
||||
sse_hub_type: str = "in_memory"
|
||||
sse_multi_worker: bool = False
|
||||
sse_warning: str = "Single-worker only. Multi-worker requires Redis Pub/Sub."
|
||||
@@ -74,6 +74,8 @@ class RoundtableState:
|
||||
capability_snapshot: dict[str, Any] | None = None,
|
||||
seat_timeout_seconds: float = 600.0,
|
||||
schema_repair_enabled: bool = True,
|
||||
intent_type: str | None = None,
|
||||
dispatch_plan: dict[str, Any] | None = None,
|
||||
) -> None:
|
||||
self.session_id = session_id
|
||||
self.run_id = run_id
|
||||
@@ -89,6 +91,11 @@ class RoundtableState:
|
||||
self.capability_snapshot = capability_snapshot
|
||||
self.seat_timeout_seconds = seat_timeout_seconds
|
||||
self.schema_repair_enabled = schema_repair_enabled
|
||||
# Stage 3 server-validated routing metadata. The workflow may use
|
||||
# this for diagnostics/checkpoints, but it never accepts a new agent
|
||||
# id from manager model output.
|
||||
self.intent_type = intent_type
|
||||
self.dispatch_plan = dispatch_plan
|
||||
|
||||
self.current_round = 0
|
||||
self.turn_results: list[dict[str, Any]] = []
|
||||
@@ -128,6 +135,8 @@ class RoundtableState:
|
||||
"capability_snapshot": self.capability_snapshot,
|
||||
"seat_timeout_seconds": self.seat_timeout_seconds,
|
||||
"schema_repair_enabled": self.schema_repair_enabled,
|
||||
"intent_type": self.intent_type,
|
||||
"dispatch_plan": self.dispatch_plan,
|
||||
"current_round": self.current_round,
|
||||
"turn_results": self.turn_results,
|
||||
"fact_ledger": self.fact_ledger,
|
||||
@@ -159,6 +168,8 @@ class RoundtableState:
|
||||
capability_snapshot=d.get("capability_snapshot"),
|
||||
seat_timeout_seconds=float(d.get("seat_timeout_seconds") or 600.0),
|
||||
schema_repair_enabled=bool(d.get("schema_repair_enabled", True)),
|
||||
intent_type=d.get("intent_type"),
|
||||
dispatch_plan=d.get("dispatch_plan"),
|
||||
)
|
||||
state.current_round = d.get("current_round", 0)
|
||||
state.turn_results = d.get("turn_results", [])
|
||||
@@ -531,12 +542,20 @@ class SeatExecutor(Executor):
|
||||
a for a in turn_actions
|
||||
if a.get("tool_name") == tc_name and not a.get("logical_action_id")
|
||||
]
|
||||
if len(hits) != 1:
|
||||
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"
|
||||
)
|
||||
if len(hits) == 0:
|
||||
logger.warning(
|
||||
"seat %s turn %s: pending tool call '%s' (id=%s) classified as "
|
||||
"needing approval but matched 0 waiting actions — tool may be "
|
||||
"unclassified or executed as read by WriteGuard; skipping",
|
||||
self._agent_id, self._state.current_round, tc_name, tc_id or "<none>",
|
||||
)
|
||||
continue
|
||||
matched.append(hits[0])
|
||||
|
||||
# Merge into pending_approvals (multi-seat).
|
||||
@@ -686,12 +705,45 @@ class CrossReviewExecutor(Executor):
|
||||
if failed_seats:
|
||||
review["gaps"] = [f"席位失败: {', '.join(failed_seats)}"]
|
||||
|
||||
# The quality gate is server-owned. A manager may recommend acceptance,
|
||||
# but gaps/failures/schema degradation always become a controlled gap
|
||||
# and are carried into the final result instead of being labelled as a
|
||||
# verified fact.
|
||||
has_quality_gap = bool(
|
||||
review.get("partial_failure")
|
||||
or review.get("failed_seats")
|
||||
or review.get("gaps")
|
||||
or review.get("conflicts")
|
||||
or review.get("tool_failures")
|
||||
or review.get("schema_status") == "schema_invalid"
|
||||
)
|
||||
review["decision"] = "controlled_gap" if has_quality_gap else "accept"
|
||||
review["reason"] = (
|
||||
"required evidence or seat output is incomplete"
|
||||
if has_quality_gap
|
||||
else "required seat deliveries passed deterministic checks"
|
||||
)
|
||||
self._state.cross_review_result = review
|
||||
# Surface unresolved conflicts from review notes.
|
||||
for c in review.get("conflicts") or []:
|
||||
if c and c not in self._state.fact_ledger["conflicts"]:
|
||||
self._state.fact_ledger["conflicts"].append(c)
|
||||
|
||||
await self._adapter._emit_critical(self._state.run_id, {
|
||||
"event_type": "manager.review.decision",
|
||||
"agent_id": self._state.manager_agent_id or "",
|
||||
"turn_index": self._state.current_round,
|
||||
"payload": {
|
||||
"decision": review["decision"],
|
||||
"reason": review["reason"],
|
||||
"quality": {
|
||||
"failed_seat_count": len(review.get("failed_seats") or []),
|
||||
"gap_count": len(review.get("gaps") or []),
|
||||
"conflict_count": len(review.get("conflicts") or []),
|
||||
},
|
||||
},
|
||||
})
|
||||
|
||||
self._state.mark_completed("cross_review")
|
||||
self._state.stage = "approval"
|
||||
await ctx.send_message({"decision": "reviewed", "review": review})
|
||||
@@ -937,16 +989,13 @@ class ApprovalGateExecutor(Executor):
|
||||
def _check_needs_approval(self) -> bool:
|
||||
if self._state.write_policy == "auto":
|
||||
return False
|
||||
if self._state.pending_approvals:
|
||||
return True
|
||||
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
|
||||
# pending_approvals is the authoritative source: it is populated by
|
||||
# SeatExecutor._capture_pending_approvals which only adds tool calls
|
||||
# that WriteGuard actually intercepted (i.e. have a database action).
|
||||
# Tools that were classified as needing approval but had 0 matching
|
||||
# actions (unclassified/hallucinated/read tools) are intentionally
|
||||
# skipped and must NOT re-trigger the gate here.
|
||||
return bool(self._state.pending_approvals)
|
||||
|
||||
|
||||
# ── Finalizer ───────────────────────────────────────────────────────────────
|
||||
@@ -1006,6 +1055,10 @@ async def generate_final_report(adapter: Any, state: RoundtableState) -> dict[st
|
||||
"agent_id": manager_id,
|
||||
"partial_failure": state.partial_failure,
|
||||
"degraded": state.partial_failure,
|
||||
"quality_decision": (
|
||||
(state.cross_review_result or {}).get("decision")
|
||||
or ("controlled_gap" if state.partial_failure else "accept")
|
||||
),
|
||||
}
|
||||
else:
|
||||
state.final_result = {
|
||||
@@ -1014,6 +1067,10 @@ async def generate_final_report(adapter: Any, state: RoundtableState) -> dict[st
|
||||
"note": "no_manager_thread",
|
||||
"partial_failure": state.partial_failure,
|
||||
"degraded": state.partial_failure,
|
||||
"quality_decision": (
|
||||
(state.cross_review_result or {}).get("decision")
|
||||
or ("controlled_gap" if state.partial_failure else "accept")
|
||||
),
|
||||
}
|
||||
|
||||
await adapter._emit_critical(state.run_id, make_run_completed(manager_id, state.current_round + 1, {
|
||||
|
||||
@@ -96,6 +96,9 @@ class WorkflowRunner:
|
||||
seat_agents = [p["agent_id"] for p in participants if p.get("role") != "manager"]
|
||||
manager_id = session.get("manager_agent_id")
|
||||
seat_timeout, schema_repair = self._orchestration_settings()
|
||||
task_payload = session.get("task_payload") or {}
|
||||
maf_v2_payload = task_payload.get("maf_v2") if isinstance(task_payload, dict) else {}
|
||||
maf_v2_payload = maf_v2_payload if isinstance(maf_v2_payload, dict) else {}
|
||||
|
||||
state = RoundtableState(
|
||||
session_id=session_id,
|
||||
@@ -112,6 +115,8 @@ class WorkflowRunner:
|
||||
capability_snapshot=session.get("capability_snapshot"),
|
||||
seat_timeout_seconds=seat_timeout,
|
||||
schema_repair_enabled=schema_repair,
|
||||
intent_type=maf_v2_payload.get("intent_type"),
|
||||
dispatch_plan=maf_v2_payload.get("dispatch_plan"),
|
||||
)
|
||||
|
||||
workflow = self._build_workflow(state)
|
||||
|
||||
Reference in new issue
Block a user