fix(maf): harden stage-4 quality gate (P0/P1)
P0-1 migration: detect the same-named stage-3 execution_stage CHECK by sqltext (must contain rework + manager_review), SQLite rebuild / PG-MySQL drop+add, PG boolean default TRUE, validate_schema checks constraint content + seat_tasks status CHECK/unique/FKs; tests start from a real stage-3 schema. P0-2: a missing/invalid manager review (timeout/exception/empty/invalid JSON/missing per-seat decision) is never an acceptance - system rework under the cap, contract fallback (reassign/controlled_gap/ask_user) afterwards, source=system events. P0-3: unaccepted deliveries are isolated from the fact ledger, cross-review and final report (deferred merge, delivery_json envelope, accepted_task_results in checkpoint, accepted-only synthesis, no turn_results fallback). P0-4: seat-task init is atomic get-or-create over the full expected set; recovery fills missing tasks without overwriting frozen contracts; quality gate blocks missing required tasks. P1: zero config values honoured; duplicate detection persists SHA-256 conclusion digests in history (survives restarts); findings never satisfy evidence, evidence_refs must resolve to trusted ledger refs (unverified_evidence_ref); conversation SSE projection tests added and manager/finalizer messages are no longer mislabelled as seat.delivery.submitted.
This commit is contained in:
1 parent
a786cdcad0
commit
1aeee86984
24 files changed
+4706
-47
No files matched your search
@@ -430,6 +430,7 @@ class MafConversationService:
|
||||
_ALLOWED_TYPES = frozenset({
|
||||
"agent.message.start", "agent.message.delta", "agent.message.complete",
|
||||
"seat.delivery.submitted", "manager.dispatch", "manager.review.decision",
|
||||
"seat.rework.assigned", "seat.reassigned", "stage.quality_gate",
|
||||
"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",
|
||||
@@ -437,6 +438,11 @@ class MafConversationService:
|
||||
"run.cancelled", "run.completed",
|
||||
})
|
||||
|
||||
# Execution stages whose ``agent.message.completed`` is a genuine seat
|
||||
# delivery. Manager / dispatch / review / cross-review / finalizer /
|
||||
# format-repair messages must NEVER be projected as seat.delivery.submitted.
|
||||
_SEAT_DELIVERY_STAGES = frozenset({"expert", "rework", "legacy", "group_chat"})
|
||||
|
||||
_SAFE_KEYS: dict[str, dict[str, bool]] = {
|
||||
"agent.message.start": {"thread_id": False},
|
||||
"agent.message.delta": {"text": True},
|
||||
@@ -463,10 +469,27 @@ class MafConversationService:
|
||||
"reason": True, "source": True, "clarification_prompt": True,
|
||||
},
|
||||
"clarification.required": {"prompt": True, "reason": True},
|
||||
"manager.review.decision": {"decision": True, "reason": True, "quality": True},
|
||||
"manager.review.decision": {
|
||||
"decision": True, "reason": True, "quality": True,
|
||||
"task_key": True, "attempt": True, "source": True,
|
||||
},
|
||||
"fact.confirmed": {"fact_id": True, "summary": True},
|
||||
"review.completed": {"summary": True, "decision": True},
|
||||
"seat.delivery.submitted": {"content": True, "schema_status": True},
|
||||
"seat.delivery.submitted": {
|
||||
"content": True, "schema_status": True,
|
||||
"task_key": True, "attempt": True,
|
||||
"deterministic_passed": True, "failure_codes": True,
|
||||
},
|
||||
"seat.rework.assigned": {
|
||||
"task_key": True, "rework_count": True, "revision_requirements": True,
|
||||
},
|
||||
"seat.reassigned": {
|
||||
"task_key": True, "from_agent_id": True, "reassign_count": True,
|
||||
},
|
||||
"stage.quality_gate": {
|
||||
"decision": True, "total": True, "accepted": True,
|
||||
"controlled_gap": True, "blocked_required": True,
|
||||
},
|
||||
}
|
||||
|
||||
def _build_projection_items(
|
||||
@@ -501,19 +524,26 @@ class MafConversationService:
|
||||
"source_event_id": source_evt_id,
|
||||
}]
|
||||
|
||||
# Only a genuine seat delivery turn may be projected as
|
||||
# seat.delivery.submitted. Manager / dispatch / manager_review /
|
||||
# cross-review / finalizer / format-repair messages are ordinary
|
||||
# agent messages and must never be mislabelled as seat deliveries
|
||||
# (Stage-4 runs emit their own explicit seat.delivery.submitted event).
|
||||
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,
|
||||
})
|
||||
stage = str(payload.get("execution_stage") or "")
|
||||
if stage in self._SEAT_DELIVERY_STAGES:
|
||||
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
|
||||
|
||||
|
||||
@@ -275,6 +275,7 @@ class DeerFlowAgentAdapter:
|
||||
content=response.content,
|
||||
usage=response.usage,
|
||||
metadata=response.metadata,
|
||||
execution_stage=execution_stage,
|
||||
))
|
||||
return response
|
||||
|
||||
|
||||
@@ -75,12 +75,17 @@ def make_turn_completed(
|
||||
content: str,
|
||||
usage: dict[str, Any] | None = None,
|
||||
metadata: dict[str, Any] | None = None,
|
||||
execution_stage: str | None = None,
|
||||
) -> dict[str, Any]:
|
||||
payload: dict[str, Any] = {"content": content}
|
||||
if usage:
|
||||
payload["usage"] = usage
|
||||
if metadata:
|
||||
payload["metadata"] = metadata
|
||||
# The conversation projection must be able to tell a real seat delivery
|
||||
# apart from manager / review / finalizer messages — carry the stage.
|
||||
if execution_stage:
|
||||
payload["execution_stage"] = execution_stage
|
||||
return _make("agent.message.completed", agent_id, turn_index, payload)
|
||||
|
||||
|
||||
@@ -154,6 +159,99 @@ def make_workflow_checkpointed(agent_id: str | None, turn_index: int, *, checkpo
|
||||
return _make("workflow.checkpointed", agent_id or "", turn_index, {"checkpoint_id": checkpoint_id, "reason": reason})
|
||||
|
||||
|
||||
# ── Stage 4 (R3-Q) quality gate events ──────────────────────────────────
|
||||
|
||||
|
||||
def make_seat_delivery_submitted(
|
||||
agent_id: str,
|
||||
turn_index: int,
|
||||
*,
|
||||
task_key: str,
|
||||
attempt: int,
|
||||
deterministic_passed: bool,
|
||||
failure_codes: list[str] | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""A seat task submitted its delivery and passed/failed deterministic checks."""
|
||||
return _make("seat.delivery.submitted", agent_id, turn_index, {
|
||||
"task_key": task_key,
|
||||
"attempt": attempt,
|
||||
"deterministic_passed": deterministic_passed,
|
||||
"failure_codes": list(failure_codes or []),
|
||||
})
|
||||
|
||||
|
||||
def make_manager_review_decision(
|
||||
agent_id: str,
|
||||
turn_index: int,
|
||||
*,
|
||||
task_key: str,
|
||||
decision: str,
|
||||
reason: str,
|
||||
source: str,
|
||||
attempt: int,
|
||||
) -> dict[str, Any]:
|
||||
"""Server-finalized manager review decision for one seat task."""
|
||||
return _make("manager.review.decision", agent_id, turn_index, {
|
||||
"task_key": task_key,
|
||||
"decision": decision,
|
||||
"reason": _truncate(reason, 500),
|
||||
"source": source,
|
||||
"attempt": attempt,
|
||||
})
|
||||
|
||||
|
||||
def make_seat_rework_assigned(
|
||||
agent_id: str,
|
||||
turn_index: int,
|
||||
*,
|
||||
task_key: str,
|
||||
rework_count: int,
|
||||
requirements: list[str] | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""A seat task is sent back for rework with explicit revision requirements."""
|
||||
return _make("seat.rework.assigned", agent_id, turn_index, {
|
||||
"task_key": task_key,
|
||||
"rework_count": rework_count,
|
||||
"revision_requirements": [str(r) for r in (requirements or [])][:16],
|
||||
})
|
||||
|
||||
|
||||
def make_seat_reassigned(
|
||||
agent_id: str,
|
||||
turn_index: int,
|
||||
*,
|
||||
task_key: str,
|
||||
from_agent_id: str,
|
||||
reassign_count: int,
|
||||
) -> dict[str, Any]:
|
||||
"""A seat task is reassigned to a backup seat (agent_id = new owner)."""
|
||||
return _make("seat.reassigned", agent_id, turn_index, {
|
||||
"task_key": task_key,
|
||||
"from_agent_id": from_agent_id,
|
||||
"reassign_count": reassign_count,
|
||||
})
|
||||
|
||||
|
||||
def make_stage_quality_gate(
|
||||
agent_id: str | None,
|
||||
turn_index: int,
|
||||
*,
|
||||
decision: str,
|
||||
total: int,
|
||||
accepted: int,
|
||||
controlled_gap: int,
|
||||
blocked_required: list[str] | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Stage quality gate outcome: passed / blocked / passed_with_gaps."""
|
||||
return _make("stage.quality_gate", agent_id or "", turn_index, {
|
||||
"decision": decision,
|
||||
"total": total,
|
||||
"accepted": accepted,
|
||||
"controlled_gap": controlled_gap,
|
||||
"blocked_required": list(blocked_required or []),
|
||||
})
|
||||
|
||||
|
||||
# ── internal helpers ──────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,568 @@
|
||||
"""Stage 4 (R3-Q): seat task contracts, deterministic quality checks, manager
|
||||
review schema, and server-owned decision finalization.
|
||||
|
||||
Pure policy module: no I/O and no MAF SDK imports, so the whole acceptance
|
||||
policy is unit-testable with a weak/fake model before any workflow runs.
|
||||
|
||||
The manager model only ever *proposes* review decisions. This module is the
|
||||
final validator and never allows:
|
||||
|
||||
- accepting a delivery that failed the deterministic quality checks (the
|
||||
manager's self-assessment is NOT acceptance evidence);
|
||||
- reworking a seat beyond its frozen ``max_rework_attempts``;
|
||||
- more reassignments than the server-configured cap;
|
||||
- an exhausted task being disguised as accepted — it becomes a
|
||||
``controlled_gap`` carrying its risk, or an explicit ``ask_user`` pause.
|
||||
|
||||
Task status state machine (persisted per seat task)::
|
||||
|
||||
assigned → delivering → submitted → manager_review →
|
||||
accepted
|
||||
| rework (→ delivering, with explicit revision requirements)
|
||||
| reassigned (→ delivering, backup seat takes over)
|
||||
| exhausted (rework/reassign caps reached)
|
||||
→ controlled_gap (risk recorded, carried into the final report)
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
import re
|
||||
from typing import Any, Literal
|
||||
|
||||
from pydantic import BaseModel, ConfigDict, Field
|
||||
|
||||
# ── task status state machine ───────────────────────────────────────────────
|
||||
|
||||
TASK_ASSIGNED = "assigned"
|
||||
TASK_DELIVERING = "delivering"
|
||||
TASK_SUBMITTED = "submitted"
|
||||
TASK_MANAGER_REVIEW = "manager_review"
|
||||
TASK_ACCEPTED = "accepted"
|
||||
TASK_REWORK = "rework"
|
||||
TASK_REASSIGNED = "reassigned"
|
||||
TASK_EXHAUSTED = "exhausted"
|
||||
TASK_CONTROLLED_GAP = "controlled_gap"
|
||||
|
||||
TASK_TERMINAL_STATUSES = frozenset({TASK_ACCEPTED, TASK_CONTROLLED_GAP})
|
||||
TASK_ALL_STATUSES = frozenset({
|
||||
TASK_ASSIGNED,
|
||||
TASK_DELIVERING,
|
||||
TASK_SUBMITTED,
|
||||
TASK_MANAGER_REVIEW,
|
||||
TASK_ACCEPTED,
|
||||
TASK_REWORK,
|
||||
TASK_REASSIGNED,
|
||||
TASK_EXHAUSTED,
|
||||
TASK_CONTROLLED_GAP,
|
||||
})
|
||||
|
||||
MafReviewDecision = Literal[
|
||||
"accept", "return_for_rework", "reassign", "ask_user", "controlled_gap"
|
||||
]
|
||||
MafFallbackPolicy = Literal["reassign_then_gap", "controlled_gap", "ask_user"]
|
||||
|
||||
# Final (server-owned) outcomes of the decision finalizer.
|
||||
OUTCOME_ACCEPTED = "accepted"
|
||||
OUTCOME_REWORK = "rework"
|
||||
OUTCOME_REASSIGNED = "reassigned"
|
||||
OUTCOME_CONTROLLED_GAP = "controlled_gap"
|
||||
OUTCOME_ASK_USER = "ask_user"
|
||||
|
||||
|
||||
class InvalidTaskContractError(ValueError):
|
||||
"""Raised when a task contract cannot be frozen from a dispatch plan."""
|
||||
|
||||
|
||||
# ── task contract ───────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
class MafTaskContract(BaseModel):
|
||||
"""Frozen acceptance contract for one seat task.
|
||||
|
||||
Created server-side from the validated dispatch assignment before the seat
|
||||
starts working. The manager model can never widen these terms afterwards.
|
||||
"""
|
||||
|
||||
model_config = ConfigDict(extra="forbid")
|
||||
|
||||
objective: str = Field(min_length=1, max_length=2000)
|
||||
expected_deliverable: str = Field(min_length=1, max_length=2000)
|
||||
acceptance_criteria: list[str] = Field(default_factory=list, max_length=32)
|
||||
required: bool = True
|
||||
max_rework_attempts: int = Field(default=2, ge=0, le=8)
|
||||
fallback_policy: MafFallbackPolicy = "reassign_then_gap"
|
||||
|
||||
|
||||
DEFAULT_EXPECTED_DELIVERABLE = (
|
||||
"结构化 JSON 交付:结论(summary)、依据/证据(findings/evidence_refs)、"
|
||||
"未解决项(open_questions)、自检(self_check)"
|
||||
)
|
||||
|
||||
|
||||
def build_task_contract(
|
||||
*,
|
||||
task_goal: str,
|
||||
delivery_requirements: list[str] | None = None,
|
||||
required: bool = True,
|
||||
max_rework_attempts: int = 2,
|
||||
fallback_policy: MafFallbackPolicy = "reassign_then_gap",
|
||||
) -> MafTaskContract:
|
||||
"""Freeze a task contract from one validated dispatch assignment."""
|
||||
objective = str(task_goal or "").strip()
|
||||
if not objective:
|
||||
raise InvalidTaskContractError("task contract objective must be non-empty")
|
||||
criteria = [
|
||||
str(item).strip()
|
||||
for item in (delivery_requirements or [])
|
||||
if str(item or "").strip()
|
||||
]
|
||||
return MafTaskContract(
|
||||
objective=objective,
|
||||
expected_deliverable=DEFAULT_EXPECTED_DELIVERABLE,
|
||||
acceptance_criteria=criteria,
|
||||
required=required,
|
||||
max_rework_attempts=max_rework_attempts,
|
||||
fallback_policy=fallback_policy,
|
||||
)
|
||||
|
||||
|
||||
# ── seat delivery ───────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
class MafSeatDelivery(BaseModel):
|
||||
"""Structured delivery extracted from one seat turn output."""
|
||||
|
||||
model_config = ConfigDict(extra="forbid")
|
||||
|
||||
conclusion: str = ""
|
||||
evidence: list[str] = Field(default_factory=list)
|
||||
# P1: only ``evidence_refs`` can satisfy the evidence requirement. Seat
|
||||
# ``findings`` are candidate claims — they are kept in ``evidence`` for
|
||||
# review display but never count as verified evidence.
|
||||
evidence_refs: list[str] = Field(default_factory=list)
|
||||
unresolved_items: list[str] = Field(default_factory=list)
|
||||
self_check: str = ""
|
||||
|
||||
|
||||
def _flat_text(item: Any, *keys: str) -> str:
|
||||
if isinstance(item, dict):
|
||||
for key in keys:
|
||||
value = item.get(key)
|
||||
if isinstance(value, str) and value.strip():
|
||||
return value.strip()
|
||||
return ""
|
||||
return str(item or "").strip()
|
||||
|
||||
|
||||
def delivery_from_seat_output(
|
||||
*, structured_output: dict[str, Any] | None, raw_content: str
|
||||
) -> MafSeatDelivery:
|
||||
"""Map a validated SeatTurnOutput dict onto the delivery contract.
|
||||
|
||||
``structured_output`` is ``None`` when the seat output failed the schema —
|
||||
the resulting delivery is (almost) empty so the deterministic checks flag
|
||||
it instead of trusting the raw text.
|
||||
"""
|
||||
out = structured_output if isinstance(structured_output, dict) else {}
|
||||
conclusion = str(out.get("summary") or "").strip()
|
||||
|
||||
evidence: list[str] = []
|
||||
for item in out.get("findings") or []:
|
||||
text = _flat_text(item, "text")
|
||||
if text:
|
||||
evidence.append(text)
|
||||
evidence_refs: list[str] = []
|
||||
for ref in out.get("evidence_refs") or []:
|
||||
text = _flat_text(ref, "ref", "text")
|
||||
if text:
|
||||
evidence_refs.append(text)
|
||||
evidence.append(text)
|
||||
|
||||
unresolved = [
|
||||
str(q).strip() for q in (out.get("open_questions") or []) if str(q or "").strip()
|
||||
]
|
||||
self_check = str(out.get("self_check") or "").strip()
|
||||
return MafSeatDelivery(
|
||||
conclusion=conclusion,
|
||||
evidence=evidence,
|
||||
evidence_refs=evidence_refs,
|
||||
unresolved_items=unresolved,
|
||||
self_check=self_check,
|
||||
)
|
||||
|
||||
|
||||
# ── deterministic quality checks ────────────────────────────────────────────
|
||||
|
||||
FAIL_EMPTY_CONTENT = "empty_content"
|
||||
FAIL_SCHEMA_INVALID = "schema_invalid"
|
||||
FAIL_MISSING_CONCLUSION = "missing_conclusion"
|
||||
FAIL_BELOW_MIN_LENGTH = "below_min_length"
|
||||
FAIL_MISSING_EVIDENCE = "missing_evidence"
|
||||
FAIL_DUPLICATE_CONTENT = "duplicate_content"
|
||||
FAIL_UNVERIFIED_EVIDENCE_REF = "unverified_evidence_ref"
|
||||
|
||||
_REPAIR_HINTS: dict[str, str] = {
|
||||
FAIL_EMPTY_CONTENT: "交付内容为空,请给出完整的分析与结论",
|
||||
FAIL_SCHEMA_INVALID: "输出不是合法的结构化 JSON,请按 SeatTurnOutput 字段重新输出",
|
||||
FAIL_MISSING_CONCLUSION: "缺少明确结论(summary),请补充",
|
||||
FAIL_BELOW_MIN_LENGTH: "结论过短,请展开具体分析、依据与建议",
|
||||
FAIL_MISSING_EVIDENCE: (
|
||||
"缺少可信证据(evidence_refs)。findings 只是候选主张,不能充当证据;"
|
||||
"请引用事实账本/成功工具结果中真实存在的证据引用"
|
||||
),
|
||||
FAIL_DUPLICATE_CONTENT: "内容与上一次交付重复,请针对退回意见提供新的分析",
|
||||
FAIL_UNVERIFIED_EVIDENCE_REF: (
|
||||
"引用了事实账本中不存在的证据(自造引用不可接受);"
|
||||
"请只引用已记录的可信证据或成功工具结果"
|
||||
),
|
||||
}
|
||||
|
||||
|
||||
def conclusion_digest(conclusion: str) -> str:
|
||||
"""SHA-256 digest of the normalized conclusion.
|
||||
|
||||
Duplicate detection persists these digests (never the conclusion bodies)
|
||||
in the task history, so the check survives restarts without storing the
|
||||
duplicated text again.
|
||||
"""
|
||||
normalized = " ".join(str(conclusion or "").split())
|
||||
return hashlib.sha256(normalized.encode("utf-8")).hexdigest()
|
||||
|
||||
|
||||
def check_delivery_deterministic(
|
||||
*,
|
||||
delivery: MafSeatDelivery,
|
||||
raw_content: str,
|
||||
schema_status: str | None,
|
||||
min_length: int = 40,
|
||||
min_evidence: int = 1,
|
||||
prior_conclusion_digests: set[str] | list[str] | None = None,
|
||||
verified_evidence_refs: set[str] | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Deterministic acceptance gate run BEFORE the manager review.
|
||||
|
||||
A delivery that fails any check can never be accepted, regardless of what
|
||||
the manager model claims. Returns ``{"passed": bool, "failure_codes": [...]}``.
|
||||
|
||||
Evidence rules (P1):
|
||||
- seat ``findings`` are candidate claims only — they can NEVER satisfy the
|
||||
evidence requirement; only ``evidence_refs`` count;
|
||||
- when ``verified_evidence_refs`` is supplied (the trusted refs the fact
|
||||
ledger actually backs: recorded evidence + successful tool results),
|
||||
every cited ref must resolve — an invented ref fails with
|
||||
``unverified_evidence_ref``, and only verified refs count toward
|
||||
``min_evidence``;
|
||||
- duplicate detection compares SHA-256 digests of normalized conclusions,
|
||||
so it survives restarts via the persisted task history.
|
||||
"""
|
||||
codes: list[str] = []
|
||||
text = str(raw_content or "").strip()
|
||||
if not text:
|
||||
codes.append(FAIL_EMPTY_CONTENT)
|
||||
if schema_status == "schema_invalid":
|
||||
codes.append(FAIL_SCHEMA_INVALID)
|
||||
if not delivery.conclusion:
|
||||
codes.append(FAIL_MISSING_CONCLUSION)
|
||||
elif len(delivery.conclusion) < max(0, int(min_length)):
|
||||
codes.append(FAIL_BELOW_MIN_LENGTH)
|
||||
|
||||
cited_refs = [str(r) for r in (delivery.evidence_refs or []) if str(r or "").strip()]
|
||||
if verified_evidence_refs is not None:
|
||||
trusted = {str(r) for r in verified_evidence_refs}
|
||||
verified = [r for r in cited_refs if r in trusted]
|
||||
if any(r not in trusted for r in cited_refs):
|
||||
codes.append(FAIL_UNVERIFIED_EVIDENCE_REF)
|
||||
else:
|
||||
verified = cited_refs
|
||||
if len(verified) < max(0, int(min_evidence)):
|
||||
codes.append(FAIL_MISSING_EVIDENCE)
|
||||
|
||||
if (
|
||||
delivery.conclusion
|
||||
and prior_conclusion_digests
|
||||
and conclusion_digest(delivery.conclusion) in set(prior_conclusion_digests)
|
||||
):
|
||||
codes.append(FAIL_DUPLICATE_CONTENT)
|
||||
return {"passed": not codes, "failure_codes": codes}
|
||||
|
||||
|
||||
def repair_requirements_for_codes(failure_codes: list[str]) -> list[str]:
|
||||
"""Deterministic, targeted revision requirements for failed checks."""
|
||||
hints = [_REPAIR_HINTS[code] for code in failure_codes if code in _REPAIR_HINTS]
|
||||
return hints or ["请按照任务合同补充缺失内容后重新交付"]
|
||||
|
||||
|
||||
# ── manager review schema ───────────────────────────────────────────────────
|
||||
|
||||
|
||||
class MafManagerReviewItem(BaseModel):
|
||||
"""One per-task review decision proposed by the manager model."""
|
||||
|
||||
model_config = ConfigDict(extra="forbid")
|
||||
|
||||
agent_id: str = Field(min_length=1, max_length=64)
|
||||
decision: MafReviewDecision
|
||||
reason: str = Field(min_length=1, max_length=1000)
|
||||
revision_requirements: list[str] = Field(default_factory=list, max_length=16)
|
||||
|
||||
|
||||
class MafManagerReviewOutput(BaseModel):
|
||||
"""Strict model-facing manager review schema (one entry per reviewed seat)."""
|
||||
|
||||
model_config = ConfigDict(extra="forbid")
|
||||
|
||||
decisions: list[MafManagerReviewItem] = Field(default_factory=list, max_length=64)
|
||||
|
||||
|
||||
_JSON_FENCE_RE = re.compile(r"```(?:json)?\s*([\s\S]*?)```", re.IGNORECASE)
|
||||
|
||||
|
||||
def _extract_json_object(text: str) -> str | None:
|
||||
raw = (text or "").strip()
|
||||
if not raw:
|
||||
return None
|
||||
m = _JSON_FENCE_RE.search(raw)
|
||||
if m:
|
||||
raw = m.group(1).strip()
|
||||
if raw.startswith("{") and raw.endswith("}"):
|
||||
return raw
|
||||
start = raw.find("{")
|
||||
end = raw.rfind("}")
|
||||
if start >= 0 and end > start:
|
||||
return raw[start : end + 1]
|
||||
return None
|
||||
|
||||
|
||||
def parse_manager_review(text: str) -> tuple[MafManagerReviewOutput | None, list[str]]:
|
||||
"""Parse the manager's review JSON. Returns ``(model, readable_errors)``."""
|
||||
blob = _extract_json_object(text)
|
||||
if blob is None:
|
||||
return None, ["review output is not a JSON object; emit MafManagerReviewOutput JSON"]
|
||||
try:
|
||||
data = json.loads(blob)
|
||||
except json.JSONDecodeError as exc:
|
||||
return None, [f"invalid JSON: {exc.msg}"]
|
||||
if not isinstance(data, dict):
|
||||
return None, ["JSON root must be an object"]
|
||||
try:
|
||||
return MafManagerReviewOutput.model_validate(data), []
|
||||
except Exception as exc: # pydantic ValidationError
|
||||
errors = []
|
||||
detail = getattr(exc, "errors", None)
|
||||
if callable(detail):
|
||||
for err in detail():
|
||||
loc = ".".join(str(p) for p in err.get("loc", ()))
|
||||
errors.append(f"{loc}: {err.get('msg', 'invalid')}")
|
||||
return None, errors or ["manager review schema validation failed"]
|
||||
|
||||
|
||||
def build_manager_review_prompt(
|
||||
*,
|
||||
task_text: str,
|
||||
review_items: list[dict[str, Any]],
|
||||
) -> str:
|
||||
"""Build the strict manager review prompt.
|
||||
|
||||
Each review item: ``{agent_id, attempt, contract, delivery, check}``. The
|
||||
manager may only propose decisions; the server finalizes them.
|
||||
"""
|
||||
contract_shape = {
|
||||
"decisions": [
|
||||
{
|
||||
"agent_id": "被审查席位 id",
|
||||
"decision": "accept|return_for_rework|reassign|ask_user|controlled_gap",
|
||||
"reason": "必填:针对性理由",
|
||||
"revision_requirements": ["打回时必填:缺什么、怎样补、哪些原结论不可用"],
|
||||
}
|
||||
]
|
||||
}
|
||||
lines = [
|
||||
"你是 MAF 总控,负责验收下列席位交付。只输出一个 JSON 对象(不要 Markdown),"
|
||||
"对每个席位给出一条 decision。验收依据是任务合同与确定性检查结果;"
|
||||
"确定性检查未通过的交付不得 accept。打回时必须写明缺什么、怎样补。"
|
||||
"不要输出任何席位/工具/线程 id 之外的字段。",
|
||||
f"原始任务:\n{task_text[:2000]}",
|
||||
"待审查交付:",
|
||||
json.dumps(review_items, ensure_ascii=False)[:12000],
|
||||
f"必须返回的 JSON 结构:{json.dumps(contract_shape, ensure_ascii=False)}",
|
||||
]
|
||||
return "\n\n".join(lines)
|
||||
|
||||
|
||||
# ── server-owned decision finalization ──────────────────────────────────────
|
||||
|
||||
|
||||
def finalize_review_decision(
|
||||
*,
|
||||
contract: MafTaskContract,
|
||||
check_result: dict[str, Any],
|
||||
review_item: MafManagerReviewItem | None,
|
||||
rework_count: int,
|
||||
reassign_count: int,
|
||||
has_backup_seat: bool,
|
||||
max_reassignments: int = 1,
|
||||
) -> dict[str, Any]:
|
||||
"""Finalize one task's review decision server-side.
|
||||
|
||||
Returns ``{"decision", "reason", "revision_requirements", "source"}`` where
|
||||
``decision`` is one of the final outcomes: ``accepted`` / ``rework`` /
|
||||
``reassigned`` / ``controlled_gap`` / ``ask_user``.
|
||||
|
||||
Rules enforced here (never by the model alone):
|
||||
|
||||
1. A deterministic check failure can NEVER end in ``accepted``.
|
||||
2. Rework is only granted while ``rework_count < contract.max_rework_attempts``.
|
||||
3. Reassignment is only granted while a backup seat exists and
|
||||
``reassign_count < max_reassignments``.
|
||||
4. Once every cap is exhausted the task ends as ``controlled_gap`` (or an
|
||||
explicit ``ask_user`` pause when the contract's fallback policy says
|
||||
so) — never as a disguised success.
|
||||
5. A missing/invalid manager review (timeout, exception, empty output,
|
||||
invalid JSON, or a missing per-seat decision) is NEVER an acceptance,
|
||||
even when the delivery passed every deterministic check: while the
|
||||
rework cap allows it, the server forces a system rework; once the caps
|
||||
are exhausted the contract's fallback policy decides (reassign /
|
||||
``controlled_gap`` / ``ask_user``).
|
||||
"""
|
||||
codes = list(check_result.get("failure_codes") or [])
|
||||
deterministic_passed = bool(check_result.get("passed"))
|
||||
can_rework = rework_count < contract.max_rework_attempts
|
||||
can_reassign = has_backup_seat and reassign_count < max_reassignments
|
||||
|
||||
def _outcome(decision: str, reason: str, source: str, requirements: list[str] | None = None) -> dict[str, Any]:
|
||||
return {
|
||||
"decision": decision,
|
||||
"reason": str(reason or "")[:1000],
|
||||
"revision_requirements": [str(r) for r in (requirements or [])][:16],
|
||||
"source": source,
|
||||
}
|
||||
|
||||
def _exhaustion_outcome(reason: str, source: str) -> dict[str, Any]:
|
||||
if contract.fallback_policy == "ask_user":
|
||||
return _outcome(OUTCOME_ASK_USER, reason, source)
|
||||
if contract.fallback_policy == "reassign_then_gap" and can_reassign:
|
||||
return _outcome(OUTCOME_REASSIGNED, reason, source)
|
||||
return _outcome(OUTCOME_CONTROLLED_GAP, reason, source)
|
||||
|
||||
# 1) Deterministic failure — never accepted.
|
||||
if not deterministic_passed:
|
||||
base_reason = f"deterministic_quality_check_failed: {', '.join(codes)}"
|
||||
if can_rework:
|
||||
requirements = (
|
||||
list(review_item.revision_requirements)
|
||||
if review_item is not None
|
||||
and review_item.decision == "return_for_rework"
|
||||
and review_item.revision_requirements
|
||||
else repair_requirements_for_codes(codes)
|
||||
)
|
||||
return _outcome(OUTCOME_REWORK, base_reason, "deterministic", requirements)
|
||||
return _exhaustion_outcome(base_reason, "deterministic")
|
||||
|
||||
# 2) Deterministic checks passed — but acceptance still requires a valid
|
||||
# manager review. A missing/invalid review (timeout, exception, empty
|
||||
# output, invalid JSON, or a missing per-seat decision) is NEVER an
|
||||
# acceptance: passing length/format checks alone does not make a delivery
|
||||
# verified. The server forces a system rework while the cap allows it, and
|
||||
# falls back to the contract's exhaustion policy afterwards.
|
||||
if review_item is None:
|
||||
reason = "manager_review_missing_or_invalid"
|
||||
if can_rework:
|
||||
return _outcome(
|
||||
OUTCOME_REWORK,
|
||||
reason,
|
||||
"system",
|
||||
["总控未获得有效验收结论;请重新提交完整、可核验的交付。"],
|
||||
)
|
||||
return _exhaustion_outcome(reason, "system")
|
||||
|
||||
decision = review_item.decision
|
||||
if decision == "accept":
|
||||
return _outcome(OUTCOME_ACCEPTED, review_item.reason, "manager")
|
||||
if decision == "return_for_rework":
|
||||
if can_rework:
|
||||
requirements = list(review_item.revision_requirements) or repair_requirements_for_codes(codes)
|
||||
return _outcome(OUTCOME_REWORK, review_item.reason, "manager", requirements)
|
||||
return _exhaustion_outcome(
|
||||
f"rework_cap_reached: {review_item.reason}", "manager"
|
||||
)
|
||||
if decision == "reassign":
|
||||
if can_reassign:
|
||||
return _outcome(OUTCOME_REASSIGNED, review_item.reason, "manager")
|
||||
return _exhaustion_outcome(
|
||||
f"reassign_unavailable: {review_item.reason}", "manager"
|
||||
)
|
||||
if decision == "ask_user":
|
||||
return _outcome(OUTCOME_ASK_USER, review_item.reason, "manager")
|
||||
# decision == "controlled_gap"
|
||||
return _outcome(OUTCOME_CONTROLLED_GAP, review_item.reason, "manager")
|
||||
|
||||
|
||||
def make_controlled_gap(
|
||||
*,
|
||||
task_key: str,
|
||||
agent_id: str,
|
||||
objective: str,
|
||||
reason: str,
|
||||
failure_codes: list[str] | None = None,
|
||||
attempts: int = 0,
|
||||
) -> dict[str, Any]:
|
||||
"""Build the persisted, traceable controlled-gap record.
|
||||
|
||||
A controlled gap is NEVER a verified fact: the final report must carry it
|
||||
in its risk / pending-information section.
|
||||
"""
|
||||
return {
|
||||
"task_key": task_key,
|
||||
"agent_id": agent_id,
|
||||
"objective": str(objective or "")[:2000],
|
||||
"reason": str(reason or "")[:1000],
|
||||
"failure_codes": list(failure_codes or []),
|
||||
"attempts": int(attempts),
|
||||
"risk": "该问题未获得合格席位交付,不得作为已验证事实写入最终结论",
|
||||
}
|
||||
|
||||
|
||||
__all__ = [
|
||||
"DEFAULT_EXPECTED_DELIVERABLE",
|
||||
"FAIL_BELOW_MIN_LENGTH",
|
||||
"FAIL_DUPLICATE_CONTENT",
|
||||
"FAIL_EMPTY_CONTENT",
|
||||
"FAIL_MISSING_CONCLUSION",
|
||||
"FAIL_MISSING_EVIDENCE",
|
||||
"FAIL_SCHEMA_INVALID",
|
||||
"FAIL_UNVERIFIED_EVIDENCE_REF",
|
||||
"InvalidTaskContractError",
|
||||
"MafFallbackPolicy",
|
||||
"MafManagerReviewItem",
|
||||
"MafManagerReviewOutput",
|
||||
"MafReviewDecision",
|
||||
"MafSeatDelivery",
|
||||
"MafTaskContract",
|
||||
"OUTCOME_ACCEPTED",
|
||||
"OUTCOME_ASK_USER",
|
||||
"OUTCOME_CONTROLLED_GAP",
|
||||
"OUTCOME_REASSIGNED",
|
||||
"OUTCOME_REWORK",
|
||||
"TASK_ACCEPTED",
|
||||
"TASK_ALL_STATUSES",
|
||||
"TASK_ASSIGNED",
|
||||
"TASK_CONTROLLED_GAP",
|
||||
"TASK_DELIVERING",
|
||||
"TASK_EXHAUSTED",
|
||||
"TASK_MANAGER_REVIEW",
|
||||
"TASK_REASSIGNED",
|
||||
"TASK_REWORK",
|
||||
"TASK_SUBMITTED",
|
||||
"TASK_TERMINAL_STATUSES",
|
||||
"build_manager_review_prompt",
|
||||
"build_task_contract",
|
||||
"check_delivery_deterministic",
|
||||
"conclusion_digest",
|
||||
"delivery_from_seat_output",
|
||||
"finalize_review_decision",
|
||||
"make_controlled_gap",
|
||||
"parse_manager_review",
|
||||
"repair_requirements_for_codes",
|
||||
]
|
||||
@@ -24,6 +24,9 @@ class SeatTurnOutput(BaseModel):
|
||||
executed_actions: list[str | dict[str, Any]] = Field(default_factory=list)
|
||||
open_questions: list[str] = Field(default_factory=list)
|
||||
conflicts: list[str] = Field(default_factory=list)
|
||||
# Stage 4 (R3-Q): optional self-check against the task contract. The
|
||||
# manager review treats this as advisory — it is never acceptance evidence.
|
||||
self_check: str | None = Field(default=None, max_length=2000)
|
||||
|
||||
|
||||
class ConfirmedCandidate(BaseModel):
|
||||
@@ -134,7 +137,8 @@ def seat_output_instruction() -> str:
|
||||
"""Stage instruction fragment telling the model to emit SeatTurnOutput JSON."""
|
||||
return (
|
||||
"请以 JSON 对象回复,字段:summary(string,必填)、findings(string[])、"
|
||||
"evidence_refs、proposed_actions、executed_actions、open_questions、conflicts。"
|
||||
"evidence_refs、proposed_actions、executed_actions、open_questions、conflicts、"
|
||||
"self_check(string,可选:对照任务合同自检:已覆盖哪些验收标准、哪些仍缺失)。"
|
||||
"proposed_actions 只表示建议;不要把未真正由系统执行的外部写入标为已执行。"
|
||||
)
|
||||
|
||||
|
||||
@@ -32,14 +32,45 @@ from app.maf_roundtable.dispatch_contracts import (
|
||||
MafDispatchCatalog,
|
||||
MafDispatchPlan,
|
||||
)
|
||||
from app.maf_roundtable.event_normalizer import (
|
||||
make_manager_review_decision,
|
||||
make_seat_delivery_submitted,
|
||||
make_seat_reassigned,
|
||||
make_seat_rework_assigned,
|
||||
make_stage_quality_gate,
|
||||
)
|
||||
from app.maf_roundtable.fact_ledger import (
|
||||
confirm_candidates,
|
||||
empty_ledger,
|
||||
known_evidence_refs,
|
||||
merge_seat_output,
|
||||
normalize_ledger,
|
||||
record_action_transition,
|
||||
record_tool_result,
|
||||
)
|
||||
from app.maf_roundtable.quality_contracts import (
|
||||
OUTCOME_ACCEPTED,
|
||||
OUTCOME_ASK_USER,
|
||||
OUTCOME_CONTROLLED_GAP,
|
||||
OUTCOME_REASSIGNED,
|
||||
OUTCOME_REWORK,
|
||||
TASK_ACCEPTED,
|
||||
TASK_CONTROLLED_GAP,
|
||||
TASK_EXHAUSTED,
|
||||
TASK_REASSIGNED,
|
||||
TASK_REWORK,
|
||||
TASK_SUBMITTED,
|
||||
TASK_TERMINAL_STATUSES,
|
||||
MafTaskContract,
|
||||
build_manager_review_prompt,
|
||||
build_task_contract,
|
||||
check_delivery_deterministic,
|
||||
conclusion_digest,
|
||||
delivery_from_seat_output,
|
||||
finalize_review_decision,
|
||||
make_controlled_gap,
|
||||
parse_manager_review,
|
||||
)
|
||||
from app.maf_roundtable.seat_output import (
|
||||
build_repair_prompt,
|
||||
parse_cross_review_output,
|
||||
@@ -85,6 +116,7 @@ class RoundtableState:
|
||||
dispatch_plan: dict[str, Any] | None = None,
|
||||
candidate_seat_agent_ids: list[str] | None = None,
|
||||
dispatch_contract_enabled: bool | None = None,
|
||||
quality_gate_enabled: bool | None = None,
|
||||
) -> None:
|
||||
self.session_id = session_id
|
||||
self.run_id = run_id
|
||||
@@ -110,6 +142,14 @@ class RoundtableState:
|
||||
if dispatch_contract_enabled is None
|
||||
else bool(dispatch_contract_enabled)
|
||||
)
|
||||
# Stage 4 (R3-Q): quality gate for V2 structured dispatch. Defaults to
|
||||
# the dispatch-contract value when not explicitly resolved, so
|
||||
# checkpoints written before Stage 4 keep the new behavior.
|
||||
self.quality_gate_enabled = (
|
||||
bool(self.dispatch_contract_enabled)
|
||||
if quality_gate_enabled is None
|
||||
else bool(quality_gate_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")
|
||||
@@ -132,6 +172,19 @@ class RoundtableState:
|
||||
self.stage: str = "planning"
|
||||
self.partial_failure: bool = False
|
||||
self.cross_review_result: dict[str, Any] | None = None
|
||||
# Stage 4 (R3-Q): per-task quality state machine summary.
|
||||
# task_key → {status, agent_id, original_agent_id, attempt_count,
|
||||
# rework_count, reassign_count, required}
|
||||
self.seat_task_statuses: dict[str, Any] = {}
|
||||
# Controlled-gap records to be carried into the final report's risk
|
||||
# section. Each entry is a make_controlled_gap(...) dict.
|
||||
self.controlled_gaps: list[dict[str, Any]] = []
|
||||
# Stage 4 (R3-Q): the ONLY seat outputs that cross-review and the
|
||||
# final synthesis may consume when the quality gate is enabled. An
|
||||
# entry is appended exactly when a task's final decision is
|
||||
# ``accepted`` — reworked / reassigned / gap deliveries never land
|
||||
# here, so unaccepted content cannot leak into the final report.
|
||||
self.accepted_task_results: list[dict[str, Any]] = []
|
||||
|
||||
def mark_completed(self, node_id: str) -> None:
|
||||
if node_id not in self.completed_nodes:
|
||||
@@ -159,6 +212,7 @@ class RoundtableState:
|
||||
"intent_type": self.intent_type,
|
||||
"dispatch_plan": self.dispatch_plan,
|
||||
"dispatch_contract_enabled": self.dispatch_contract_enabled,
|
||||
"quality_gate_enabled": self.quality_gate_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,
|
||||
@@ -173,6 +227,9 @@ class RoundtableState:
|
||||
"stage": self.stage,
|
||||
"partial_failure": self.partial_failure,
|
||||
"cross_review_result": self.cross_review_result,
|
||||
"seat_task_statuses": dict(self.seat_task_statuses),
|
||||
"controlled_gaps": list(self.controlled_gaps),
|
||||
"accepted_task_results": list(self.accepted_task_results),
|
||||
}
|
||||
|
||||
@classmethod
|
||||
@@ -196,6 +253,7 @@ class RoundtableState:
|
||||
dispatch_plan=d.get("dispatch_plan"),
|
||||
candidate_seat_agent_ids=d.get("candidate_seat_agent_ids"),
|
||||
dispatch_contract_enabled=d.get("dispatch_contract_enabled"),
|
||||
quality_gate_enabled=d.get("quality_gate_enabled"),
|
||||
)
|
||||
state.current_round = d.get("current_round", 0)
|
||||
state.turn_results = d.get("turn_results", [])
|
||||
@@ -212,6 +270,9 @@ 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.seat_task_statuses = dict(d.get("seat_task_statuses") or {})
|
||||
state.controlled_gaps = list(d.get("controlled_gaps") or [])
|
||||
state.accepted_task_results = list(d.get("accepted_task_results") or [])
|
||||
state.candidate_seat_agent_ids = list(
|
||||
d.get("candidate_seat_agent_ids") or state.candidate_seat_agent_ids
|
||||
)
|
||||
@@ -863,12 +924,24 @@ class SeatExecutor(Executor):
|
||||
agent_id: str,
|
||||
*,
|
||||
action_coordinator: ActionCoordinator | None = None,
|
||||
execution_stage: str | None = None,
|
||||
defer_fact_ledger_merge: bool = False,
|
||||
) -> None:
|
||||
super().__init__(id=f"seat_{agent_id}")
|
||||
self._adapter = adapter
|
||||
self._state = state
|
||||
self._agent_id = agent_id
|
||||
self._action_coordinator = action_coordinator
|
||||
# Stage 4 (R3-Q): optional override for the execution_stage passed to
|
||||
# run_seat_turn. When None, falls back to the mode-based default
|
||||
# ("expert" for structured, "group_chat" for group_chat).
|
||||
self._execution_stage = execution_stage
|
||||
# Stage 4 (R3-Q): when True the structured output is validated, tool
|
||||
# results are audited and events are recorded as usual, but the output
|
||||
# is NOT merged into the fact ledger. The quality loop merges it only
|
||||
# if the manager's final decision accepts the delivery — reworked,
|
||||
# reassigned or gapped content must never become candidate facts.
|
||||
self._defer_fact_ledger_merge = defer_fact_ledger_merge
|
||||
|
||||
@handler(input=Any, output=dict)
|
||||
async def handle(self, message: Any, ctx: WorkflowContext) -> None:
|
||||
@@ -918,7 +991,7 @@ class SeatExecutor(Executor):
|
||||
run_id=self._state.run_id,
|
||||
agent_id=self._agent_id,
|
||||
turn_index=self._state.current_round,
|
||||
execution_stage="group_chat" if self._state.mode == "group_chat" else "expert",
|
||||
execution_stage=self._execution_stage or ("group_chat" if self._state.mode == "group_chat" else "expert"),
|
||||
message=self._state.task_text,
|
||||
thread_id=thread_id,
|
||||
model_name=caps.get("model_name") or self._state.model_name,
|
||||
@@ -956,7 +1029,7 @@ class SeatExecutor(Executor):
|
||||
schema_result = await self._validate_output(raw_content)
|
||||
content = schema_result.get("raw_content") or raw_content
|
||||
|
||||
if schema_result.get("output"):
|
||||
if schema_result.get("output") and not self._defer_fact_ledger_merge:
|
||||
merge_seat_output(self._state.fact_ledger, schema_result["output"], agent_id=self._agent_id)
|
||||
|
||||
await self._capture_pending_approvals(response.tool_calls or [])
|
||||
@@ -981,7 +1054,7 @@ class SeatExecutor(Executor):
|
||||
# Phase-3 P0-1: record which execution stage produced this turn so
|
||||
# recovery can distinguish an expert's original output from its
|
||||
# format_repair / cross_review / finalizer re-runs.
|
||||
"execution_stage": "group_chat" if self._state.mode == "group_chat" else "expert",
|
||||
"execution_stage": self._execution_stage or ("group_chat" if self._state.mode == "group_chat" else "expert"),
|
||||
"content": content,
|
||||
"tool_calls": response.tool_calls,
|
||||
"error": response.error,
|
||||
@@ -1160,8 +1233,21 @@ class CrossReviewExecutor(Executor):
|
||||
|
||||
self._state.stage = "review"
|
||||
|
||||
# Barrier: ensure every seat has an outcome (fan-in should guarantee this).
|
||||
review_seats = self._state.selected_seat_agent_ids or self._state.seat_agent_ids
|
||||
# P0-3: with the Stage-4 quality gate the cross-review may only see
|
||||
# ACCEPTED seat results — reworked/reassigned/gapped deliveries never
|
||||
# enter the review prompt (their content is already absent from the
|
||||
# fact ledger because the merge was deferred until acceptance).
|
||||
if self._state.quality_gate_enabled:
|
||||
accepted_results = list(self._state.accepted_task_results)
|
||||
review_seats = sorted({
|
||||
str(r.get("agent_id") or "")
|
||||
for r in accepted_results
|
||||
if r.get("agent_id")
|
||||
})
|
||||
else:
|
||||
accepted_results = None
|
||||
# Barrier: ensure every seat has an outcome (fan-in should guarantee this).
|
||||
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"}
|
||||
@@ -1193,9 +1279,16 @@ class CrossReviewExecutor(Executor):
|
||||
thread_id = self._state.thread_map.get(manager_id or "", "")
|
||||
if manager_id and thread_id:
|
||||
try:
|
||||
if accepted_results is not None:
|
||||
seat_results_for_review: list[dict[str, Any]] = accepted_results
|
||||
else:
|
||||
seat_results_for_review = [
|
||||
r for r in self._state.turn_results
|
||||
if r.get("agent_id") in review_seats
|
||||
]
|
||||
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 review_seats],
|
||||
seat_results=seat_results_for_review,
|
||||
fact_ledger=self._state.fact_ledger,
|
||||
)
|
||||
# Surface the candidate ids + the evidence refs the ledger has
|
||||
@@ -1257,6 +1350,9 @@ class CrossReviewExecutor(Executor):
|
||||
or review.get("conflicts")
|
||||
or review.get("tool_failures")
|
||||
or review.get("schema_status") == "schema_invalid"
|
||||
# Stage 4: a controlled gap is authoritative — the cross-review
|
||||
# decision must reflect it even when everything else looks clean.
|
||||
or (self._state.quality_gate_enabled and self._state.controlled_gaps)
|
||||
)
|
||||
review["decision"] = "controlled_gap" if has_quality_gap else "accept"
|
||||
review["reason"] = (
|
||||
@@ -1549,16 +1645,24 @@ async def generate_final_report(adapter: Any, state: RoundtableState) -> dict[st
|
||||
manager_id = state.manager_agent_id or "coordinator"
|
||||
thread_id = state.thread_map.get(manager_id, "")
|
||||
|
||||
usable = [
|
||||
r for r in state.turn_results
|
||||
if not r.get("error") or r.get("content")
|
||||
]
|
||||
if state.partial_failure:
|
||||
usable = [r for r in usable if (state.seat_outcomes.get(r.get("agent_id")) or {}).get("status") == "completed"]
|
||||
if state.quality_gate_enabled:
|
||||
# P0-3: Stage 4 synthesizes ONLY accepted task results. There is
|
||||
# deliberately NO fallback to ``turn_results`` — when no delivery was
|
||||
# accepted, the report must be built from the controlled-gap risk
|
||||
# section alone instead of smuggling rejected content back in.
|
||||
seat_results_for_synthesis: list[dict[str, Any]] = list(state.accepted_task_results)
|
||||
else:
|
||||
usable = [
|
||||
r for r in state.turn_results
|
||||
if not r.get("error") or r.get("content")
|
||||
]
|
||||
if state.partial_failure:
|
||||
usable = [r for r in usable if (state.seat_outcomes.get(r.get("agent_id")) or {}).get("status") == "completed"]
|
||||
seat_results_for_synthesis = usable or state.turn_results
|
||||
|
||||
synthesis_input = build_manager_synthesis_input(
|
||||
task_text=state.task_text,
|
||||
seat_results=usable or state.turn_results,
|
||||
seat_results=seat_results_for_synthesis,
|
||||
fact_ledger=state.fact_ledger,
|
||||
)
|
||||
if state.partial_failure:
|
||||
@@ -1573,6 +1677,32 @@ async def generate_final_report(adapter: Any, state: RoundtableState) -> dict[st
|
||||
if state.cross_review_result:
|
||||
synthesis_input += f"\n\n【交叉审查摘要】\n{state.cross_review_result.get('summary', '')[:2000]}"
|
||||
|
||||
# Stage 4 (R3-Q): controlled gaps must reach the final report traceably and
|
||||
# must NEVER be presented as verified facts. They are injected into the
|
||||
# synthesis prompt as an explicit risk/pending-info section.
|
||||
if state.controlled_gaps:
|
||||
gap_lines = [
|
||||
f"- 任务 {gap.get('task_key')}(席位 {gap.get('agent_id')},"
|
||||
f"尝试 {gap.get('attempts', 0)} 次):{gap.get('reason')}"
|
||||
for gap in state.controlled_gaps
|
||||
]
|
||||
synthesis_input += (
|
||||
"\n\n【受控缺口(尚未获得合格席位交付,严禁写成已验证事实)】\n"
|
||||
+ "\n".join(gap_lines)
|
||||
+ "\n要求:把上述每一条缺口完整列入最终结论的『风险/待补信息』章节,"
|
||||
"逐条说明其对结论的影响;不得将缺口内容陈述为已验证结论。"
|
||||
)
|
||||
|
||||
has_gaps = bool(state.controlled_gaps)
|
||||
quality_decision = (
|
||||
"controlled_gap"
|
||||
if has_gaps
|
||||
else (
|
||||
(state.cross_review_result or {}).get("decision")
|
||||
or ("controlled_gap" if state.partial_failure else "accept")
|
||||
)
|
||||
)
|
||||
|
||||
if thread_id:
|
||||
response = await adapter.run_seat_turn(
|
||||
session_id=state.session_id,
|
||||
@@ -1595,11 +1725,9 @@ async def generate_final_report(adapter: Any, state: RoundtableState) -> dict[st
|
||||
"content": response.content,
|
||||
"agent_id": manager_id,
|
||||
"partial_failure": state.partial_failure,
|
||||
"degraded": state.partial_failure,
|
||||
"quality_decision": (
|
||||
(state.cross_review_result or {}).get("decision")
|
||||
or ("controlled_gap" if state.partial_failure else "accept")
|
||||
),
|
||||
"degraded": state.partial_failure or has_gaps,
|
||||
"quality_decision": quality_decision,
|
||||
"controlled_gaps": list(state.controlled_gaps),
|
||||
}
|
||||
else:
|
||||
state.final_result = {
|
||||
@@ -1607,11 +1735,9 @@ async def generate_final_report(adapter: Any, state: RoundtableState) -> dict[st
|
||||
"agent_id": manager_id,
|
||||
"note": "no_manager_thread",
|
||||
"partial_failure": state.partial_failure,
|
||||
"degraded": state.partial_failure,
|
||||
"quality_decision": (
|
||||
(state.cross_review_result or {}).get("decision")
|
||||
or ("controlled_gap" if state.partial_failure else "accept")
|
||||
),
|
||||
"degraded": state.partial_failure or has_gaps,
|
||||
"quality_decision": quality_decision,
|
||||
"controlled_gaps": list(state.controlled_gaps),
|
||||
}
|
||||
|
||||
await adapter._emit_critical(state.run_id, make_run_completed(manager_id, state.current_round + 1, {
|
||||
@@ -1659,6 +1785,617 @@ class WaitingTerminalExecutor(Executor):
|
||||
await ctx.yield_output({"status": "waiting_approval"})
|
||||
|
||||
|
||||
class _SilentWorkflowCtx:
|
||||
"""WorkflowContext stand-in for SeatExecutor invoked INSIDE the quality
|
||||
loop. The embedded SeatExecutor reuses the outer executor's ctx when
|
||||
called directly, which would otherwise publish its messages with the
|
||||
outer node's source id and re-enter the graph. A silent ctx discards
|
||||
those intermediate messages — the quality loop reads the delivery state
|
||||
from ``turn_results`` / ``seat_outcomes`` instead."""
|
||||
|
||||
async def send_message(self, msg: Any) -> None:
|
||||
return None
|
||||
|
||||
async def yield_output(self, msg: Any) -> None:
|
||||
return None
|
||||
|
||||
|
||||
class WaitingInputTerminalExecutor(Executor):
|
||||
"""Terminal executor for the Stage-4 ask_user / waiting_input path.
|
||||
|
||||
Reached when a seat task's fallback policy requests user clarification
|
||||
(``ask_user``) and the manager cannot resolve the gap. The run ends in
|
||||
``waiting_input`` — never as a disguised success.
|
||||
"""
|
||||
|
||||
def __init__(self) -> None:
|
||||
super().__init__(id="waiting_input_terminal")
|
||||
|
||||
@handler(input=Any, workflow_output=dict)
|
||||
async def handle(self, message: Any, ctx: WorkflowContext) -> None:
|
||||
await ctx.yield_output({"status": "waiting_input"})
|
||||
|
||||
|
||||
class QualitySeatTasksExecutor(Executor):
|
||||
"""Stage 4 (R3-Q): run every seat task through the acceptance state machine.
|
||||
|
||||
Replaces the plain SeatExecutor fan-out for V2 structured dispatch. One
|
||||
executor drives all tasks in bounded quality rounds::
|
||||
|
||||
delivering → submitted → manager_review →
|
||||
accepted | rework(→delivering) | reassigned(→delivering) |
|
||||
controlled_gap | ask_user(→ waiting_input)
|
||||
|
||||
Every delivery runs a deterministic quality check first; the manager model
|
||||
then proposes one structured decision per task, and the server finalizes it
|
||||
via :func:`quality_contracts.finalize_review_decision` — a delivery that
|
||||
failed the deterministic checks can NEVER be accepted, reworks are capped
|
||||
by the frozen contract, and an exhausted task ends as ``controlled_gap``
|
||||
(or an explicit ``ask_user`` pause) instead of being disguised as success.
|
||||
|
||||
Task rows persist in ``maf_roundtable_seat_tasks``; reassignment only
|
||||
changes the task's ``agent_id`` (a server-validated backup candidate) and
|
||||
never creates a new task.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
adapter: Any,
|
||||
state: RoundtableState,
|
||||
*,
|
||||
action_coordinator: ActionCoordinator | None = None,
|
||||
max_rework_attempts: int = 2,
|
||||
max_reassignments: int = 1,
|
||||
min_delivery_chars: int = 40,
|
||||
min_delivery_evidence: int = 1,
|
||||
fallback_policy: str = "reassign_then_gap",
|
||||
) -> None:
|
||||
super().__init__(id="quality_seat_tasks")
|
||||
self._adapter = adapter
|
||||
self._state = state
|
||||
self._action_coordinator = action_coordinator
|
||||
self._max_rework_attempts = max_rework_attempts
|
||||
self._max_reassignments = max_reassignments
|
||||
self._min_delivery_chars = min_delivery_chars
|
||||
self._min_delivery_evidence = min_delivery_evidence
|
||||
self._fallback_policy = fallback_policy
|
||||
self._tasks: list[dict[str, Any]] = []
|
||||
|
||||
@property
|
||||
def _store(self) -> Any:
|
||||
return self._adapter._service.store
|
||||
|
||||
@handler(input=Any, output=dict)
|
||||
async def handle(self, message: Any, ctx: WorkflowContext) -> None:
|
||||
if self._state.is_completed("quality_seat_tasks"):
|
||||
await ctx.send_message({
|
||||
"tasks": dict(self._state.seat_task_statuses),
|
||||
"replayed": True,
|
||||
})
|
||||
return
|
||||
|
||||
self._state.stage = "experts"
|
||||
tasks = await self._load_or_create_tasks()
|
||||
self._tasks = tasks
|
||||
base_round = max(self._state.current_round, 1)
|
||||
# P1: duplicate detection is seeded from the persisted task history
|
||||
# (SHA-256 digests of prior conclusions), so a restart cannot re-submit
|
||||
# an already-rejected conclusion and pass it off as new content.
|
||||
prior_conclusions: dict[str, set[str]] = {}
|
||||
for task in tasks:
|
||||
digests = {
|
||||
str(h.get("conclusion_sha256"))
|
||||
for h in (task.get("history") or [])
|
||||
if isinstance(h, dict) and h.get("conclusion_sha256")
|
||||
}
|
||||
prior_conclusions[str(task.get("task_key") or "")] = digests
|
||||
|
||||
# Bounded quality loop: initial delivery + max_rework_attempts reworks
|
||||
# per task budget, plus one delivery round per possible reassignment.
|
||||
max_rounds = (self._max_rework_attempts + 1) * (self._max_reassignments + 1) + 1
|
||||
for round_offset in range(max_rounds):
|
||||
self._state.current_round = base_round + round_offset
|
||||
active = [t for t in tasks if t["status"] not in TASK_TERMINAL_STATUSES]
|
||||
if not active or self._state.status == "waiting_input":
|
||||
break
|
||||
|
||||
submitted: list[dict[str, Any]] = []
|
||||
for task in active:
|
||||
outcome = await self._deliver(task, prior_conclusions)
|
||||
if outcome is not None:
|
||||
submitted.append(outcome)
|
||||
|
||||
if not submitted:
|
||||
continue
|
||||
|
||||
reviews = await self._manager_review(submitted)
|
||||
for task in submitted:
|
||||
final_outcome = await self._apply_decision(task, reviews.get(task["agent_id"]))
|
||||
if final_outcome == OUTCOME_ASK_USER:
|
||||
self._state.status = "waiting_input"
|
||||
self._state.stage = "waiting_input"
|
||||
|
||||
self._state.seat_task_statuses = {
|
||||
t["task_key"]: {
|
||||
"task_key": t["task_key"],
|
||||
"status": t["status"],
|
||||
"agent_id": t["agent_id"],
|
||||
"original_agent_id": t["original_agent_id"],
|
||||
"attempt_count": t["attempt_count"],
|
||||
"rework_count": t["rework_count"],
|
||||
"reassign_count": t["reassign_count"],
|
||||
"required": bool(t["required"]),
|
||||
}
|
||||
for t in tasks
|
||||
}
|
||||
self._state.mark_completed("quality_seat_tasks")
|
||||
await ctx.send_message({"tasks": dict(self._state.seat_task_statuses)})
|
||||
|
||||
# ── task init (atomic, recovery-safe) ───────────────────────────────────
|
||||
|
||||
def _expected_task_specs(self) -> list[dict[str, Any]]:
|
||||
"""The server-computed expected task set from the dispatch assignments.
|
||||
|
||||
``task_key`` is stable per original assignment, so recovery always
|
||||
derives the identical key set — existing rows are kept, rows that a
|
||||
crashed initialization never created are filled back in.
|
||||
"""
|
||||
plan = self._state.dispatch_plan or {}
|
||||
assignments = plan.get("assignments") or []
|
||||
specs: list[dict[str, Any]] = []
|
||||
for index, assignment in enumerate(assignments, start=1):
|
||||
agent_id = str(assignment.get("agent_id") or "").strip()
|
||||
if not agent_id:
|
||||
continue
|
||||
contract = build_task_contract(
|
||||
task_goal=str(assignment.get("task_goal") or ""),
|
||||
delivery_requirements=list(assignment.get("delivery_requirements") or []),
|
||||
required=True,
|
||||
max_rework_attempts=self._max_rework_attempts,
|
||||
fallback_policy=self._fallback_policy, # type: ignore[arg-type]
|
||||
)
|
||||
specs.append({
|
||||
"task_key": f"{index:02d}:{agent_id}",
|
||||
"agent_id": agent_id,
|
||||
"contract": contract.model_dump(),
|
||||
"required": True,
|
||||
})
|
||||
return specs
|
||||
|
||||
async def _load_or_create_tasks(self) -> list[dict[str, Any]]:
|
||||
"""Atomic get-or-create over the FULL expected task set (P0-4).
|
||||
|
||||
Never short-circuits on "some tasks already exist": a crash mid-init
|
||||
must not permanently drop the remaining required seats. Existing rows
|
||||
keep their frozen contracts; concurrent recoveries converge without
|
||||
unique-key errors.
|
||||
"""
|
||||
return await self._store.seat_tasks.get_or_create_tasks(
|
||||
session_id=self._state.session_id,
|
||||
run_id=self._state.run_id,
|
||||
expected=self._expected_task_specs(),
|
||||
)
|
||||
|
||||
# ── delivery step ───────────────────────────────────────────────────────
|
||||
|
||||
async def _deliver(
|
||||
self,
|
||||
task: dict[str, Any],
|
||||
prior_conclusions: dict[str, set[str]],
|
||||
) -> dict[str, Any] | None:
|
||||
"""Run one delivery via SeatExecutor (approvals / ledger / outcomes
|
||||
reuse the existing seat path), then submit it with its deterministic
|
||||
check result. Returns the submitted task dict or ``None`` if the seat
|
||||
run hard-failed without any output."""
|
||||
agent_id = task["agent_id"]
|
||||
|
||||
# Re-delivery must not replay the completed node.
|
||||
node_id = f"seat_{agent_id}"
|
||||
if node_id in self._state.completed_nodes:
|
||||
self._state.completed_nodes.remove(node_id)
|
||||
|
||||
# Reassigned tasks: add the validated backup seat to the selected set
|
||||
# and ensure its participant row + thread before it delivers.
|
||||
if task["status"] == TASK_REASSIGNED:
|
||||
if self._state.selected_seat_agent_ids is not None and agent_id not in self._state.selected_seat_agent_ids:
|
||||
self._state.selected_seat_agent_ids.append(agent_id)
|
||||
await _ensure_selected_seat_threads(self._adapter, self._state)
|
||||
|
||||
is_rework = task["attempt_count"] > 0
|
||||
seat_exec = SeatExecutor(
|
||||
self._adapter,
|
||||
self._state,
|
||||
agent_id,
|
||||
action_coordinator=self._action_coordinator,
|
||||
execution_stage="rework" if is_rework else None,
|
||||
# P0-3: the delivery must not touch the fact ledger until the
|
||||
# manager's final decision accepts it.
|
||||
defer_fact_ledger_merge=True,
|
||||
)
|
||||
await seat_exec.handle({}, _SilentWorkflowCtx())
|
||||
|
||||
turn_row = next(
|
||||
(
|
||||
r for r in reversed(self._state.turn_results)
|
||||
if r.get("agent_id") == agent_id
|
||||
and r.get("turn_index") == self._state.current_round
|
||||
),
|
||||
None,
|
||||
)
|
||||
raw_content = str((turn_row or {}).get("content") or "")
|
||||
structured_output = (turn_row or {}).get("structured_output")
|
||||
schema_status = str((turn_row or {}).get("schema_status") or "ok")
|
||||
delivery = delivery_from_seat_output(
|
||||
structured_output=structured_output, raw_content=raw_content
|
||||
)
|
||||
prior = prior_conclusions.get(task["task_key"])
|
||||
if prior is None:
|
||||
prior = set()
|
||||
prior_conclusions[task["task_key"]] = prior
|
||||
# P1: evidence must be traceable to the fact ledger (recorded evidence
|
||||
# or successful tool results). Self-made findings / invented refs fail
|
||||
# the deterministic gate.
|
||||
verified_refs = known_evidence_refs(self._state.fact_ledger)
|
||||
check = check_delivery_deterministic(
|
||||
delivery=delivery,
|
||||
raw_content=raw_content,
|
||||
schema_status=schema_status,
|
||||
min_length=self._min_delivery_chars,
|
||||
min_evidence=self._min_delivery_evidence,
|
||||
prior_conclusion_digests=prior,
|
||||
verified_evidence_refs=verified_refs,
|
||||
)
|
||||
digest = conclusion_digest(delivery.conclusion) if delivery.conclusion else None
|
||||
if digest:
|
||||
prior.add(digest)
|
||||
|
||||
task["attempt_count"] = int(task.get("attempt_count") or 0) + 1
|
||||
history = list(task.get("history") or [])
|
||||
history.append({
|
||||
"attempt": task["attempt_count"],
|
||||
"agent_id": agent_id,
|
||||
"round": self._state.current_round,
|
||||
"schema_status": schema_status,
|
||||
"failure_codes": list(check["failure_codes"]),
|
||||
# P1: persist the digest only — never the conclusion body — so
|
||||
# duplicate detection survives restarts.
|
||||
"conclusion_sha256": digest,
|
||||
})
|
||||
# P0-3: persisted delivery envelope. ``contract_delivery`` is the
|
||||
# acceptance-facing view; ``validated_seat_output`` is the schema-
|
||||
# validated raw SeatTurnOutput kept back until acceptance merges it
|
||||
# into the fact ledger. Runtime objects / tool-call arguments are
|
||||
# never written here.
|
||||
task["delivery"] = {
|
||||
"contract_delivery": delivery.model_dump(),
|
||||
"validated_seat_output": structured_output
|
||||
if isinstance(structured_output, dict)
|
||||
else None,
|
||||
}
|
||||
task["deterministic_check"] = check
|
||||
task["history"] = history
|
||||
# In-memory only (never persisted): the turn row of this attempt, so
|
||||
# an acceptance can merge exactly what was submitted.
|
||||
task["_turn_row"] = turn_row
|
||||
await self._store.seat_tasks.update_task(task["id"], {
|
||||
"status": TASK_SUBMITTED,
|
||||
"attempt_count": task["attempt_count"],
|
||||
"delivery": task["delivery"],
|
||||
"deterministic_check": check,
|
||||
"history": history,
|
||||
})
|
||||
task["status"] = TASK_SUBMITTED
|
||||
|
||||
await self._adapter._emit_critical(self._state.run_id, make_seat_delivery_submitted(
|
||||
agent_id,
|
||||
self._state.current_round,
|
||||
task_key=task["task_key"],
|
||||
attempt=task["attempt_count"],
|
||||
deterministic_passed=bool(check["passed"]),
|
||||
failure_codes=list(check["failure_codes"]),
|
||||
))
|
||||
return task
|
||||
|
||||
# ── manager review step ─────────────────────────────────────────────────
|
||||
|
||||
async def _manager_review(self, tasks: list[dict[str, Any]]) -> dict[str, Any]:
|
||||
"""One batched manager review call for the round's submissions.
|
||||
|
||||
Returns ``{agent_id: MafManagerReviewItem}``. Any failure (timeout,
|
||||
runtime error, empty output, invalid JSON, schema failure) degrades to
|
||||
an empty dict — every task then finalizes as an INVALID review
|
||||
(``source=system``): a system rework while the cap allows it, or the
|
||||
contract's exhaustion outcome afterwards. A delivery is never accepted
|
||||
without a valid manager review, and a seat missing from a partially
|
||||
valid review is treated the same way.
|
||||
"""
|
||||
manager_id = self._state.manager_agent_id
|
||||
thread_id = self._state.thread_map.get(manager_id or "", "")
|
||||
if not (manager_id and thread_id):
|
||||
return {}
|
||||
|
||||
review_items: list[dict[str, Any]] = []
|
||||
for task in tasks:
|
||||
contract = task.get("contract") or {}
|
||||
envelope = task.get("delivery") or {}
|
||||
# The manager reviews the contract-facing delivery view; the raw
|
||||
# validated seat output stays server-side until acceptance.
|
||||
contract_delivery = envelope.get("contract_delivery") or envelope
|
||||
review_items.append({
|
||||
"agent_id": task["agent_id"],
|
||||
"task_key": task["task_key"],
|
||||
"attempt": task["attempt_count"],
|
||||
"contract": {
|
||||
"objective": contract.get("objective"),
|
||||
"expected_deliverable": contract.get("expected_deliverable"),
|
||||
"acceptance_criteria": list(contract.get("acceptance_criteria") or []),
|
||||
"required": bool(contract.get("required", True)),
|
||||
},
|
||||
"delivery": contract_delivery,
|
||||
"check": task.get("deterministic_check") or {},
|
||||
})
|
||||
prompt = build_manager_review_prompt(
|
||||
task_text=self._state.task_text, review_items=review_items
|
||||
)
|
||||
try:
|
||||
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=self._state.current_round,
|
||||
execution_stage="manager_review",
|
||||
message=prompt,
|
||||
thread_id=thread_id,
|
||||
model_name=self._state.model_name,
|
||||
reasoning_effort=self._state.reasoning_effort,
|
||||
task_text=prompt,
|
||||
stage_instruction="返回严格的总控验收 JSON(每席位一条 decision)",
|
||||
fact_ledger=self._state.fact_ledger,
|
||||
capability_snapshot=self._state.capability_snapshot,
|
||||
write_policy=self._state.write_policy,
|
||||
wait_timeout_seconds=self._state.seat_timeout_seconds,
|
||||
),
|
||||
timeout=self._state.seat_timeout_seconds,
|
||||
)
|
||||
except Exception: # noqa: BLE001 - degraded to deterministic finalization
|
||||
return {}
|
||||
if response.error:
|
||||
return {}
|
||||
model, _errors = parse_manager_review(response.content or "")
|
||||
if model is None:
|
||||
return {}
|
||||
return {item.agent_id: item for item in model.decisions}
|
||||
|
||||
# ── decision application ────────────────────────────────────────────────
|
||||
|
||||
async def _apply_decision(
|
||||
self,
|
||||
task: dict[str, Any],
|
||||
review_item: Any | None,
|
||||
) -> str:
|
||||
"""Finalize and persist one task's review decision; returns the outcome."""
|
||||
contract = MafTaskContract.model_validate(task.get("contract") or {})
|
||||
check = task.get("deterministic_check") or {"passed": False, "failure_codes": []}
|
||||
final = finalize_review_decision(
|
||||
contract=contract,
|
||||
check_result=check,
|
||||
review_item=review_item,
|
||||
rework_count=int(task.get("rework_count") or 0),
|
||||
reassign_count=int(task.get("reassign_count") or 0),
|
||||
has_backup_seat=bool(self._backup_agents(task)),
|
||||
max_reassignments=self._max_reassignments,
|
||||
)
|
||||
outcome = final["decision"]
|
||||
|
||||
await self._adapter._emit_critical(self._state.run_id, make_manager_review_decision(
|
||||
task["agent_id"],
|
||||
self._state.current_round,
|
||||
task_key=task["task_key"],
|
||||
decision=outcome,
|
||||
reason=final["reason"],
|
||||
source=final["source"],
|
||||
attempt=task["attempt_count"],
|
||||
))
|
||||
|
||||
if outcome == OUTCOME_ACCEPTED:
|
||||
task["status"] = TASK_ACCEPTED
|
||||
# P0-3: only an accepted delivery may enter the fact ledger and
|
||||
# the accepted result set consumed by cross-review / the final
|
||||
# synthesis. Reworked / reassigned / gapped attempts never do.
|
||||
envelope = task.get("delivery") or {}
|
||||
validated = envelope.get("validated_seat_output")
|
||||
if isinstance(validated, dict):
|
||||
merge_seat_output(
|
||||
self._state.fact_ledger, validated, agent_id=task["agent_id"]
|
||||
)
|
||||
turn_row = task.get("_turn_row") or {}
|
||||
self._state.accepted_task_results.append({
|
||||
"task_key": task["task_key"],
|
||||
"agent_id": task["agent_id"],
|
||||
"attempt": task["attempt_count"],
|
||||
"accepted": True,
|
||||
"source": final["source"],
|
||||
"turn_index": turn_row.get("turn_index", self._state.current_round),
|
||||
"content": str(turn_row.get("content") or ""),
|
||||
"execution_stage": turn_row.get("execution_stage"),
|
||||
"schema_status": turn_row.get("schema_status"),
|
||||
"structured_output": validated if isinstance(validated, dict) else None,
|
||||
})
|
||||
await self._store.seat_tasks.update_task(task["id"], {
|
||||
"status": TASK_ACCEPTED,
|
||||
"review_decision": final,
|
||||
})
|
||||
|
||||
elif outcome == OUTCOME_REWORK:
|
||||
task["rework_count"] = int(task.get("rework_count") or 0) + 1
|
||||
task["status"] = TASK_REWORK
|
||||
await self._store.seat_tasks.update_task(task["id"], {
|
||||
"status": TASK_REWORK,
|
||||
"rework_count": task["rework_count"],
|
||||
"review_decision": final,
|
||||
})
|
||||
await self._adapter._emit_critical(self._state.run_id, make_seat_rework_assigned(
|
||||
task["agent_id"],
|
||||
self._state.current_round,
|
||||
task_key=task["task_key"],
|
||||
rework_count=task["rework_count"],
|
||||
requirements=list(final.get("revision_requirements") or []),
|
||||
))
|
||||
|
||||
elif outcome == OUTCOME_REASSIGNED:
|
||||
from_agent_id = task["agent_id"]
|
||||
backup = self._pick_backup(task)
|
||||
task["reassign_count"] = int(task.get("reassign_count") or 0) + 1
|
||||
task["agent_id"] = backup
|
||||
task["status"] = TASK_REASSIGNED
|
||||
await self._store.seat_tasks.update_task(task["id"], {
|
||||
"agent_id": backup,
|
||||
"status": TASK_REASSIGNED,
|
||||
"reassign_count": task["reassign_count"],
|
||||
"review_decision": final,
|
||||
})
|
||||
await self._adapter._emit_critical(self._state.run_id, make_seat_reassigned(
|
||||
backup,
|
||||
self._state.current_round,
|
||||
task_key=task["task_key"],
|
||||
from_agent_id=from_agent_id,
|
||||
reassign_count=task["reassign_count"],
|
||||
))
|
||||
|
||||
elif outcome == OUTCOME_CONTROLLED_GAP:
|
||||
gap = make_controlled_gap(
|
||||
task_key=task["task_key"],
|
||||
agent_id=task["agent_id"],
|
||||
objective=contract.objective,
|
||||
reason=final["reason"],
|
||||
failure_codes=list(check.get("failure_codes") or []),
|
||||
attempts=task["attempt_count"],
|
||||
)
|
||||
task["gap"] = gap
|
||||
task["status"] = TASK_CONTROLLED_GAP
|
||||
self._state.controlled_gaps.append(gap)
|
||||
await self._store.seat_tasks.update_task(task["id"], {
|
||||
"status": TASK_CONTROLLED_GAP,
|
||||
"gap": gap,
|
||||
"review_decision": final,
|
||||
})
|
||||
|
||||
else: # OUTCOME_ASK_USER
|
||||
task["status"] = TASK_EXHAUSTED
|
||||
await self._store.seat_tasks.update_task(task["id"], {
|
||||
"status": TASK_EXHAUSTED,
|
||||
"review_decision": final,
|
||||
})
|
||||
|
||||
return outcome
|
||||
|
||||
# ── backup selection (server-validated) ─────────────────────────────────
|
||||
|
||||
def _backup_agents(self, task: dict[str, Any]) -> list[str]:
|
||||
"""Ordered backup candidates for a task.
|
||||
|
||||
Candidates = server candidate seats minus every agent this task has
|
||||
already used (original + rework owners) minus every agent that is the
|
||||
current owner of ANY other task. A seat owns at most one task at a
|
||||
time — a seat whose own task was accepted must not be double-booked as
|
||||
a backup, because it would then hold two tasks and its deliveries
|
||||
would collide on the (run, agent, turn, stage) idempotency key.
|
||||
"""
|
||||
candidates = list(self._state.candidate_seat_agent_ids or [])
|
||||
used: set[str] = {
|
||||
str(item.get("agent_id") or "")
|
||||
for item in (task.get("history") or [])
|
||||
if str(item.get("agent_id") or "")
|
||||
}
|
||||
used.add(str(task.get("agent_id") or ""))
|
||||
for other in self._tasks:
|
||||
if other.get("task_key") == task.get("task_key"):
|
||||
continue
|
||||
used.add(str(other.get("agent_id") or ""))
|
||||
return [agent_id for agent_id in candidates if agent_id not in used]
|
||||
|
||||
def _pick_backup(self, task: dict[str, Any]) -> str:
|
||||
backups = self._backup_agents(task)
|
||||
if not backups:
|
||||
raise RuntimeError(
|
||||
f"MAF quality loop requested reassignment for task "
|
||||
f"{task.get('task_key')} but no validated backup seat exists"
|
||||
)
|
||||
return backups[0]
|
||||
|
||||
|
||||
class QualityGateExecutor(Executor):
|
||||
"""Stage 4 (R3-Q): phase quality gate between seat tasks and cross-review.
|
||||
|
||||
All required seat tasks must have reached a terminal state (``accepted``
|
||||
or ``controlled_gap``) before the phase may proceed. A required task left
|
||||
non-terminal blocks the phase deterministically (hard run failure — the
|
||||
quality loop guarantees terminal states, so a blocked gate is a safety
|
||||
net, never a normal outcome). Controlled gaps do NOT block the phase:
|
||||
they proceed as ``passed_with_gaps`` and are carried into the final
|
||||
report's risk section.
|
||||
"""
|
||||
|
||||
def __init__(self, adapter: Any, state: RoundtableState) -> None:
|
||||
super().__init__(id="quality_gate")
|
||||
self._adapter = adapter
|
||||
self._state = state
|
||||
|
||||
@handler(input=Any, output=dict)
|
||||
async def handle(self, message: Any, ctx: WorkflowContext) -> None:
|
||||
if self._state.is_completed("quality_gate"):
|
||||
await ctx.send_message({"decision": "passed", "replayed": True})
|
||||
return
|
||||
|
||||
# ask_user path: route to the waiting_input terminal, never to
|
||||
# cross-review / finalizer.
|
||||
if self._state.status == "waiting_input":
|
||||
self._state.mark_completed("quality_gate")
|
||||
await ctx.send_message({"decision": "waiting_input"})
|
||||
return
|
||||
|
||||
statuses = self._state.seat_task_statuses
|
||||
required = {k: v for k, v in statuses.items() if v.get("required")}
|
||||
non_terminal = [
|
||||
k for k, v in required.items() if v.get("status") not in TASK_TERMINAL_STATUSES
|
||||
]
|
||||
# P0-4 safety net: every dispatch assignment must be represented by a
|
||||
# task row. A missing required task blocks the gate exactly like a
|
||||
# non-terminal one — the gate must never pass on a dropped seat.
|
||||
expected_keys: list[str] = []
|
||||
plan = self._state.dispatch_plan or {}
|
||||
for index, assignment in enumerate(plan.get("assignments") or [], start=1):
|
||||
agent_id = str(assignment.get("agent_id") or "").strip()
|
||||
if agent_id:
|
||||
expected_keys.append(f"{index:02d}:{agent_id}")
|
||||
missing = [k for k in expected_keys if k not in statuses]
|
||||
blocked = sorted({*non_terminal, *missing})
|
||||
accepted = sum(1 for v in statuses.values() if v.get("status") == TASK_ACCEPTED)
|
||||
gap_count = sum(1 for v in statuses.values() if v.get("status") == TASK_CONTROLLED_GAP)
|
||||
decision = "blocked" if blocked else ("passed_with_gaps" if gap_count else "passed")
|
||||
|
||||
await self._adapter._emit_critical(self._state.run_id, make_stage_quality_gate(
|
||||
self._state.manager_agent_id,
|
||||
self._state.current_round,
|
||||
decision=decision,
|
||||
total=len(statuses),
|
||||
accepted=accepted,
|
||||
controlled_gap=gap_count,
|
||||
blocked_required=blocked,
|
||||
))
|
||||
|
||||
if blocked:
|
||||
raise RuntimeError(
|
||||
f"MAF quality gate blocked: required seat tasks not terminal or missing: "
|
||||
f"{', '.join(blocked)}"
|
||||
)
|
||||
|
||||
self._state.mark_completed("quality_gate")
|
||||
self._state.stage = "review"
|
||||
await ctx.send_message({"decision": decision, "tasks": dict(statuses)})
|
||||
|
||||
|
||||
# ── helpers ─────────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
|
||||
@@ -55,11 +55,19 @@ def build_structured_workflow(
|
||||
dispatch_seat_entry: Any | None = None,
|
||||
manager_answer: Any | None = None,
|
||||
clarification_terminal: Any | None = None,
|
||||
quality_gate: Any | None = None,
|
||||
waiting_input_terminal: Any | None = None,
|
||||
) -> Any:
|
||||
"""Build a structured (fixed-topology) MAF Workflow.
|
||||
|
||||
Topology: planner → parallel seat executors → cross_review → approval gate
|
||||
→ finalizer | waiting_terminal.
|
||||
Topology (Stage 3): planner → parallel seat executors → cross_review →
|
||||
approval gate → finalizer | waiting_terminal.
|
||||
|
||||
Topology (Stage 4 quality gate): quality seat-tasks loop → quality gate →
|
||||
(waiting_input | cross_review) → approval gate → finalizer | waiting_terminal.
|
||||
When ``quality_gate`` is provided, the seat fan-out is replaced by the
|
||||
single quality loop executor and ``waiting_input_terminal`` becomes an
|
||||
additional workflow output for the ``ask_user`` pause path.
|
||||
"""
|
||||
from agent_framework import Case, Default, WorkflowBuilder
|
||||
|
||||
@@ -71,6 +79,8 @@ def build_structured_workflow(
|
||||
outputs.append(manager_answer)
|
||||
if clarification_terminal is not None:
|
||||
outputs.append(clarification_terminal)
|
||||
if waiting_input_terminal is not None:
|
||||
outputs.append(waiting_input_terminal)
|
||||
builder = WorkflowBuilder(
|
||||
start_executor=start,
|
||||
name="maf-structured-roundtable",
|
||||
@@ -97,7 +107,20 @@ def build_structured_workflow(
|
||||
builder.add_switch_case_edge_group(dispatch_router, cases)
|
||||
seat_start = dispatch_seat_entry
|
||||
|
||||
if execution_mode == "chain" and seat_executors:
|
||||
if quality_gate is not None:
|
||||
# Stage 4: single quality-loop node replaces the seat fan-out; the
|
||||
# quality gate routes ask_user pauses to waiting_input_terminal and
|
||||
# everything else to cross-review.
|
||||
builder.add_edge(seat_start, quality_gate)
|
||||
gate_cases = []
|
||||
if waiting_input_terminal is not None:
|
||||
gate_cases.append(Case(
|
||||
condition=lambda out: isinstance(out, dict) and out.get("decision") == "waiting_input",
|
||||
target=waiting_input_terminal,
|
||||
))
|
||||
gate_cases.append(Default(target=cross_review))
|
||||
builder.add_switch_case_edge_group(quality_gate, gate_cases)
|
||||
elif 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)
|
||||
@@ -249,6 +272,8 @@ def create_workflow(
|
||||
dispatch_router: Any | None = None,
|
||||
dispatch_seat_entry: Any | None = None,
|
||||
clarification_terminal: Any | None = None,
|
||||
quality_gate: Any | None = None,
|
||||
waiting_input_terminal: Any | None = None,
|
||||
) -> Any:
|
||||
"""Factory: create the appropriate workflow for the given mode."""
|
||||
if mode == "manager_only":
|
||||
@@ -290,4 +315,6 @@ def create_workflow(
|
||||
dispatch_seat_entry=dispatch_seat_entry,
|
||||
manager_answer=manager_answer,
|
||||
clarification_terminal=clarification_terminal,
|
||||
quality_gate=quality_gate,
|
||||
waiting_input_terminal=waiting_input_terminal,
|
||||
)
|
||||
@@ -36,8 +36,11 @@ from app.maf_roundtable.workflow_executors import (
|
||||
ManagerAnswerExecutor,
|
||||
ManagerDispatchExecutor,
|
||||
PlannerExecutor,
|
||||
QualityGateExecutor,
|
||||
QualitySeatTasksExecutor,
|
||||
RoundtableState,
|
||||
SeatExecutor,
|
||||
WaitingInputTerminalExecutor,
|
||||
WaitingTerminalExecutor,
|
||||
_agent_capabilities_from_snapshot,
|
||||
generate_final_report,
|
||||
@@ -165,6 +168,7 @@ class WorkflowRunner:
|
||||
or candidate_set
|
||||
or maf_v2_payload.get("dispatch_plan") is not None
|
||||
),
|
||||
quality_gate_enabled=self._resolve_quality_gate_enabled(maf_v2_payload),
|
||||
)
|
||||
|
||||
if state.dispatch_contract_enabled:
|
||||
@@ -220,6 +224,54 @@ class WorkflowRunner:
|
||||
except Exception: # noqa: BLE001
|
||||
return 600.0, True
|
||||
|
||||
def _resolve_quality_gate_enabled(self, maf_v2_payload: dict[str, Any]) -> bool:
|
||||
"""Resolve the per-run quality gate flag.
|
||||
|
||||
A boolean frozen in the session's ``maf_v2`` payload wins (sessions
|
||||
created before Stage 4 can opt out explicitly); otherwise the service
|
||||
config default applies.
|
||||
"""
|
||||
payload_flag = maf_v2_payload.get("quality_gate_enabled")
|
||||
if isinstance(payload_flag, bool):
|
||||
return payload_flag
|
||||
return bool(self._quality_settings()["enabled"])
|
||||
|
||||
@staticmethod
|
||||
def _cfg_int(cfg: Any, name: str, default: int) -> int:
|
||||
"""Config int where an explicit 0 is honoured (only None falls back).
|
||||
|
||||
``int(getattr(...) or default)`` would silently turn a deliberate
|
||||
``max_rework_attempts: 0`` back into the default — zero must mean zero.
|
||||
"""
|
||||
value = getattr(cfg, name, None)
|
||||
return default if value is None else int(value)
|
||||
|
||||
def _quality_settings(self) -> dict[str, Any]:
|
||||
try:
|
||||
from deerflow.config import get_app_config
|
||||
|
||||
cfg = get_app_config().maf_roundtable
|
||||
return {
|
||||
"enabled": bool(getattr(cfg, "quality_gate_enabled", True)),
|
||||
"max_rework_attempts": self._cfg_int(cfg, "max_rework_attempts", 2),
|
||||
"max_reassignments": self._cfg_int(cfg, "max_reassignments", 1),
|
||||
"min_delivery_chars": self._cfg_int(cfg, "min_delivery_chars", 40),
|
||||
"min_delivery_evidence": self._cfg_int(cfg, "min_delivery_evidence", 1),
|
||||
"fallback_policy": str(
|
||||
getattr(cfg, "default_fallback_policy", None)
|
||||
or "reassign_then_gap"
|
||||
),
|
||||
}
|
||||
except Exception: # noqa: BLE001
|
||||
return {
|
||||
"enabled": True,
|
||||
"max_rework_attempts": 2,
|
||||
"max_reassignments": 1,
|
||||
"min_delivery_chars": 40,
|
||||
"min_delivery_evidence": 1,
|
||||
"fallback_policy": "reassign_then_gap",
|
||||
}
|
||||
|
||||
def _participants_requiring_threads(
|
||||
self,
|
||||
participants: list[dict[str, Any]],
|
||||
@@ -344,6 +396,37 @@ class WorkflowRunner:
|
||||
|
||||
state.current_round = max(state.current_round, 1)
|
||||
cross_review = CrossReviewExecutor(self._adapter, state)
|
||||
|
||||
# Stage 4 (R3-Q): the quality seat-task loop + phase gate replace
|
||||
# the plain seat fan-out for V2 structured dispatch.
|
||||
if state.quality_gate_enabled:
|
||||
q = self._quality_settings()
|
||||
quality_seats = QualitySeatTasksExecutor(
|
||||
self._adapter,
|
||||
state,
|
||||
action_coordinator=self._action_coordinator,
|
||||
max_rework_attempts=q["max_rework_attempts"],
|
||||
max_reassignments=q["max_reassignments"],
|
||||
min_delivery_chars=q["min_delivery_chars"],
|
||||
min_delivery_evidence=q["min_delivery_evidence"],
|
||||
fallback_policy=q["fallback_policy"],
|
||||
)
|
||||
quality_gate = QualityGateExecutor(self._adapter, state)
|
||||
waiting_input_terminal = WaitingInputTerminalExecutor()
|
||||
return create_workflow(
|
||||
mode="structured",
|
||||
planner=quality_seats,
|
||||
cross_review=cross_review,
|
||||
seat_executors=[],
|
||||
approval_gate=approval_gate,
|
||||
finalizer=finalizer,
|
||||
waiting_terminal=waiting_terminal,
|
||||
seat_agent_ids=[],
|
||||
execution_mode=execution_mode,
|
||||
quality_gate=quality_gate,
|
||||
waiting_input_terminal=waiting_input_terminal,
|
||||
)
|
||||
|
||||
return create_workflow(
|
||||
mode="structured",
|
||||
planner=DispatchSeatEntryExecutor(state),
|
||||
|
||||
Reference in new issue
Block a user