代码提交

This commit is contained in:
董宏凯 committed 2026-08-03 19:27:54 +08:00
1 parent d93cc62806
commit ddf83f7728
25 files changed
+4086 -424

No files matched your search

@@ -12,7 +12,7 @@ import asyncio
import logging
from collections.abc import AsyncGenerator, Callable
from contextlib import AsyncExitStack, asynccontextmanager
from typing import TYPE_CHECKING, TypeVar, cast
from typing import TYPE_CHECKING, Any, TypeVar, cast
from fastapi import FastAPI, HTTPException, Request
from langgraph.types import Checkpointer
@@ -39,6 +39,67 @@ if TYPE_CHECKING:
T = TypeVar("T")
def get_gateway_worker_topology() -> dict[str, Any]:
"""Detect the current worker count and source.
Returns ``{"worker_count": int|None, "source": str, "is_multi_worker": bool}``.
Sources checked in order: ``WEB_CONCURRENCY`` env var, ``/proc`` scan (Linux).
"""
import os as _os
wc = _os.environ.get("WEB_CONCURRENCY", "").strip()
if wc and wc.isdigit():
count = int(wc)
return {"worker_count": count, "source": "WEB_CONCURRENCY", "is_multi_worker": count > 1}
if not _os.name == "posix":
return {"worker_count": None, "source": "unknown", "is_multi_worker": False}
try:
from pathlib import Path as _Path
peers = 0
proc = _Path("/proc")
if proc.exists():
for entry in proc.iterdir():
if not entry.name.isdigit():
continue
try:
cmdline = (entry / "cmdline").read_bytes().replace(b"\x00", b" ").decode("utf-8", "ignore")
except OSError:
continue
if "uvicorn" in cmdline and "app.gateway.app" in cmdline:
peers += 1
if peers > 0:
return {"worker_count": peers, "source": "process_scan", "is_multi_worker": peers > 1}
except Exception: # noqa: BLE001
pass
return {"worker_count": None, "source": "unknown", "is_multi_worker": False}
async def _background_reconcile_loop(service: Any, *, interval: int) -> None:
"""Periodically reconcile active conversation runs."""
while True:
try:
await asyncio.sleep(interval)
await service.reconcile_active_conversations()
except asyncio.CancelledError:
raise
except Exception: # noqa: BLE001
logger.warning("[maf-roundtable] background reconcile failed", exc_info=True)
async def _startup_reconcile(service: Any) -> None:
"""One-shot reconcile of all active runs at gateway startup."""
try:
written = await service.reconcile_active_conversations()
if written:
logger.info("[maf-roundtable] startup reconcile wrote %d conversation events", written)
except Exception: # noqa: BLE001
logger.warning("[maf-roundtable] startup reconcile failed", exc_info=True)
def resolve_roundtable_gateway_mode(raw: str | None) -> str:
"""解析 ``ROUNDTABLE_JOB_GATEWAY``:**默认 ``inprocess``(真模型后台挂起)**。
@@ -321,11 +382,24 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
app.state.maf_roundtable_store = make_maf_roundtable_store(sf)
maf_enabled = False
maf_dispatch_ready = False
maf_dispatch_status = "configuration_unavailable"
try:
from app.maf_roundtable import MafRoundtableService
maf_cfg = getattr(config, "maf_roundtable", None)
maf_enabled = bool(getattr(maf_cfg, "enabled", False)) if maf_cfg is not None else False
maf_cfg = getattr(config, "maf_roundtable", None)
maf_enabled = bool(getattr(maf_cfg, "enabled", False)) if maf_cfg is not None else False
if maf_cfg is not None:
from app.maf_roundtable.dispatch_contracts import MafDispatchCatalog
maf_dispatch_ready, maf_dispatch_status = MafDispatchCatalog(maf_cfg).readiness()
if maf_enabled and not maf_dispatch_ready:
logger.error(
"[maf-roundtable] enabled but no trusted manager route is configured; "
"forcing the conversation entry OFF (%s)",
maf_dispatch_status,
)
maf_enabled = False
maf_admin_diag = (
bool(getattr(maf_cfg, "admin_diagnostic_access", True)) if maf_cfg is not None else True
)
@@ -348,7 +422,8 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
"forcing the feature OFF: %s",
cfg_exc,
)
maf_enabled = False
maf_enabled = False
maf_dispatch_ready = False
if app.state.maf_roundtable_store is not None:
app.state.maf_roundtable_service = MafRoundtableService(
app.state.maf_roundtable_store,
@@ -371,24 +446,48 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
app.state.maf_roundtable_service = None
# ── MAF roundtable V2 Conversation service + SSE event hub ──
# P0-2: multi-worker guard — memory hub cannot broadcast across
# workers. When detected, disable the conversation SSE write path
# (reads stay open for admin history review).
_topology = get_gateway_worker_topology()
_maf_cfg = getattr(config, "maf_roundtable", None)
_conv_backend = getattr(_maf_cfg, "conversation_event_backend", "memory")
_require_single = getattr(_maf_cfg, "require_single_worker_for_conversation_sse", True)
_stream_blocked = (
_conv_backend == "memory"
and _topology["is_multi_worker"]
and _require_single
)
if _stream_blocked:
logger.error(
"[maf-roundtable] conversation_event_backend=memory with %d workers "
"(%s) — SSE stream disabled. Set WEB_CONCURRENCY=1 or deploy Redis "
"Pub/Sub before enabling multi-worker conversation SSE.",
_topology["worker_count"],
_topology["source"],
)
try:
from app.maf_roundtable.conversation_event_hub import ConversationEventHub
app.state.maf_conversation_event_hub = ConversationEventHub()
if _stream_blocked:
app.state.maf_conversation_event_hub = None
else:
app.state.maf_conversation_event_hub = ConversationEventHub()
if app.state.maf_roundtable_store is not None:
from app.maf_roundtable.conversation_service import MafConversationService
from app.maf_roundtable.dispatcher import get_dispatcher
app.state.maf_conversation_service = MafConversationService(
app.state.maf_roundtable_store,
maf_config=getattr(config, "maf_roundtable", None),
event_hub=app.state.maf_conversation_event_hub,
agent_store=getattr(app.state, "agent_store", None),
app_config=config,
dispatcher=get_dispatcher(app),
enabled=maf_enabled,
)
if app.state.maf_roundtable_store is not None:
from app.maf_roundtable.conversation_service import MafConversationService
from app.maf_roundtable.dispatcher import get_dispatcher
app.state.maf_conversation_service = MafConversationService(
app.state.maf_roundtable_store,
maf_config=_maf_cfg,
event_hub=app.state.maf_conversation_event_hub,
agent_store=getattr(app.state, "agent_store", None),
app_config=config,
dispatcher=get_dispatcher(app),
enabled=maf_enabled,
)
else:
app.state.maf_conversation_service = None
except Exception: # noqa: BLE001
@@ -396,6 +495,36 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
app.state.maf_conversation_service = None
app.state.maf_conversation_event_hub = None
app.state.maf_conversation_dispatch_ready = bool(maf_enabled and maf_dispatch_ready)
app.state.maf_conversation_dispatch_status = maf_dispatch_status
app.state.maf_conversation_stream_ready = not _stream_blocked and app.state.maf_conversation_event_hub is not None
app.state.maf_conversation_stream_status = (
"multi_worker_memory_hub_unsupported" if _stream_blocked
else "ok" if app.state.maf_conversation_event_hub is not None
else "hub_not_initialized"
)
app.state.maf_conversation_event_backend = _conv_backend
# ── Background reconcile task for conversation event projection ──
_reconcile_task: asyncio.Task | None = None
if (
app.state.maf_conversation_service is not None
and maf_enabled
and not _stream_blocked
):
_reconcile_interval = getattr(_maf_cfg, "background_reconcile_interval_seconds", 10)
_reconcile_task = asyncio.create_task(
_background_reconcile_loop(
app.state.maf_conversation_service,
interval=max(5, int(_reconcile_interval)),
)
)
app.state.maf_conversation_reconcile_task = _reconcile_task
logger.info("[maf-roundtable] background reconcile started (interval=%ss)", _reconcile_interval)
# Startup reconcile: scan active/recent runs once
asyncio.create_task(_startup_reconcile(app.state.maf_conversation_service))
from deerflow.persistence.roundtable_jobs import (
make_roundtable_job_store,
)
@@ -485,14 +614,22 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
try:
yield
finally:
# P1: shut down the SSE event hub before closing the DB engine
# so active SSE streams are released cleanly.
reconcile_task = getattr(app.state, "maf_conversation_reconcile_task", None)
if reconcile_task is not None:
reconcile_task.cancel()
try:
await reconcile_task
except asyncio.CancelledError:
pass
except Exception: # noqa: BLE001
logger.warning("[maf-roundtable] reconcile task shutdown error", exc_info=True)
hub = getattr(app.state, "maf_conversation_event_hub", None)
if hub is not None:
try:
hub.shutdown()
await hub.aclose()
except Exception: # noqa: BLE001
logger.warning("[maf-roundtable] hub shutdown failed", exc_info=True)
logger.warning("[maf-roundtable] hub aclose failed", exc_info=True)
from deerflow.persistence.notifications import set_notification_store
@@ -82,8 +82,18 @@ def _user_ctx(request: Request) -> tuple[str, bool]:
# ── REST endpoints (Phase 1) ──────────────────────────────────────────────
def _check_stream_ready(request: Request) -> None:
stream_ready = getattr(request.app.state, "maf_conversation_stream_ready", True)
if not stream_ready:
raise HTTPException(
status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
detail=getattr(request.app.state, "maf_conversation_stream_status", "stream_not_ready"),
)
@router.post("/conversations", response_model=ConversationResponse, status_code=status.HTTP_201_CREATED)
async def create_conversation(body: CreateConversationRequest, request: Request):
_check_stream_ready(request)
svc = _get_conversation_service(request)
user_id, _ = _user_ctx(request)
try:
@@ -142,6 +152,7 @@ async def list_messages(
@router.post("/conversations/{conversation_id}/messages", response_model=SendMessageResponse, status_code=status.HTTP_201_CREATED)
async def send_message(conversation_id: str, body: SendMessageRequest, request: Request):
_check_stream_ready(request)
svc = _get_conversation_service(request)
user_id, _ = _user_ctx(request)
try:
@@ -198,53 +209,44 @@ def _is_terminal(event: dict[str, Any]) -> bool:
return event.get("type") in _TERMINAL_EVENT_TYPES
@router.get("/conversations/{conversation_id}/stream")
async def stream_conversation(
conversation_id: str,
def build_conversation_event_generator(
*,
service: MafConversationService,
hub: ConversationEventHub,
request: Request,
after_seq: int = Query(default=0, ge=0),
):
"""SSE stream for one conversation (§4.2).
conversation_id: str,
after_seq: int = 0,
) -> Any:
"""Extracted async generator for SSE streaming — testable without HTTP.
Single fetch-reader connection per conversation. The ordering is:
The ordering is:
1. **Open subscription** (register before any DB query — P0-1 fix).
2. **Replay** from DB: ``list_events(after_seq)``.
3. **Stabilise**: re-query while the hub generation advanced during replay.
4. **Snapshot** marker.
5. **Real-time**: ``wait_for_change`` → query DB → yield events.
1. **Reconcile** any missed projections for the active run (P0-1 auto).
2. **Open subscription** (register before any DB query — P0-1 fix).
3. **Replay** from DB: ``list_events(after_seq)``.
4. **Stabilise**: re-query while the hub generation advanced during replay.
5. **Snapshot** marker.
6. **Real-time**: ``wait_for_change`` → query DB → yield events.
On terminal events (``run.completed`` / ``run.error`` / ``run.cancelled``)
the stream sends the event and closes (P0-2 fix).
Heartbeat every 15 s. Disconnect detection via ``request.is_disconnected()``.
On terminal events the stream sends the event and closes (P0-2 fix).
Heartbeat every ``hub.heartbeat_interval`` seconds.
"""
svc = _get_conversation_service(request)
hub = _get_event_hub(request)
user_id, is_admin = _user_ctx(request)
store = service._store # noqa: SLF001
if hub is None:
raise HTTPException(
status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
detail="SSE event hub not configured",
)
async def _gen():
try:
active_run_id = await _get_active_run_id(store, conversation_id)
if active_run_id:
try:
await service.reconcile_conversation_events(run_id=active_run_id)
except Exception: # noqa: BLE001
logger.warning("SSE connect reconcile failed conv=%s", conversation_id, exc_info=True)
except Exception: # noqa: BLE001
logger.warning("SSE connect reconcile lookup failed conv=%s", conversation_id, exc_info=True)
# Ownership check before opening the stream.
try:
await svc.get_conversation(
conversation_id=conversation_id, user_id=user_id, is_admin=is_admin,
)
except ConversationNotFoundError:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Conversation not found")
store = svc._store # noqa: SLF001 — router needs raw event queries for streaming
async def event_generator():
# ── P0-1: Open subscription BEFORE replay ──
sub = hub.open_subscription(conversation_id)
last_seq = after_seq
try:
# ── Phase 1: Replay from DB ──
try:
replay_events = await store.conversation_events.list_events(
conversation_id, after_seq=last_seq,
@@ -254,7 +256,6 @@ async def stream_conversation(
return
yield _format_sse_event(evt)
last_seq = max(last_seq, int(evt.get("seq", last_seq)))
# P0-2: stop if replay already hit a terminal event.
if _is_terminal(evt):
return
except Exception:
@@ -269,7 +270,6 @@ async def stream_conversation(
})
return
# ── P0-1: Stabilise — catch events published during replay ──
while sub.has_pending:
sub.mark_seen()
late_events = await store.conversation_events.list_events(
@@ -285,7 +285,6 @@ async def stream_conversation(
if _is_terminal(evt):
return
# ── Send snapshot marker ──
snapshot = {
"seq": last_seq,
"event_id": f"snapshot_{conversation_id}_{last_seq}",
@@ -297,7 +296,6 @@ async def stream_conversation(
if not await request.is_disconnected():
yield _format_sse_event(snapshot)
# ── Phase 2: Real-time subscription ──
heartbeat_interval = hub.heartbeat_interval
while True:
if hub.is_closed:
@@ -307,13 +305,11 @@ async def stream_conversation(
changed = await sub.wait_for_change(timeout=heartbeat_interval)
if not changed:
# Timeout → heartbeat (or hub closed).
if hub.is_closed:
return
yield _format_heartbeat()
continue
# Generation advanced — fetch new events from DB.
new_events = await store.conversation_events.list_events(
conversation_id, after_seq=last_seq,
)
@@ -322,7 +318,6 @@ async def stream_conversation(
return
yield _format_sse_event(evt)
last_seq = max(last_seq, int(evt.get("seq", last_seq)))
# P0-2: terminal event → close stream after sending it.
if _is_terminal(evt):
return
except asyncio.CancelledError:
@@ -334,8 +329,63 @@ async def stream_conversation(
finally:
sub.close()
return _gen()
async def _get_active_run_id(store: Any, conversation_id: str) -> str | None:
from sqlalchemy import select
from deerflow.persistence.maf_roundtable.model import MafRoundtableConversationRow
async with store.session_factory() as db:
row = (
await db.execute(
select(MafRoundtableConversationRow.active_run_id).where(
MafRoundtableConversationRow.id == conversation_id,
)
)
).first()
return row[0] if row and row[0] else None
@router.get("/conversations/{conversation_id}/stream")
async def stream_conversation(
conversation_id: str,
request: Request,
after_seq: int = Query(default=0, ge=0),
):
"""SSE stream for one conversation (§4.2)."""
svc = _get_conversation_service(request)
hub = _get_event_hub(request)
user_id, is_admin = _user_ctx(request)
if hub is None:
raise HTTPException(
status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
detail="SSE event hub not configured",
)
stream_ready = getattr(request.app.state, "maf_conversation_stream_ready", True)
if not stream_ready:
raise HTTPException(
status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
detail=getattr(request.app.state, "maf_conversation_stream_status", "stream_not_ready"),
)
try:
await svc.get_conversation(
conversation_id=conversation_id, user_id=user_id, is_admin=is_admin,
)
except ConversationNotFoundError:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Conversation not found")
return StreamingResponse(
event_generator(),
build_conversation_event_generator(
service=svc,
hub=hub,
request=request,
conversation_id=conversation_id,
after_seq=after_seq,
),
media_type="text/event-stream",
headers=_SSE_HEADERS,
)
@@ -119,9 +119,20 @@ async def get_health(request: Request) -> HealthResponse:
cfg = app_config.maf_roundtable
svc = _get_service(request)
store_available = svc is not None and svc.store is not None
from app.maf_roundtable.dispatch_contracts import MafDispatchCatalog
dispatch_ready, dispatch_status = MafDispatchCatalog(cfg).readiness()
readiness = get_maf_write_guard_readiness(app_config=app_config)
stream_ready = bool(getattr(request.app.state, "maf_conversation_stream_ready", False))
stream_status = str(getattr(request.app.state, "maf_conversation_stream_status", "unknown"))
conv_backend = str(getattr(request.app.state, "maf_conversation_event_backend", "memory"))
return HealthResponse(
enabled=bool(cfg.enabled and svc is not None and svc.enabled),
enabled=bool(cfg.enabled and dispatch_ready and svc is not None and svc.enabled),
conversation_dispatch_ready=bool(cfg.enabled and dispatch_ready and svc is not None and svc.enabled),
conversation_dispatch_status=dispatch_status,
conversation_stream_ready=stream_ready,
conversation_stream_status=stream_status,
conversation_event_backend=conv_backend,
store_available=store_available,
default_mode=cfg.default_mode,
default_write_policy=cfg.default_write_policy,
@@ -251,34 +251,30 @@ class ConversationEventHub:
return seen_gen
return state.generation
def shutdown(self) -> None:
"""Signal all subscribers to stop (server shutdown).
async def aclose(self) -> None:
"""Async shutdown that immediately wakes all subscribers.
Wakes every waiter; their ``wait_for_change`` returns ``True`` but
the caller's outer loop checks ``hub.is_closed`` and exits.
Acquires each Condition lock, bumps generation, and calls
``notify_all()`` so every waiter returns within milliseconds —
not after the next heartbeat timeout.
"""
self._closed = True
for state in list(self._convs.values()):
async with state.condition:
state.generation += 1
state.condition.notify_all()
def shutdown(self) -> None:
"""Deprecated sync stub — bumps generation but cannot wake waiters
immediately. Callers should use ``await hub.aclose()`` instead."""
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()
await hub.aclose()
__all__ = ["ConversationEventHub", "Subscription", "hub_aclose"]
@@ -18,10 +18,8 @@ from typing import TYPE_CHECKING, Any
from app.maf_roundtable.dispatch_contracts import (
DispatchConfigurationError,
MafDispatchCandidateSet,
MafDispatchCatalog,
MafDispatchPlan,
MafIntentDecision,
resolve_intent,
)
from deerflow.persistence.maf_roundtable.conversations import (
conversation_public_to_dict,
@@ -113,8 +111,24 @@ class MafConversationService:
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))
if not self._enabled_override:
return False
elif not bool(getattr(self._maf_config, "enabled", False)):
return False
return self.conversation_dispatch_ready
@property
def conversation_dispatch_ready(self) -> bool:
"""Expose only non-sensitive route readiness to the gateway/UI."""
if self._maf_config is None:
return False
return MafDispatchCatalog(self._maf_config).conversation_dispatch_ready
@property
def conversation_dispatch_status(self) -> str:
if self._maf_config is None:
return "configuration_unavailable"
return MafDispatchCatalog(self._maf_config).readiness()[1]
def _read_scope_user(self, *, user_id: str, is_admin: bool) -> str | None:
"""Keep administrator diagnostics read-only and config-gated."""
@@ -129,83 +143,82 @@ class MafConversationService:
title: str,
content: str,
task_context: dict[str, Any] | None,
) -> tuple[dict[str, Any] | None, MafIntentDecision, MafDispatchPlan | None]:
) -> tuple[dict[str, Any] | None, MafDispatchCandidateSet]:
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]] = []
try:
candidate_set = MafDispatchCatalog(cfg).build_candidate_set(
task_context=task_context,
)
except DispatchConfigurationError as exc:
raise ConversationDispatchError(str(exc)) from exc
snapshot_inputs = MafDispatchCatalog.candidate_participants(
candidate_set,
include_seats=True,
)
participants = MafDispatchCatalog.candidate_participants(
candidate_set,
include_seats=False,
)
capability_snapshot: dict[str, Any] | None = None
if intent.intent_type != "clarification":
from app.maf_roundtable.capability_snapshot import (
AgentNotAccessibleError,
InvalidExcludedToolsError,
build_trusted_capability_snapshot,
seat_snapshot_for_agent,
)
if self._app_config is not None:
try:
plan = MafDispatchCatalog(cfg).build_plan(
intent=intent,
task_context=task_context,
capability_snapshot = await build_trusted_capability_snapshot(
user_id=user_id,
participants=snapshot_inputs,
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 DispatchConfigurationError as exc:
raise ConversationDispatchError(str(exc)) from exc
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
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"])
)
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,
"dispatch_contract_enabled": True,
"candidate_set": candidate_set.model_dump(mode="json"),
"candidate_seat_agent_ids": list(candidate_set.candidate_seat_agent_ids),
"manager_agent_id": candidate_set.manager_agent_id,
}
}
blueprint = {
"title": title,
"task_text": content,
"mode": getattr(plan, "mode", None) or getattr(cfg, "default_mode", "structured"),
"mode": candidate_set.mode,
"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),
"manager_agent_id": candidate_set.manager_agent_id,
"max_rounds": candidate_set.max_rounds,
"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",
"start_run": True,
}
return blueprint, intent, plan
return blueprint, candidate_set
async def create_conversation(
self, *, user_id: str, title: str = "", task_context: dict[str, Any] | None = None
@@ -275,7 +288,7 @@ class MafConversationService:
raise ConversationNotFoundError()
try:
blueprint, intent, plan = await self._build_dispatch_blueprint(
blueprint, _candidate_set = await self._build_dispatch_blueprint(
user_id=user_id,
title=conv.get("title", ""),
content=content,
@@ -290,7 +303,7 @@ class MafConversationService:
# 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:
if self._dispatcher is not None:
check_sdk = getattr(self._dispatcher, "check_sdk_available", None)
if callable(check_sdk):
try:
@@ -313,48 +326,19 @@ class MafConversationService:
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 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)
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"],
)
if result.get("run") is None:
raise ConversationDispatchError("dispatch run was not created")
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 "",
@@ -426,16 +410,115 @@ class MafConversationService:
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.
_EVENT_TYPE_MAP = {
"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",
"manager.dispatch": "manager.dispatch",
"clarification.required": "clarification.required",
"workflow.checkpointed": "run.status",
"action.waiting_target_lease": "tool.progress",
"action.unknown": "tool.failed",
}
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.
"""
_ALLOWED_TYPES = frozenset({
"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", "clarification.required",
"fact.confirmed", "review.completed", "run.status", "run.error",
"run.cancelled", "run.completed",
})
_SAFE_KEYS: dict[str, dict[str, bool]] = {
"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": {
"intent_type": True, "execution_mode": True, "convergence_path": True,
"selected_seat_agent_ids": True, "assignments": True, "next_speaker": True,
"reason": True, "source": True, "clarification_prompt": True,
},
"clarification.required": {"prompt": 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},
}
def _build_projection_items(
self,
event: dict[str, Any],
source_audit_event_id: str | None,
) -> list[dict[str, Any]]:
source_type = str(event.get("event_type") or "")
mapped_type = self._EVENT_TYPE_MAP.get(source_type, source_type)
if mapped_type not in self._ALLOWED_TYPES:
return []
payload = event.get("payload")
if not isinstance(payload, dict):
payload = {}
safe_keys = self._SAFE_KEYS.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"]
source_evt_id = source_audit_event_id or event.get("id") or event.get("source_event_id")
items: list[dict[str, Any]] = [{
"event_type": mapped_type,
"event_data": data,
"source_event_id": source_evt_id,
}]
if source_type == "agent.message.completed":
delivery_data: dict[str, Any] = {
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"]
items.append({
"event_type": "seat.delivery.submitted",
"event_data": delivery_data,
"source_event_id": f"{source_evt_id}:delivery" if source_evt_id else None,
})
return items
async def _resolve_conversation_for_run(self, run_id: str) -> tuple[str, str] | None:
from sqlalchemy import select
async with self._store.session_factory() as db:
row = (
await db.execute(
@@ -449,104 +532,139 @@ class MafConversationService:
)
).scalars().first()
if row is None:
return
conversation_id = row.id
owner_user_id = row.owner_user_id
return None
return row.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)
async def bridge_workflow_event(
self,
*,
run_id: str,
event: dict[str, Any],
source_audit_event_id: str | None = None,
) -> bool:
"""Project a persisted per-run event onto the V2 conversation stream.
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
Returns ``True`` if at least one new conversation event was written,
``False`` if all items were deduped or unmapped.
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"]
All derived events from one audit event (e.g. ``agent.message.complete``
+ ``seat.delivery.submitted``) are written in a single transaction —
if any insert fails, the entire batch rolls back.
"""
from sqlalchemy import select
# P0-4: use the source audit event's stable id for dedup.
source_evt_id = event.get("id") or event.get("source_event_id")
items = self._build_projection_items(event, source_audit_event_id)
if not items:
return False
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
resolved = await self._resolve_conversation_for_run(run_id)
if resolved is None:
return False
conversation_id, _owner_user_id = resolved
written = 0
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:
return False
written = await self._store.append_conversation_events_idempotently(
db, conversation=conv, items=items,
)
if written > 0 and 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 written > 0
async def reconcile_conversation_events(self, *, run_id: str) -> int:
"""Re-project audit events for a run into the conversation stream.
Scans ``maf_roundtable_events`` for the given run and re-bridges each
event. Because ``bridge_workflow_event`` is idempotent (dedup via
``source_event_id``), this is safe to call after a crash, a restart,
or a projection failure. Events already projected are silently skipped.
Returns the number of **new** conversation events written (deduped
events are NOT counted).
"""
from sqlalchemy import select
from deerflow.persistence.maf_roundtable.model import MafRoundtableEventRow
written = 0
async with self._store.session_factory() as db:
rows = (
await db.execute(
select(MafRoundtableEventRow)
.where(MafRoundtableEventRow.run_id == run_id)
.order_by(MafRoundtableEventRow.seq.asc())
)
).scalars().all()
for row in rows:
event_dict: dict[str, Any] = {
"id": row.id,
"event_type": row.event_type,
"agent_id": row.agent_id,
"turn_index": row.turn_index,
"source_event_id": row.source_event_id,
"payload": row.payload_json,
}
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,
)
try:
if await self.bridge_workflow_event(
run_id=run_id,
event=event_dict,
source_audit_event_id=row.id,
):
written += 1
except Exception: # noqa: BLE001
logger.warning(
"reconcile: failed to project audit event %s for run %s",
row.id, run_id, exc_info=True,
)
return written
async def reconcile_active_conversations(self) -> int:
"""Scan active/recent MAF runs and reconcile their conversation projections.
Called by the background reconcile task and the SSE connect trigger.
Returns total new conversation events written across all runs.
"""
from sqlalchemy import select
from deerflow.persistence.maf_roundtable.model import (
MafRoundtableConversationRow,
MafRoundtableRunRow,
)
active_statuses = ("pending", "running", "waiting_approval", "waiting_input")
total = 0
async with self._store.session_factory() as db:
rows = (
await db.execute(
select(MafRoundtableRunRow.id)
.join(
MafRoundtableConversationRow,
MafRoundtableConversationRow.active_run_id == MafRoundtableRunRow.id,
)
.where(MafRoundtableRunRow.status.in_(active_statuses))
)
).scalars().all()
for run_id in rows:
try:
total += await self.reconcile_conversation_events(run_id=str(run_id))
except Exception: # noqa: BLE001
logger.warning("background reconcile: run %s failed", run_id, exc_info=True)
return total
async def _dispatch_run(self, *, conversation_id: str, user_id: str, run: dict[str, Any]) -> None:
if self._dispatcher is None:
@@ -620,6 +738,11 @@ class MafConversationService:
logger.exception("MAF conversation watcher failed run=%s", run_id)
return
try:
await self.reconcile_conversation_events(run_id=run_id)
except Exception: # noqa: BLE001
logger.warning("watcher reconcile failed run=%s", run_id, exc_info=True)
run = await self._store.runs.get_run(run_id)
if run is None:
return
@@ -473,9 +473,16 @@ class DeerFlowAgentAdapter:
# ── P1.6: audit event persistence ───────────────────────────────────────
async def _emit_critical(self, run_id: str, event: dict[str, Any]) -> None:
"""Emit a critical audit event. Failure raises AuditEventError."""
"""Emit a critical audit event. Failure raises AuditEventError.
The persisted audit event row's ``id`` is passed to the conversation
bridge as ``source_audit_event_id`` so projection dedup is always
keyed on the real audit row — not on an ephemeral input field that
may be absent for critical events.
"""
persisted: dict[str, Any] | None = None
try:
await self._service.append_event(
persisted = await self._service.append_event(
run_id=run_id,
user_id=self._user_id,
event_type=event["event_type"],
@@ -488,7 +495,11 @@ 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)
await self._bridge_conversation_event(
run_id,
event,
source_audit_event_id=persisted["id"] if persisted else None,
)
async def _emit(self, run_id: str, event: dict[str, Any]) -> None:
"""Emit a non-critical event (agent.message.delta). Failure degrades gracefully.
@@ -507,8 +518,9 @@ class DeerFlowAgentAdapter:
if event_type in _CRITICAL_EVENT_TYPES:
await self._emit_critical(run_id, event)
return
persisted: dict[str, Any] | None = None
try:
await self._service.append_event(
persisted = await self._service.append_event(
run_id=run_id,
user_id=self._user_id,
event_type=event_type,
@@ -520,15 +532,29 @@ 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)
await self._bridge_conversation_event(
run_id,
event,
source_audit_event_id=persisted["id"] if persisted else None,
)
async def _bridge_conversation_event(self, run_id: str, event: dict[str, Any]) -> None:
async def _bridge_conversation_event(
self,
run_id: str,
event: dict[str, Any],
*,
source_audit_event_id: str | None = None,
) -> 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.
seat run into a false runtime failure.
``source_audit_event_id`` is the real persisted audit row id — it is
always preferred over ``event["id"]`` / ``event["source_event_id"]``
for dedup (P0-4 fix). When the bridge retries after a restart, the
same audit id ensures the conversation event is written exactly once.
P0-3: the entire ``app.state`` resolution is best-effort. If any link
is missing (no app, no state, no conversation service), the projection
@@ -547,7 +573,11 @@ class DeerFlowAgentAdapter:
if not callable(bridge):
return
try:
await bridge(run_id=run_id, event=event)
await bridge(
run_id=run_id,
event=event,
source_audit_event_id=source_audit_event_id,
)
except Exception: # noqa: BLE001 - audit already persisted
logger.warning(
"conversation event projection failed for run %s (%s)",
@@ -9,6 +9,7 @@ tested with a weak/fake model and before any workflow is launched.
from __future__ import annotations
import json
from typing import Any, Literal
from pydantic import BaseModel, ConfigDict, Field, model_validator
@@ -23,6 +24,8 @@ MafIntentType = Literal[
"chain_consultation",
"tool_write",
]
MafExecutionMode = Literal["manager_only", "single", "parallel", "chain", "group_chat"]
MafDispatchSource = Literal["server", "manager", "deterministic_fallback"]
class DispatchConfigurationError(RuntimeError):
@@ -33,6 +36,18 @@ class InvalidDispatchPlanError(ValueError):
"""A proposed or constructed plan violates the dispatch contract."""
class MafDispatchCandidateSet(BaseModel):
"""Trusted route supplied to the manager before it chooses an intent."""
model_config = ConfigDict(extra="forbid")
manager_agent_id: str = Field(min_length=1, max_length=64)
candidate_seat_agent_ids: list[str] = Field(default_factory=list, max_length=64)
mode: MafMode = "structured"
business_code: str | None = Field(default=None, max_length=255)
max_rounds: int = Field(ge=1, le=64)
class MafIntentDecision(BaseModel):
model_config = ConfigDict(extra="forbid")
@@ -56,6 +71,87 @@ class MafDispatchAssignment(BaseModel):
agent_id: str = Field(min_length=1, max_length=64)
role: Literal["seat"] = "seat"
sort_order: int = Field(ge=1, le=64)
task_goal: str = Field(default="Complete the assigned analysis", min_length=1, max_length=2000)
delivery_requirements: list[str] = Field(default_factory=list, max_length=16)
class MafManagerPlanAssignment(BaseModel):
"""The only per-seat shape accepted from the manager model."""
model_config = ConfigDict(extra="forbid")
agent_id: str = Field(min_length=1, max_length=64)
task_goal: str = Field(min_length=1, max_length=2000)
delivery_requirements: list[str] = Field(min_length=1, max_length=16)
order: int = Field(ge=1, le=64)
class MafManagerPlanOutput(BaseModel):
"""Strict model-facing dispatch schema.
This model deliberately contains no thread, tool, capability, or user
supplied routing fields. The server validates the IDs again after this
schema passes.
"""
model_config = ConfigDict(extra="forbid")
intent_type: MafIntentType
selected_seat_agent_ids: list[str] = Field(default_factory=list, max_length=64)
assignments: list[MafManagerPlanAssignment] = Field(default_factory=list, max_length=64)
execution_mode: MafExecutionMode
convergence_path: list[str] = Field(min_length=1, max_length=16)
reason: str = Field(min_length=1, max_length=1000)
clarification_prompt: str | None = Field(default=None, min_length=1, max_length=1000)
@model_validator(mode="after")
def _validate_manager_shape(self) -> MafManagerPlanOutput:
selected = self.selected_seat_agent_ids
if len(set(selected)) != len(selected):
raise ValueError("manager plan contains duplicate seats")
assignment_ids = [item.agent_id for item in self.assignments]
if assignment_ids != selected:
raise ValueError("manager assignments must exactly match selected seats")
if [item.order for item in self.assignments] != list(range(1, len(selected) + 1)):
raise ValueError("manager assignment order must be contiguous")
required_mode: MafExecutionMode
if self.intent_type == "clarification":
if selected or self.assignments or self.execution_mode != "manager_only":
raise ValueError("clarification cannot select expert seats")
if not self.clarification_prompt:
raise ValueError("clarification requires clarification_prompt")
return self
if self.clarification_prompt is not None:
raise ValueError("only clarification may include clarification_prompt")
if self.intent_type == "direct_answer":
required_mode = "manager_only"
if selected:
raise ValueError("direct_answer cannot select expert seats")
elif self.intent_type in {"single_seat", "tool_write"}:
required_mode = "single"
if len(selected) != 1:
raise ValueError("single-seat intents require exactly one seat")
elif self.intent_type == "parallel_consultation":
required_mode = "parallel"
if not selected:
raise ValueError("parallel consultation requires a seat")
if len(selected) < 2:
raise ValueError("parallel consultation requires at least two seats")
elif self.intent_type == "chain_consultation":
required_mode = "chain"
if not selected:
raise ValueError("chain consultation requires a seat")
else:
raise ValueError("clarification cannot be dispatched")
allowed_modes = {required_mode}
if self.execution_mode == "group_chat" and required_mode != "manager_only":
allowed_modes.add("group_chat")
if self.execution_mode not in allowed_modes:
raise ValueError(
f"execution_mode {self.execution_mode!r} does not match {required_mode!r}"
)
return self
class MafDispatchPlan(BaseModel):
@@ -70,6 +166,11 @@ class MafDispatchPlan(BaseModel):
intent_type: MafIntentType
business_code: str | None = Field(default=None, max_length=255)
max_rounds: int = Field(ge=1, le=64)
candidate_seat_agent_ids: list[str] = Field(default_factory=list, max_length=64)
execution_mode: MafExecutionMode = "parallel"
convergence_path: list[str] = Field(default_factory=list, max_length=16)
reason: str = Field(default="server-owned route", min_length=1, max_length=1000)
source: MafDispatchSource = "server"
@model_validator(mode="after")
def _validate_shape(self) -> MafDispatchPlan:
@@ -77,6 +178,12 @@ class MafDispatchPlan(BaseModel):
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")
if len(set(self.candidate_seat_agent_ids)) != len(self.candidate_seat_agent_ids):
raise ValueError("duplicate candidate seat agent")
if self.candidate_seat_agent_ids and any(
agent_id not in self.candidate_seat_agent_ids for agent_id in self.seat_agent_ids
):
raise ValueError("selected seat is outside candidate seats")
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")
@@ -84,6 +191,22 @@ class MafDispatchPlan(BaseModel):
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":
if self.seat_agent_ids or self.execution_mode != "manager_only":
raise ValueError("direct_answer must use manager_only with no seats")
elif self.intent_type in {"single_seat", "tool_write"}:
if len(self.seat_agent_ids) != 1 or self.execution_mode not in {"single", "group_chat"}:
raise ValueError("single-seat intents require one seat and single mode")
elif self.intent_type == "parallel_consultation":
if not self.seat_agent_ids or self.execution_mode not in {"parallel", "group_chat"}:
raise ValueError("parallel consultation requires at least one configured seat")
if len(self.seat_agent_ids) < 2:
raise ValueError("parallel consultation requires at least two seats")
elif self.intent_type == "chain_consultation":
if not self.seat_agent_ids or self.execution_mode not in {"chain", "group_chat"}:
raise ValueError("chain consultation requires at least one configured seat")
if self.execution_mode == "group_chat" and self.mode != "group_chat":
raise ValueError("group_chat execution requires a group_chat route")
if self.intent_type != "direct_answer" and not self.seat_agent_ids:
raise ValueError("this intent requires at least one configured seat")
return self
@@ -149,6 +272,27 @@ class MafDispatchCatalog:
def __init__(self, maf_config: Any) -> None:
self._config = maf_config
def readiness(self) -> tuple[bool, str]:
"""Return non-sensitive deployment readiness for the conversation UI.
A manager-only route is sufficient for a safe direct answer. Expert
routes are checked separately when a request selects a business chain
and when the trusted capability snapshot is built for the user.
"""
manager = str(_read(self._config, "default_manager_agent_id", "") or "").strip()
routes = _read(self._config, "business_routes", {}) or {}
if manager:
return True, "default_manager_configured"
for business_code, route in routes.items():
route_manager = str(_read(route, "manager_agent_id", "") or "").strip()
if route_manager:
return True, f"business_route_configured:{business_code}"
return False, "no_trusted_manager_route"
@property
def conversation_dispatch_ready(self) -> bool:
return self.readiness()[0]
def _route(self, business_code: str | None) -> tuple[str | None, list[str], MafMode | None]:
routes = _read(self._config, "business_routes", {}) or {}
if business_code:
@@ -169,6 +313,40 @@ class MafDispatchCatalog:
None,
)
def build_candidate_set(
self, *, task_context: dict[str, Any] | None
) -> MafDispatchCandidateSet:
"""Build only the trusted route; intent remains a manager decision."""
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"
)
normalized_manager = str(manager_id).strip()
candidates = [str(agent_id).strip() for agent_id in route_seats]
max_seats = int(_read(self._config, "max_seats_per_run", 16) or 16)
# A route may intentionally be manager-only, but it must always have
# a concrete manager. Candidate seats are optional until the manager
# chooses an expert intent.
if not normalized_manager:
raise DispatchConfigurationError("trusted manager route is blank")
if len(candidates) > max_seats:
raise DispatchConfigurationError("configured MAF route exceeds max_seats_per_run")
if normalized_manager in candidates or len(set(candidates)) != len(candidates):
raise DispatchConfigurationError("configured MAF route contains duplicate agents")
try:
return MafDispatchCandidateSet(
manager_agent_id=normalized_manager,
candidate_seat_agent_ids=candidates,
mode=route_mode or _read(self._config, "default_mode", "structured"),
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
def build_plan(
self,
*,
@@ -184,27 +362,54 @@ class MafDispatchCatalog:
# 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"}:
candidate_seats = route_seats[:]
if intent.intent_type == "direct_answer":
seat_ids = []
execution_mode: MafExecutionMode = "manager_only"
elif intent.intent_type in {"single_seat", "tool_write"}:
seat_ids = route_seats[:1]
execution_mode = "single"
elif intent.intent_type == "chain_consultation":
seat_ids = route_seats[:]
execution_mode = "chain"
else:
seat_ids = route_seats[:]
execution_mode = "parallel"
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")
if intent.intent_type != "direct_answer" and not seat_ids:
raise DispatchConfigurationError("selected MAF intent requires a configured seat route")
if intent.intent_type == "parallel_consultation" and len(seat_ids) < 2:
raise DispatchConfigurationError(
"parallel consultation requires at least two configured seats"
)
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)
MafDispatchAssignment(
agent_id=str(agent_id).strip(),
sort_order=index,
task_goal=f"Complete the {intent.intent_type} task",
delivery_requirements=["structured result", "evidence or limitation notes"],
)
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),
candidate_seat_agent_ids=[str(agent_id).strip() for agent_id in candidate_seats],
execution_mode=execution_mode,
convergence_path=[
"manager answer" if intent.intent_type == "direct_answer" else "manager synthesis"
],
reason="server-owned candidate route",
source="server",
)
except (TypeError, ValueError) as exc:
raise DispatchConfigurationError("invalid trusted MAF dispatch route") from exc
@@ -214,8 +419,138 @@ class MafDispatchCatalog:
return plan
@staticmethod
def participants(plan: MafDispatchPlan) -> list[dict[str, Any]]:
def parse_manager_decision(
raw: str,
*,
candidate_set: MafDispatchCandidateSet,
max_seats: int,
capability_snapshot: dict[str, Any] | None = None,
) -> tuple[MafManagerPlanOutput, MafDispatchPlan | None]:
"""Parse the manager's complete intent + dispatch decision.
The manager may choose only from the server-provided candidate set.
A clarification is a valid terminal decision with no dispatch plan;
every malformed or unauthorized response raises for safe fallback.
"""
try:
payload = _extract_json_object(raw)
proposed = MafManagerPlanOutput.model_validate(payload)
except Exception as exc: # noqa: BLE001 - caller uses clarification fallback
raise InvalidDispatchPlanError("manager plan schema invalid") from exc
candidates = list(candidate_set.candidate_seat_agent_ids)
selected = list(proposed.selected_seat_agent_ids)
if any(agent_id not in candidates for agent_id in selected):
raise InvalidDispatchPlanError("manager selected a seat outside the candidate set")
if len(selected) > max_seats:
raise InvalidDispatchPlanError("manager plan exceeds the seat limit")
if candidate_set.manager_agent_id in selected:
raise InvalidDispatchPlanError("manager cannot select itself as a seat")
if proposed.execution_mode == "group_chat" and candidate_set.mode != "group_chat":
raise InvalidDispatchPlanError("group_chat is not enabled for this route")
if proposed.intent_type == "chain_consultation":
candidate_order = {agent_id: index for index, agent_id in enumerate(candidates)}
orders = [candidate_order[agent_id] for agent_id in selected]
if orders != sorted(orders):
raise InvalidDispatchPlanError(
"chain seats must preserve the configured business order"
)
if proposed.intent_type == "tool_write" and capability_snapshot is not None:
agents = capability_snapshot.get("agents")
by_id = {
str(agent.get("agent_id")): agent
for agent in agents or []
if isinstance(agent, dict)
}
if not any(
any(
isinstance(tool, dict) and tool.get("side_effect") == "write"
for tool in (by_id.get(agent_id, {}).get("tools") or [])
)
for agent_id in selected
):
raise InvalidDispatchPlanError("tool_write has no trusted write-capable seat")
if proposed.intent_type == "clarification":
return proposed, None
assignments = [
MafDispatchAssignment(
agent_id=item.agent_id,
sort_order=item.order,
task_goal=item.task_goal,
delivery_requirements=list(item.delivery_requirements),
)
for item in proposed.assignments
]
try:
plan = MafDispatchPlan(
manager_agent_id=candidate_set.manager_agent_id,
seat_agent_ids=selected,
assignments=assignments,
mode=candidate_set.mode,
intent_type=proposed.intent_type,
business_code=candidate_set.business_code,
max_rounds=candidate_set.max_rounds,
candidate_seat_agent_ids=candidates,
execution_mode=proposed.execution_mode,
convergence_path=list(proposed.convergence_path),
reason=proposed.reason,
source="manager",
)
except (TypeError, ValueError) as exc:
raise InvalidDispatchPlanError("manager plan failed final validation") from exc
return proposed, plan
@staticmethod
def parse_manager_plan(
raw: str,
*,
expected_intent: MafIntentType,
server_plan: MafDispatchPlan,
max_seats: int,
) -> MafDispatchPlan:
"""Compatibility wrapper for callers with a pre-resolved intent."""
candidate_set = MafDispatchCandidateSet(
manager_agent_id=server_plan.manager_agent_id,
candidate_seat_agent_ids=list(server_plan.candidate_seat_agent_ids),
mode=server_plan.mode,
business_code=server_plan.business_code,
max_rounds=server_plan.max_rounds,
)
proposed, plan = MafDispatchCatalog.parse_manager_decision(
raw,
candidate_set=candidate_set,
max_seats=max_seats,
)
if proposed.intent_type != expected_intent:
raise InvalidDispatchPlanError("manager changed the expected intent")
if plan is None:
raise InvalidDispatchPlanError("clarification is not a dispatch plan")
return plan
@staticmethod
def deterministic_fallback_plan(server_plan: MafDispatchPlan) -> MafDispatchPlan:
"""Use the server route without ever expanding model permissions."""
return server_plan.model_copy(
update={
"seat_agent_ids": list(server_plan.seat_agent_ids),
"assignments": [item.model_copy() for item in server_plan.assignments],
"source": "deterministic_fallback",
"reason": "manager_plan_invalid_safe_route",
}
)
@staticmethod
def participants(
plan: MafDispatchPlan, *, include_candidates: bool = True
) -> list[dict[str, Any]]:
"""Return persistence records; thread ids are intentionally absent."""
candidate_seats = (
list(plan.candidate_seat_agent_ids)
if include_candidates and plan.intent_type != "direct_answer"
else []
)
return [
{
"agent_id": plan.manager_agent_id,
@@ -225,15 +560,76 @@ class MafDispatchCatalog:
},
*[
{
"agent_id": assignment.agent_id,
"agent_id": agent_id,
"role": "seat",
"sort_order": assignment.sort_order,
"sort_order": index,
"display_name": "",
}
for assignment in plan.assignments
for index, agent_id in enumerate(candidate_seats, start=1)
],
]
@staticmethod
def candidate_participants(
candidate_set: MafDispatchCandidateSet,
*,
include_seats: bool = True,
capability_snapshot: dict[str, Any] | None = None,
) -> list[dict[str, Any]]:
"""Build ephemeral snapshot inputs or persisted manager-only records."""
snapshots = {
str(agent.get("agent_id")): dict(agent)
for agent in (capability_snapshot or {}).get("agents", [])
if isinstance(agent, dict)
}
rows = [{
"agent_id": candidate_set.manager_agent_id,
"role": "manager",
"sort_order": 0,
"display_name": "",
"capability_snapshot": snapshots.get(candidate_set.manager_agent_id, {}),
}]
if include_seats:
rows.extend({
"agent_id": agent_id,
"role": "seat",
"sort_order": index,
"display_name": "",
"capability_snapshot": snapshots.get(agent_id, {}),
} for index, agent_id in enumerate(candidate_set.candidate_seat_agent_ids, start=1))
return rows
@staticmethod
def manager_capability_summary(
snapshot: dict[str, Any] | None,
candidate_set: MafDispatchCandidateSet,
) -> list[dict[str, Any]]:
"""Return only safe, non-secret capability facts for the manager prompt."""
by_id = {
str(agent.get("agent_id")): agent
for agent in (snapshot or {}).get("agents", [])
if isinstance(agent, dict)
}
result: list[dict[str, Any]] = []
for agent_id in candidate_set.candidate_seat_agent_ids:
agent = by_id.get(agent_id, {})
tools = [
{
"tool_name": str(tool.get("tool_name")),
"side_effect": tool.get("side_effect", "write"),
"risk_level": tool.get("risk_level", "R3"),
}
for tool in (agent.get("tools") or [])
if isinstance(tool, dict) and tool.get("tool_name")
]
result.append({
"agent_id": agent_id,
"model_name": agent.get("model_name"),
"tool_names": [tool["tool_name"] for tool in tools],
"tool_summary": tools,
})
return result
def validate_dispatch_plan(
plan: MafDispatchPlan,
@@ -255,10 +651,31 @@ def validate_dispatch_plan(
raise InvalidDispatchPlanError("manager cannot be dispatched as a seat")
def _extract_json_object(raw: str) -> dict[str, Any]:
text = str(raw or "").strip()
if not text:
raise ValueError("empty manager plan")
try:
value = json.loads(text)
except json.JSONDecodeError:
start = text.find("{")
end = text.rfind("}")
if start < 0 or end <= start:
raise ValueError("manager plan is not JSON")
value = json.loads(text[start:end + 1])
if not isinstance(value, dict):
raise ValueError("manager plan must be a JSON object")
return value
__all__ = [
"DispatchConfigurationError",
"InvalidDispatchPlanError",
"MafDispatchAssignment",
"MafDispatchCandidateSet",
"MafExecutionMode",
"MafManagerPlanAssignment",
"MafManagerPlanOutput",
"MafDispatchPlan",
"MafDispatchCatalog",
"MafIntentDecision",
@@ -254,6 +254,11 @@ class HealthResponse(BaseModel):
"""
enabled: bool
conversation_dispatch_ready: bool = False
conversation_dispatch_status: str = "configuration_unavailable"
conversation_stream_ready: bool = False
conversation_stream_status: str = "unknown"
conversation_event_backend: str = "memory"
store_available: bool
default_mode: str
default_write_policy: str
@@ -14,6 +14,7 @@ Group-chat still uses CoordinatorExecutor for speaker selection.
from __future__ import annotations
import asyncio
import json
import logging
from typing import Any
@@ -25,6 +26,12 @@ from app.maf_roundtable.action_coordinator import (
tool_needs_approval,
)
from app.maf_roundtable.context_builder import build_manager_synthesis_input
from app.maf_roundtable.dispatch_contracts import (
InvalidDispatchPlanError,
MafDispatchCandidateSet,
MafDispatchCatalog,
MafDispatchPlan,
)
from app.maf_roundtable.fact_ledger import (
confirm_candidates,
empty_ledger,
@@ -76,6 +83,8 @@ class RoundtableState:
schema_repair_enabled: bool = True,
intent_type: str | None = None,
dispatch_plan: dict[str, Any] | None = None,
candidate_seat_agent_ids: list[str] | None = None,
dispatch_contract_enabled: bool | None = None,
) -> None:
self.session_id = session_id
self.run_id = run_id
@@ -96,6 +105,18 @@ class RoundtableState:
# id from manager model output.
self.intent_type = intent_type
self.dispatch_plan = dispatch_plan
self.dispatch_contract_enabled = (
bool(dispatch_plan is not None or intent_type is not None)
if dispatch_contract_enabled is None
else bool(dispatch_contract_enabled)
)
plan_seats = list((dispatch_plan or {}).get("seat_agent_ids") or [])
self.candidate_seat_agent_ids = list(
(dispatch_plan or {}).get("candidate_seat_agent_ids")
or candidate_seat_agent_ids
or seat_agent_ids
)
self.selected_seat_agent_ids: list[str] | None = plan_seats or None
self.current_round = 0
self.turn_results: list[dict[str, Any]] = []
@@ -137,6 +158,9 @@ class RoundtableState:
"schema_repair_enabled": self.schema_repair_enabled,
"intent_type": self.intent_type,
"dispatch_plan": self.dispatch_plan,
"dispatch_contract_enabled": self.dispatch_contract_enabled,
"candidate_seat_agent_ids": list(self.candidate_seat_agent_ids),
"selected_seat_agent_ids": self.selected_seat_agent_ids,
"current_round": self.current_round,
"turn_results": self.turn_results,
"fact_ledger": self.fact_ledger,
@@ -170,6 +194,8 @@ class RoundtableState:
schema_repair_enabled=bool(d.get("schema_repair_enabled", True)),
intent_type=d.get("intent_type"),
dispatch_plan=d.get("dispatch_plan"),
candidate_seat_agent_ids=d.get("candidate_seat_agent_ids"),
dispatch_contract_enabled=d.get("dispatch_contract_enabled"),
)
state.current_round = d.get("current_round", 0)
state.turn_results = d.get("turn_results", [])
@@ -186,62 +212,59 @@ class RoundtableState:
state.stage = d.get("stage") or "planning"
state.partial_failure = bool(d.get("partial_failure", False))
state.cross_review_result = d.get("cross_review_result")
state.candidate_seat_agent_ids = list(
d.get("candidate_seat_agent_ids") or state.candidate_seat_agent_ids
)
selected = d.get("selected_seat_agent_ids")
state.selected_seat_agent_ids = list(selected) if selected is not None else None
state.dispatch_contract_enabled = bool(
d.get("dispatch_contract_enabled", state.dispatch_contract_enabled)
)
return state
# ── Planner (structured) ────────────────────────────────────────────────────
class PlannerExecutor(Executor):
"""Produce per-seat assignments for the structured expert stage."""
class ManagerAnswerExecutor(Executor):
"""Manager-only topology for ordinary direct answers."""
def __init__(self, adapter: Any, state: RoundtableState) -> None:
super().__init__(id="planner")
super().__init__(id="manager_answer")
self._adapter = adapter
self._state = state
@handler(input=Any, output=dict)
@handler(input=Any, workflow_output=dict)
async def handle(self, message: Any, ctx: WorkflowContext) -> None:
if self._state.is_completed("planner"):
await ctx.send_message({"decision": "parallel_seats", "agents": self._state.seat_agent_ids, "replayed": True})
if self._state.is_completed("manager_answer") and self._state.final_result is not None:
self._state.status = "completed"
await ctx.yield_output({"final_result": self._state.final_result, "replayed": True})
return
self._state.stage = "planning"
self._state.current_round = max(self._state.current_round, 1)
assignments = {
aid: {
"role": f"专家席位 {aid}",
"instruction": (
f"请作为席位 {aid} 独立分析任务,可使用你的工具与技能。"
f"{seat_output_instruction()}"
),
manager_id = self._state.manager_agent_id or ""
thread_id = self._state.thread_map.get(manager_id, "")
if not thread_id:
self._state.status = "failed"
self._state.final_result = {
"content": "MAF manager thread is unavailable",
"agent_id": manager_id,
"error_code": "manager_thread_unavailable",
}
for aid in self._state.seat_agent_ids
}
manager_id = self._state.manager_agent_id
thread_id = self._state.thread_map.get(manager_id or "", "")
if manager_id and thread_id:
else:
try:
plan_prompt = (
f"任务:{self._state.task_text}\n"
f"参与席位:{', '.join(self._state.seat_agent_ids)}\n"
"请为每个席位给出简短分工说明。可用纯文本;系统会据此填充各席位指令。"
)
response = await asyncio.wait_for(
self._adapter.run_seat_turn(
session_id=self._state.session_id,
run_id=self._state.run_id,
agent_id=manager_id,
turn_index=0,
execution_stage="planner",
message=plan_prompt,
execution_stage="direct_answer",
message=self._state.task_text,
thread_id=thread_id,
model_name=self._state.model_name,
reasoning_effort=self._state.reasoning_effort,
task_text=plan_prompt,
stage_instruction="任务规划与分工",
task_text=self._state.task_text,
stage_instruction="Answer the user directly; do not delegate to expert seats",
fact_ledger=self._state.fact_ledger,
capability_snapshot=self._state.capability_snapshot,
write_policy=self._state.write_policy,
@@ -249,31 +272,247 @@ class PlannerExecutor(Executor):
),
timeout=self._state.seat_timeout_seconds,
)
plan_text = (response.content or "").strip()
if plan_text:
for aid in self._state.seat_agent_ids:
assignments[aid]["instruction"] = (
f"{plan_text[:1500]}\n\n你的席位 id={aid}。\n{seat_output_instruction()}"
)
self._state.plan = {"source": "manager", "text": plan_text, "assignments": assignments}
if response.error:
self._state.status = "failed"
else:
self._state.plan = {"source": "deterministic", "assignments": assignments}
except Exception as exc: # noqa: BLE001
logger.warning("planner manager turn failed (%s); using deterministic plan", type(exc).__name__)
self._state.plan = {"source": "deterministic", "assignments": assignments}
self._state.status = "completed"
self._state.final_result = {
"content": response.content,
"agent_id": manager_id,
"error": response.error,
"quality_decision": "accept" if not response.error else "controlled_gap",
}
except Exception as exc: # noqa: BLE001 - runner persists a safe failure
self._state.status = "failed"
self._state.final_result = {
"content": "MAF manager answer failed",
"agent_id": manager_id,
"error_code": type(exc).__name__,
}
self._state.stage = "done"
self._state.mark_completed("manager_answer")
dispatch_plan = MafDispatchPlan.model_validate(self._state.dispatch_plan or {
"manager_agent_id": manager_id,
"seat_agent_ids": [],
"assignments": [],
"intent_type": "direct_answer",
"max_rounds": self._state.max_rounds,
"candidate_seat_agent_ids": list(self._state.candidate_seat_agent_ids),
"execution_mode": "manager_only",
"convergence_path": ["manager answer"],
"reason": "direct answer uses manager only",
"source": "server",
})
self._state.dispatch_plan = dispatch_plan.model_dump(mode="json")
store = getattr(getattr(self._adapter, "_service", None), "store", None)
if store is not None:
await store.runs.update_run(
self._state.run_id,
{"maf_checkpoint": self._state.to_dict()},
)
if not self._state.dispatch_contract_enabled:
await self._adapter._emit_critical(self._state.run_id, {
"event_type": "manager.dispatch",
"agent_id": manager_id,
"turn_index": 0,
"payload": {
"intent_type": dispatch_plan.intent_type,
"execution_mode": dispatch_plan.execution_mode,
"convergence_path": list(dispatch_plan.convergence_path),
"selected_seat_agent_ids": [],
"assignments": [],
"reason": dispatch_plan.reason,
"source": dispatch_plan.source,
},
})
from app.maf_roundtable.event_normalizer import make_run_completed
await self._adapter._emit_critical(
self._state.run_id,
make_run_completed(manager_id, 1, {"manager_only": True}),
)
await ctx.yield_output({"final_result": self._state.final_result})
class ManagerDispatchExecutor(Executor):
"""Understand intent and emit one server-validated dispatch decision."""
def __init__(
self, adapter: Any, state: RoundtableState, *, executor_id: str = "manager_dispatch"
) -> None:
super().__init__(id=executor_id)
self._adapter = adapter
self._state = state
self._node_id = executor_id
def _dispatch_decision(self) -> str:
plan = self._state.dispatch_plan or {}
if self._state.intent_type == "clarification" or not plan:
return "clarification"
if plan.get("execution_mode") == "manager_only":
return "manager_only"
if plan.get("mode") == "group_chat" or plan.get("execution_mode") == "group_chat":
return "group_chat"
return "selected_seats"
@handler(input=Any, output=dict)
async def handle(self, message: Any, ctx: WorkflowContext) -> None:
if self._state.is_completed(self._node_id):
await ctx.send_message({
"decision": self._dispatch_decision(),
"agents": list(self._state.selected_seat_agent_ids or []),
"execution_mode": (self._state.dispatch_plan or {}).get("execution_mode"),
"replayed": True,
})
return
self._state.stage = "planning"
# Legacy MAF roundtable runs do not carry the V2 conversation dispatch
# contract. Keep their planner semantics isolated from the new MAF
# conversation workflow; in particular, old seat-only runs may have no
# manager at all.
if not self._state.dispatch_contract_enabled:
self._state.current_round = max(self._state.current_round, 1)
await _run_legacy_planner(self, ctx)
return
# The manager plan is a strict JSON contract. Legacy free-text
# planning is isolated in _run_legacy_planner; new Stage 3 runs
# always return through this verifier.
await _resolve_manager_dispatch(self, ctx)
return
async def _run_legacy_planner(executor: ManagerDispatchExecutor, ctx: WorkflowContext) -> None:
"""Keep the pre-V2 free-text planner isolated from new conversations."""
state = executor._state
if state.is_completed(executor._node_id):
await ctx.send_message({"decision": "parallel_seats", "agents": list(state.seat_agent_ids), "replayed": True})
return
assignments = {
agent_id: {
"role": f"Expert seat {agent_id}",
"instruction": f"Independently analyze the task. {seat_output_instruction()}",
}
for agent_id in state.seat_agent_ids
}
manager_id = state.manager_agent_id
thread_id = state.thread_map.get(manager_id or "", "")
if manager_id and thread_id:
try:
response = await asyncio.wait_for(
executor._adapter.run_seat_turn(
session_id=state.session_id,
run_id=state.run_id,
agent_id=manager_id,
turn_index=0,
execution_stage="planner",
message=state.task_text,
thread_id=thread_id,
model_name=state.model_name,
reasoning_effort=state.reasoning_effort,
task_text=state.task_text,
stage_instruction="Produce a concise assignment for each configured expert seat.",
fact_ledger=state.fact_ledger,
capability_snapshot=state.capability_snapshot,
write_policy=state.write_policy,
wait_timeout_seconds=state.seat_timeout_seconds,
),
timeout=state.seat_timeout_seconds,
)
plan_text = (response.content or "").strip()
if plan_text:
for agent_id in state.seat_agent_ids:
assignments[agent_id]["instruction"] = f"{plan_text[:1500]}\n\nSeat id: {agent_id}.\n{seat_output_instruction()}"
state.plan = {"source": "manager", "text": plan_text, "assignments": assignments}
else:
state.plan = {"source": "deterministic", "assignments": assignments}
except Exception as exc: # noqa: BLE001 - legacy path deliberately degrades
logger.warning("legacy planner failed (%s); using deterministic plan", type(exc).__name__)
state.plan = {"source": "deterministic", "assignments": assignments}
else:
state.plan = {"source": "deterministic", "assignments": assignments}
state.mark_completed(executor._node_id)
state.stage = "experts"
await ctx.send_message({"decision": "parallel_seats", "agents": list(state.seat_agent_ids)})
class PlannerExecutor(ManagerDispatchExecutor):
"""Compatibility node retained solely for pre-V2 MAF roundtable runs."""
def __init__(self, adapter: Any, state: RoundtableState) -> None:
super().__init__(adapter, state, executor_id="planner")
class DispatchRouteExecutor(Executor):
"""Route only from the verified, persisted manager dispatch decision."""
def __init__(self, state: RoundtableState) -> None:
super().__init__(id="dispatch_route")
self._state = state
@handler(input=Any, output=dict)
async def handle(self, message: Any, ctx: WorkflowContext) -> None:
plan = self._state.dispatch_plan or {}
if self._state.intent_type == "clarification" or not plan:
decision = "clarification"
elif plan.get("execution_mode") == "manager_only":
decision = "manager_only"
elif plan.get("mode") == "group_chat" or plan.get("execution_mode") == "group_chat":
decision = "group_chat"
else:
self._state.plan = {"source": "deterministic", "assignments": assignments}
decision = "selected_seats"
await ctx.send_message({"decision": decision, "agents": list(self._state.selected_seat_agent_ids or [])})
self._state.mark_completed("planner")
class DispatchSeatEntryExecutor(Executor):
"""Start seat work only after the manager's plan and threads are durable."""
def __init__(self, state: RoundtableState) -> None:
super().__init__(id="dispatch_seat_entry")
self._state = state
@handler(input=Any, output=dict)
async def handle(self, message: Any, ctx: WorkflowContext) -> None:
self._state.stage = "experts"
await ctx.send_message({"decision": "parallel_seats", "agents": self._state.seat_agent_ids})
await ctx.send_message({"agents": list(self._state.selected_seat_agent_ids or [])})
# ── Coordinator (group_chat) ────────────────────────────────────────────────
class ClarificationTerminalExecutor(Executor):
"""Safe terminal branch for invalid, unauthorized, or timed-out planning."""
def __init__(self, state: RoundtableState) -> None:
super().__init__(id="clarification_terminal")
self._state = state
@handler(input=Any, workflow_output=dict)
async def handle(self, message: Any, ctx: WorkflowContext) -> None:
self._state.status = "waiting_input"
self._state.stage = "waiting_input"
self._state.mark_completed("clarification_terminal")
await ctx.yield_output({"status": "waiting_input", "clarification_prompt": (self._state.dispatch_plan or {}).get("clarification_prompt")})
class DispatchPreparationTerminalExecutor(Executor):
"""End the manager-only preparation graph before topology is selected."""
def __init__(self, state: RoundtableState) -> None:
super().__init__(id="dispatch_preparation_terminal")
self._state = state
@handler(input=Any, workflow_output=dict)
async def handle(self, message: Any, ctx: WorkflowContext) -> None:
self._state.mark_completed("dispatch_preparation_terminal")
await ctx.yield_output({
"decision": "clarification" if self._state.intent_type == "clarification" else "dispatched",
"status": self._state.status,
})
class CoordinatorExecutor(Executor):
"""Decides which seat speaks next, whether to continue or finish (group_chat)."""
"""Choose the next selected group-chat speaker without widening the plan."""
def __init__(self, adapter: Any, state: RoundtableState) -> None:
super().__init__(id="coordinator")
@@ -282,41 +521,302 @@ class CoordinatorExecutor(Executor):
@handler(input=Any, output=dict)
async def handle(self, message: Any, ctx: WorkflowContext) -> None:
self._state.current_round += 1
if self._state.stage == "dispatch_validated" and self._state.current_round == 0:
self._state.current_round = 1
else:
self._state.current_round += 1
if self._state.current_round > self._state.max_rounds:
await ctx.send_message({"decision": "done", "reason": "max_rounds_reached"})
return
if self._state.mode == "structured":
# Structured mode no longer uses the coordinator; keep a safe fallback.
if self._state.current_round == 1:
await ctx.send_message({"decision": "parallel_seats", "agents": self._state.seat_agent_ids})
return
await ctx.send_message({"decision": "done", "reason": "structured_complete"})
return
eligible = list(self._state.selected_seat_agent_ids) if self._state.selected_seat_agent_ids is not None else list(self._state.seat_agent_ids)
remaining = [
a for a in self._state.seat_agent_ids
if not any(
r.get("agent_id") == a and r.get("turn_index", 0) >= self._state.current_round - 1
for r in self._state.turn_results
)
agent_id for agent_id in eligible
if not any(row.get("agent_id") == agent_id and row.get("turn_index", 0) >= self._state.current_round - 1 for row in self._state.turn_results)
]
if not remaining:
await ctx.send_message({"decision": "done", "reason": "all_seats_spoke"})
await ctx.send_message({"decision": "done", "reason": "all_selected_seats_spoke"})
return
next_agent = remaining[(self._state.current_round - 1) % len(remaining)]
await self._adapter._emit_critical(self._state.run_id, {
"event_type": "manager.decision",
"agent_id": self._state.manager_agent_id or "coordinator",
"turn_index": self._state.current_round,
"payload": {"next_speaker": next_agent, "reason": "round_robin", "round": self._state.current_round},
"payload": {"next_speaker": next_agent, "reason": "selected_plan_round_robin", "round": self._state.current_round},
})
await ctx.send_message({"decision": "next_speaker", "agent_id": next_agent})
async def _persist_dispatch_checkpoint(adapter: Any, state: RoundtableState) -> None:
store = getattr(getattr(adapter, "_service", None), "store", None)
if store is not None:
await store.runs.update_run(state.run_id, {"maf_checkpoint": state.to_dict()})
async def _emit_dispatch_event(
adapter: Any,
state: RoundtableState,
*,
clarification_prompt: str | None = None,
) -> None:
plan = state.dispatch_plan or {}
payload: dict[str, Any] = {
"intent_type": state.intent_type,
"execution_mode": plan.get("execution_mode", "manager_only"),
"selected_seat_agent_ids": list(state.selected_seat_agent_ids or []),
"assignments": plan.get("assignments", []),
"convergence_path": plan.get("convergence_path", []),
"reason": plan.get("reason", "manager_plan_invalid_safe_clarification"),
"source": plan.get("source", "deterministic_fallback"),
}
if clarification_prompt:
payload["clarification_prompt"] = clarification_prompt
await adapter._emit_critical(state.run_id, {
"event_type": "manager.dispatch",
"agent_id": state.manager_agent_id or "",
"turn_index": 0,
"payload": payload,
})
async def _ensure_selected_seat_threads(adapter: Any, state: RoundtableState) -> None:
"""Persist and bind threads only for server-validated selected seats."""
selected = list(state.selected_seat_agent_ids or [])
if not selected:
return
store = getattr(getattr(adapter, "_service", None), "store", None)
participants_repo = getattr(store, "participants", None)
if participants_repo is None:
return
route_mode = state.mode if state.mode in {"structured", "group_chat"} else "structured"
candidate_set = MafDispatchCandidateSet(
manager_agent_id=str(state.manager_agent_id or ""),
candidate_seat_agent_ids=list(state.candidate_seat_agent_ids),
mode=route_mode,
max_rounds=state.max_rounds,
)
candidate_rows = MafDispatchCatalog.candidate_participants(
candidate_set,
capability_snapshot=state.capability_snapshot,
)
selected_rows = [row for row in candidate_rows if row.get("agent_id") in selected]
await participants_repo.ensure_participants(state.session_id, selected_rows)
persisted = await participants_repo.list_participants(state.session_id)
selected_persisted = [row for row in persisted if row.get("agent_id") in selected]
if selected_persisted:
state.thread_map.update(
await adapter.ensure_threads(state.session_id, state.run_id, selected_persisted)
)
async def _resolve_manager_dispatch(
executor: ManagerDispatchExecutor, ctx: WorkflowContext
) -> None:
"""Run, validate, persist, and route the sole V2 manager dispatch turn."""
adapter = executor._adapter
state = executor._state
manager_id = str(state.manager_agent_id or "").strip()
route_mode = state.mode if state.mode in {"structured", "group_chat"} else "structured"
candidate_set = MafDispatchCandidateSet(
manager_agent_id=manager_id,
candidate_seat_agent_ids=list(state.candidate_seat_agent_ids),
mode=route_mode,
max_rounds=state.max_rounds,
)
async def clarification(reason: str) -> None:
prompt = "Please clarify the goal, expected outcome, and relevant business context."
state.intent_type = "clarification"
state.dispatch_plan = {
"execution_mode": "manager_only",
"convergence_path": ["clarification"],
"reason": reason,
"source": "deterministic_fallback",
"clarification_prompt": prompt,
}
state.selected_seat_agent_ids = []
state.plan = None
state.status = "waiting_input"
state.stage = "waiting_input"
state.mark_completed(executor._node_id)
await _persist_dispatch_checkpoint(adapter, state)
await _emit_dispatch_event(adapter, state, clarification_prompt=prompt)
await adapter._emit_critical(state.run_id, {
"event_type": "clarification.required",
"agent_id": manager_id,
"turn_index": 0,
"payload": {"prompt": prompt, "reason": reason},
})
await ctx.send_message({"decision": "clarification", "agents": []})
# A checkpoint written after validation survives process recovery and is
# never re-planned. It still creates any selected threads that were not
# bound before interruption.
if state.dispatch_plan and state.intent_type:
try:
existing = MafDispatchPlan.model_validate(state.dispatch_plan)
except (TypeError, ValueError):
await clarification("checkpoint_dispatch_plan_invalid")
return
state.selected_seat_agent_ids = list(existing.seat_agent_ids)
state.plan = {
"source": existing.source,
"assignments": {
assignment.agent_id: {
"role": assignment.role,
"instruction": "\n".join(
[assignment.task_goal, *assignment.delivery_requirements]
),
}
for assignment in existing.assignments
},
}
await _ensure_selected_seat_threads(adapter, state)
state.mark_completed(executor._node_id)
await _persist_dispatch_checkpoint(adapter, state)
await ctx.send_message({
"decision": executor._dispatch_decision(),
"agents": list(state.selected_seat_agent_ids or []),
"replayed": True,
})
return
thread_id = state.thread_map.get(manager_id, "")
if not manager_id or not thread_id:
await clarification("manager_thread_unavailable")
return
capability_summary = MafDispatchCatalog.manager_capability_summary(
state.capability_snapshot,
candidate_set,
)
manager_tool_names = [
str(tool.get("tool_name"))
for agent in (state.capability_snapshot or {}).get("agents", [])
if isinstance(agent, dict) and agent.get("agent_id") == manager_id
for tool in (agent.get("tools") or [])
if isinstance(tool, dict) and tool.get("tool_name")
]
contract = {
"intent_type": "direct_answer|clarification|single_seat|parallel_consultation|chain_consultation|tool_write",
"selected_seat_agent_ids": "candidate IDs only",
"assignments": "one ordered task_goal and delivery_requirements entry per selected seat",
"execution_mode": "manager_only|single|parallel|chain|group_chat",
"convergence_path": ["how work converges"],
"reason": "brief explanation",
"clarification_prompt": "required only for clarification",
}
prompt = (
"You are the MAF manager. Determine the user intent and return exactly one JSON object, "
"without Markdown. You may select only from the trusted candidate seats and their redacted "
"capabilities. Invalid or uncertain requests must use clarification; never invent a seat, "
"tool, capability, or route.\n\n"
f"User task:\n{state.task_text}\n\n"
f"Trusted route mode: {candidate_set.mode}\n"
f"Trusted candidate seats: {json.dumps(candidate_set.candidate_seat_agent_ids)}\n"
f"Trusted capability summary: {json.dumps(capability_summary, ensure_ascii=False)}\n"
f"Required JSON shape: {json.dumps(contract)}"
)
try:
response = await asyncio.wait_for(
adapter.run_seat_turn(
session_id=state.session_id,
run_id=state.run_id,
agent_id=manager_id,
turn_index=0,
execution_stage="manager_dispatch",
message=prompt,
thread_id=thread_id,
model_name=state.model_name,
reasoning_effort=state.reasoning_effort,
task_text=state.task_text,
stage_instruction="Return only the strict MAF dispatch JSON object.",
excluded_tools=manager_tool_names,
fact_ledger=state.fact_ledger,
capability_snapshot=state.capability_snapshot,
write_policy=state.write_policy,
wait_timeout_seconds=state.seat_timeout_seconds,
),
timeout=state.seat_timeout_seconds,
)
except TimeoutError:
await clarification("manager_dispatch_timeout")
return
except Exception: # noqa: BLE001 - model/runtime details must not reach the user
await clarification("manager_dispatch_failed")
return
if response.error:
await clarification("manager_dispatch_failed")
return
try:
proposed, plan = MafDispatchCatalog.parse_manager_decision(
response.content or "",
candidate_set=candidate_set,
max_seats=len(candidate_set.candidate_seat_agent_ids),
capability_snapshot=state.capability_snapshot,
)
except InvalidDispatchPlanError:
await clarification("manager_dispatch_invalid")
return
state.intent_type = proposed.intent_type
if plan is None:
state.dispatch_plan = {
"execution_mode": "manager_only",
"convergence_path": list(proposed.convergence_path),
"reason": proposed.reason,
"source": "manager",
"clarification_prompt": proposed.clarification_prompt,
}
state.selected_seat_agent_ids = []
state.plan = None
state.status = "waiting_input"
state.stage = "waiting_input"
state.mark_completed(executor._node_id)
await _persist_dispatch_checkpoint(adapter, state)
await _emit_dispatch_event(
adapter,
state,
clarification_prompt=proposed.clarification_prompt,
)
await adapter._emit_critical(state.run_id, {
"event_type": "clarification.required",
"agent_id": manager_id,
"turn_index": 0,
"payload": {"prompt": proposed.clarification_prompt, "reason": proposed.reason},
})
await ctx.send_message({"decision": "clarification", "agents": []})
return
state.dispatch_plan = plan.model_dump(mode="json")
state.selected_seat_agent_ids = list(plan.seat_agent_ids)
state.plan = {
"source": plan.source,
"assignments": {
assignment.agent_id: {
"role": assignment.role,
"instruction": "\n".join(
[assignment.task_goal, *assignment.delivery_requirements]
),
}
for assignment in plan.assignments
},
}
state.stage = "dispatch_validated"
# Persist before adding a participant or thread: recovery cannot obtain a
# different model decision after a process interruption.
await _persist_dispatch_checkpoint(adapter, state)
await _ensure_selected_seat_threads(adapter, state)
state.mark_completed(executor._node_id)
await _persist_dispatch_checkpoint(adapter, state)
await _emit_dispatch_event(adapter, state)
await ctx.send_message({
"decision": executor._dispatch_decision(),
"agents": list(state.selected_seat_agent_ids),
"execution_mode": plan.execution_mode,
})
# ── Seat executor ───────────────────────────────────────────────────────────
@@ -349,6 +849,17 @@ class SeatExecutor(Executor):
await ctx.send_message({"agent_id": self._agent_id, **prior, "replayed": True})
return
selected = self._state.selected_seat_agent_ids
if selected is not None and self._agent_id not in selected:
self._state.seat_outcomes[self._agent_id] = {"status": "skipped", "reason": "not_selected"}
self._state.mark_completed(node_id)
await ctx.send_message({
"agent_id": self._agent_id,
"status": "skipped",
"reason": "not_selected",
})
return
thread_id = self._state.thread_map.get(self._agent_id, "")
if not thread_id:
self._record_failure("no_thread", f"no thread for agent {self._agent_id}")
@@ -621,7 +1132,8 @@ class CrossReviewExecutor(Executor):
self._state.stage = "review"
# Barrier: ensure every seat has an outcome (fan-in should guarantee this).
missing = [a for a in self._state.seat_agent_ids if a not in self._state.seat_outcomes]
review_seats = self._state.selected_seat_agent_ids or self._state.seat_agent_ids
missing = [a for a in review_seats if a not in self._state.seat_outcomes]
for aid in missing:
self._state.seat_outcomes[aid] = {"status": "missing", "error": "no_outcome"}
self._state.partial_failure = True
@@ -654,7 +1166,7 @@ class CrossReviewExecutor(Executor):
try:
prompt = build_manager_synthesis_input(
task_text=self._state.task_text,
seat_results=[r for r in self._state.turn_results if r.get("agent_id") in self._state.seat_agent_ids],
seat_results=[r for r in self._state.turn_results if r.get("agent_id") in review_seats],
fact_ledger=self._state.fact_ledger,
)
# Surface the candidate ids + the evidence refs the ledger has
@@ -23,6 +23,24 @@ from typing import Any
logger = logging.getLogger(__name__)
def build_manager_dispatch_workflow(*, manager_dispatch: Any, terminal: Any) -> Any:
"""Run the constrained manager decision before building a work topology.
The resulting checkpoint is the sole input to the second workflow. This
prevents a route's configured default topology from pre-empting a manager
decision such as manager-only, chain, or group chat.
"""
from agent_framework import WorkflowBuilder
builder = WorkflowBuilder(
start_executor=manager_dispatch,
name="maf-manager-dispatch",
output_from=[terminal],
)
builder.add_edge(manager_dispatch, terminal)
return builder.build()
def build_structured_workflow(
*,
planner: Any,
@@ -31,6 +49,12 @@ def build_structured_workflow(
approval_gate: Any,
finalizer: Any,
waiting_terminal: Any,
execution_mode: str = "parallel",
manager_dispatch: Any | None = None,
dispatch_router: Any | None = None,
dispatch_seat_entry: Any | None = None,
manager_answer: Any | None = None,
clarification_terminal: Any | None = None,
) -> Any:
"""Build a structured (fixed-topology) MAF Workflow.
@@ -39,20 +63,53 @@ def build_structured_workflow(
"""
from agent_framework import Case, Default, WorkflowBuilder
start = manager_dispatch or planner
if start is None:
raise ValueError("structured mode requires manager_dispatch or planner")
outputs = [finalizer, waiting_terminal]
if manager_answer is not None:
outputs.append(manager_answer)
if clarification_terminal is not None:
outputs.append(clarification_terminal)
builder = WorkflowBuilder(
start_executor=planner,
start_executor=start,
name="maf-structured-roundtable",
output_from=[finalizer, waiting_terminal],
output_from=outputs,
)
if len(seat_executors) >= 2:
builder.add_fan_out_edges(planner, seat_executors)
seat_start = planner
if manager_dispatch is not None:
if dispatch_router is None or dispatch_seat_entry is None:
raise ValueError("manager_dispatch requires structured dispatch route executors")
builder.add_edge(manager_dispatch, dispatch_router)
cases = []
if manager_answer is not None:
cases.append(Case(
condition=lambda out: isinstance(out, dict) and out.get("decision") == "manager_only",
target=manager_answer,
))
if clarification_terminal is not None:
cases.append(Case(
condition=lambda out: isinstance(out, dict) and out.get("decision") == "clarification",
target=clarification_terminal,
))
cases.append(Default(target=dispatch_seat_entry))
builder.add_switch_case_edge_group(dispatch_router, cases)
seat_start = dispatch_seat_entry
if execution_mode == "chain" and seat_executors:
builder.add_edge(seat_start, seat_executors[0])
for previous, current in zip(seat_executors, seat_executors[1:]):
builder.add_edge(previous, current)
builder.add_edge(seat_executors[-1], cross_review)
elif len(seat_executors) >= 2:
builder.add_fan_out_edges(seat_start, seat_executors)
builder.add_fan_in_edges(seat_executors, cross_review)
elif len(seat_executors) == 1:
builder.add_edge(planner, seat_executors[0])
builder.add_edge(seat_start, seat_executors[0])
builder.add_edge(seat_executors[0], cross_review)
else:
builder.add_edge(planner, cross_review)
builder.add_edge(seat_start, cross_review)
builder.add_edge(cross_review, approval_gate)
@@ -67,6 +124,41 @@ def build_structured_workflow(
return builder.build()
def build_manager_only_workflow(
*,
manager_answer: Any,
manager_dispatch: Any | None = None,
dispatch_router: Any | None = None,
clarification_terminal: Any | None = None,
) -> Any:
"""Build the direct-answer topology with no expert seat nodes."""
from agent_framework import Case, Default, WorkflowBuilder
if manager_dispatch is None:
builder = WorkflowBuilder(
start_executor=manager_answer,
name="maf-manager-only",
output_from=[manager_answer],
)
return builder.build()
if dispatch_router is None or clarification_terminal is None:
raise ValueError("manager-only dispatch requires route and clarification executors")
builder = WorkflowBuilder(
start_executor=manager_dispatch,
name="maf-manager-only",
output_from=[manager_answer, clarification_terminal],
)
builder.add_edge(manager_dispatch, dispatch_router)
builder.add_switch_case_edge_group(dispatch_router, [
Case(
condition=lambda out: isinstance(out, dict) and out.get("decision") == "manager_only",
target=manager_answer,
),
Default(target=clarification_terminal),
])
return builder.build()
def build_group_chat_workflow(
*,
coordinator: Any,
@@ -75,6 +167,10 @@ def build_group_chat_workflow(
finalizer: Any,
waiting_terminal: Any,
seat_agent_ids: list[str],
manager_dispatch: Any | None = None,
dispatch_router: Any | None = None,
manager_answer: Any | None = None,
clarification_terminal: Any | None = None,
) -> Any:
"""Build a dynamic group-chat MAF Workflow.
@@ -83,12 +179,36 @@ def build_group_chat_workflow(
"""
from agent_framework import Case, Default, WorkflowBuilder
start = manager_dispatch or coordinator
outputs = [finalizer, waiting_terminal]
if manager_answer is not None:
outputs.append(manager_answer)
if clarification_terminal is not None:
outputs.append(clarification_terminal)
builder = WorkflowBuilder(
start_executor=coordinator,
start_executor=start,
name="maf-groupchat-roundtable",
output_from=[finalizer, waiting_terminal],
output_from=outputs,
)
if manager_dispatch is not None:
if dispatch_router is None:
raise ValueError("group_chat manager_dispatch requires a route executor")
builder.add_edge(manager_dispatch, dispatch_router)
cases = []
if manager_answer is not None:
cases.append(Case(
condition=lambda out: isinstance(out, dict) and out.get("decision") == "manager_only",
target=manager_answer,
))
if clarification_terminal is not None:
cases.append(Case(
condition=lambda out: isinstance(out, dict) and out.get("decision") == "clarification",
target=clarification_terminal,
))
cases.append(Default(target=coordinator))
builder.add_switch_case_edge_group(dispatch_router, cases)
cases = []
for i, agent_id in enumerate(seat_agent_ids):
cases.append(Case(
@@ -123,8 +243,23 @@ def create_workflow(
coordinator: Any | None = None,
planner: Any | None = None,
cross_review: Any | None = None,
manager_answer: Any | None = None,
execution_mode: str = "parallel",
manager_dispatch: Any | None = None,
dispatch_router: Any | None = None,
dispatch_seat_entry: Any | None = None,
clarification_terminal: Any | None = None,
) -> Any:
"""Factory: create the appropriate workflow for the given mode."""
if mode == "manager_only":
if manager_answer is None:
raise ValueError("manager_only mode requires manager_answer")
return build_manager_only_workflow(
manager_answer=manager_answer,
manager_dispatch=manager_dispatch,
dispatch_router=dispatch_router,
clarification_terminal=clarification_terminal,
)
if mode == "group_chat":
if coordinator is None:
raise ValueError("group_chat mode requires coordinator")
@@ -135,6 +270,10 @@ def create_workflow(
finalizer=finalizer,
waiting_terminal=waiting_terminal,
seat_agent_ids=seat_agent_ids,
manager_dispatch=manager_dispatch,
dispatch_router=dispatch_router,
manager_answer=manager_answer,
clarification_terminal=clarification_terminal,
)
if planner is None or cross_review is None:
raise ValueError("structured mode requires planner and cross_review")
@@ -145,4 +284,10 @@ def create_workflow(
approval_gate=approval_gate,
finalizer=finalizer,
waiting_terminal=waiting_terminal,
execution_mode=execution_mode,
manager_dispatch=manager_dispatch,
dispatch_router=dispatch_router,
dispatch_seat_entry=dispatch_seat_entry,
manager_answer=manager_answer,
clarification_terminal=clarification_terminal,
)
@@ -30,7 +30,11 @@ from app.maf_roundtable.workflow_executors import (
ApprovalGateExecutor,
CoordinatorExecutor,
CrossReviewExecutor,
DispatchPreparationTerminalExecutor,
DispatchSeatEntryExecutor,
FinalizerExecutor,
ManagerAnswerExecutor,
ManagerDispatchExecutor,
PlannerExecutor,
RoundtableState,
SeatExecutor,
@@ -38,7 +42,7 @@ from app.maf_roundtable.workflow_executors import (
_agent_capabilities_from_snapshot,
generate_final_report,
)
from app.maf_roundtable.workflow_factory import create_workflow
from app.maf_roundtable.workflow_factory import build_manager_dispatch_workflow, create_workflow
logger = logging.getLogger(__name__)
@@ -93,12 +97,26 @@ class WorkflowRunner:
participants = await self._service.store.participants.list_participants(session_id)
thread_map = await self._adapter.ensure_threads(session_id, run_id, participants)
seat_agents = [p["agent_id"] for p in participants if p.get("role") != "manager"]
persisted_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 {}
candidate_set = maf_v2_payload.get("candidate_set")
candidate_set = candidate_set if isinstance(candidate_set, dict) else {}
candidate_seat_agents = list(
candidate_set.get("candidate_seat_agent_ids")
or maf_v2_payload.get("candidate_seat_agent_ids")
or (maf_v2_payload.get("dispatch_plan") or {}).get("candidate_seat_agent_ids")
or persisted_seat_agents
)
if not manager_id:
manager_id = candidate_set.get("manager_agent_id") or maf_v2_payload.get(
"manager_agent_id"
)
state = RoundtableState(
session_id=session_id,
@@ -110,17 +128,29 @@ class WorkflowRunner:
max_rounds=session.get("max_rounds", 8),
write_policy=session.get("write_policy", "confirm_high_risk"),
manager_agent_id=manager_id,
seat_agent_ids=seat_agents,
seat_agent_ids=candidate_seat_agents,
thread_map=thread_map,
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"),
candidate_seat_agent_ids=candidate_seat_agents,
dispatch_contract_enabled=bool(
maf_v2_payload.get("dispatch_contract_enabled")
or candidate_set
or maf_v2_payload.get("dispatch_plan") is not None
),
)
workflow = self._build_workflow(state)
await self._run_workflow(workflow, state)
if state.dispatch_contract_enabled:
await self._run_manager_dispatch(state)
if state.status != "waiting_input":
workflow = self._build_workflow(state)
await self._run_workflow(workflow, state)
else:
workflow = self._build_workflow(state)
await self._run_workflow(workflow, state)
# Persist final state. waiting_approval is NOT a terminal state —
# it must NOT write finished_at. Only completed/failed/cancelled do.
@@ -166,14 +196,106 @@ class WorkflowRunner:
except Exception: # noqa: BLE001
return 600.0, True
async def _run_manager_dispatch(self, state: RoundtableState) -> None:
"""Freeze the V2 manager decision before constructing seat topology."""
if state.is_completed("manager_dispatch"):
return
workflow = build_manager_dispatch_workflow(
manager_dispatch=ManagerDispatchExecutor(self._adapter, state),
terminal=DispatchPreparationTerminalExecutor(state),
)
await self._run_workflow(workflow, state)
def _build_workflow(self, state: RoundtableState) -> Any:
approval_gate = ApprovalGateExecutor(self._adapter, state, self._service)
finalizer = FinalizerExecutor(self._adapter, state)
waiting_terminal = WaitingTerminalExecutor()
# New V2 conversations always start at the same constrained manager
# dispatch node. The manager preparation workflow finishes before this
# method is entered, so topology is selected from the persisted plan,
# never from a route default or a model-supplied agent id.
if state.dispatch_contract_enabled:
manager_answer = ManagerAnswerExecutor(self._adapter, state)
plan = state.dispatch_plan or {}
execution_mode = str(plan.get("execution_mode") or "")
selected_seat_ids = list(state.selected_seat_agent_ids or [])
if state.intent_type == "clarification" or not execution_mode:
raise RuntimeError("V2 manager dispatch did not produce a valid execution plan")
if execution_mode == "manager_only":
return create_workflow(
mode="manager_only",
manager_answer=manager_answer,
seat_executors=[],
approval_gate=approval_gate,
finalizer=finalizer,
waiting_terminal=waiting_terminal,
seat_agent_ids=[],
)
if state.mode == "group_chat":
coordinator = CoordinatorExecutor(self._adapter, state)
return create_workflow(
mode="group_chat",
coordinator=coordinator,
seat_executors=[
SeatExecutor(
self._adapter,
state,
agent_id,
action_coordinator=self._action_coordinator,
)
for agent_id in selected_seat_ids
],
approval_gate=approval_gate,
finalizer=finalizer,
waiting_terminal=waiting_terminal,
seat_agent_ids=selected_seat_ids,
)
state.current_round = max(state.current_round, 1)
cross_review = CrossReviewExecutor(self._adapter, state)
return create_workflow(
mode="structured",
planner=DispatchSeatEntryExecutor(state),
cross_review=cross_review,
seat_executors=[
SeatExecutor(
self._adapter,
state,
agent_id,
action_coordinator=self._action_coordinator,
)
for agent_id in selected_seat_ids
],
approval_gate=approval_gate,
finalizer=finalizer,
waiting_terminal=waiting_terminal,
seat_agent_ids=selected_seat_ids,
execution_mode=execution_mode,
)
seat_executors = [
SeatExecutor(self._adapter, state, agent_id, action_coordinator=self._action_coordinator)
for agent_id in state.seat_agent_ids
]
approval_gate = ApprovalGateExecutor(self._adapter, state, self._service)
finalizer = FinalizerExecutor(self._adapter, state)
waiting_terminal = WaitingTerminalExecutor()
execution_mode = str(
(state.dispatch_plan or {}).get("execution_mode")
or ("manager_only" if state.intent_type == "direct_answer" else "parallel")
)
if execution_mode == "manager_only":
manager_answer = ManagerAnswerExecutor(self._adapter, state)
return create_workflow(
mode="manager_only",
manager_answer=manager_answer,
seat_executors=[],
approval_gate=approval_gate,
finalizer=finalizer,
waiting_terminal=waiting_terminal,
seat_agent_ids=[],
)
if state.mode == "group_chat":
coordinator = CoordinatorExecutor(self._adapter, state)
@@ -198,6 +320,7 @@ class WorkflowRunner:
finalizer=finalizer,
waiting_terminal=waiting_terminal,
seat_agent_ids=state.seat_agent_ids,
execution_mode=execution_mode,
)
async def _persist_checkpoint(self, state: RoundtableState, *, reason: str = "") -> None:
@@ -663,8 +786,14 @@ class WorkflowRunner:
await self._service.store.runs.update_run(run_id, {"status": "running"})
try:
workflow = self._build_workflow(state)
await self._run_workflow(workflow, state)
if state.dispatch_contract_enabled:
await self._run_manager_dispatch(state)
if state.status != "waiting_input":
workflow = self._build_workflow(state)
await self._run_workflow(workflow, state)
else:
workflow = self._build_workflow(state)
await self._run_workflow(workflow, state)
latency = int((time.perf_counter() - t0) * 1000)
final_status = state.status