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:
董宏凯andCursor committed 2026-08-03 12:09:47 +08:00
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)