初始化

This commit is contained in:
gozeros committed 2026-09-07 18:24:55 +08:00
1 parent 34474bd5fc
commit b638b541d0
3008 files changed
+837699

No files matched your search

@@ -0,0 +1,60 @@
"""Task-ledger helpers. Completion is artifact-driven; waves are ledger-owned."""
from app.report_collaboration.execution.board import ArtifactBoard
from app.report_collaboration.execution.completion import (
NodeCompletionBlocked,
can_complete_node,
late_output_may_write_completed,
require_can_complete_node,
)
from app.report_collaboration.execution.dispatcher import ReportCollaborationDispatcher
from app.report_collaboration.execution.executor import LeaseParams, ReportCollaborationExecutor
from app.report_collaboration.execution.ledger import ApplyOutcome, TaskAssignment, TaskLedger, TaskResult
from app.report_collaboration.execution.live_hub import (
CoalescingEventSink,
EventRepository,
PublishingReportCollaborationStore,
ReportCollaborationLiveHub,
coalesce_consecutive_deltas,
iter_run_sse,
sanitize_event_payload,
)
from app.report_collaboration.execution.member_runner import ControlledMemberRunner, ScriptedMemberKernel, WaveExecutor
from app.report_collaboration.execution.quality_gate import QualityGate, QualityGateContext, QualityGateResult, requirement_from_session_record
from app.report_collaboration.execution.quality_roles import QualityRoleKernel
from app.report_collaboration.execution.recovery import RecoveryReport, recover_orphaned_attempts
from app.report_collaboration.execution.schema_gate import SchemaGateResult, validate_artifact_draft
__all__ = [
"ApplyOutcome",
"ArtifactBoard",
"CoalescingEventSink",
"ControlledMemberRunner",
"EventRepository",
"LeaseParams",
"RecoveryReport",
"ReportCollaborationDispatcher",
"ReportCollaborationExecutor",
"NodeCompletionBlocked",
"QualityGate",
"QualityGateContext",
"QualityGateResult",
"QualityRoleKernel",
"PublishingReportCollaborationStore",
"ReportCollaborationLiveHub",
"SchemaGateResult",
"ScriptedMemberKernel",
"TaskAssignment",
"TaskLedger",
"TaskResult",
"WaveExecutor",
"can_complete_node",
"coalesce_consecutive_deltas",
"iter_run_sse",
"recover_orphaned_attempts",
"sanitize_event_payload",
"late_output_may_write_completed",
"require_can_complete_node",
"requirement_from_session_record",
"validate_artifact_draft",
]
@@ -0,0 +1,82 @@
"""Artifact board: pending drafts become downstream inputs only after validation."""
from __future__ import annotations
from typing import Any
from uuid import uuid4
from deerflow.persistence.report_collaboration.base import ReportCollaborationStore
from deerflow.persistence.report_collaboration.codec import iso_now
class ArtifactBoard:
"""Persistence wrapper. QualityGate (RC-BE-010) will sit in front of ``validate``."""
def __init__(self, store: ReportCollaborationStore) -> None:
self._store = store
async def submit(
self,
*,
session_id: str,
run_id: str,
node_id: str,
attempt: int,
producer_node_run_id: str,
artifact_type: str,
content: dict[str, Any],
requirement_revision: int,
summary: str | None = None,
validation_status: str = "pending",
) -> dict[str, Any]:
return await self._store.save_artifact(
{
"id": f"rca_{uuid4().hex[:16]}",
"session_id": session_id,
"run_id": run_id,
"node_id": node_id,
"attempt": attempt,
"producer_node_run_id": producer_node_run_id,
"artifact_type": artifact_type,
"schema_version": int(content.get("schema_version") or 1),
"requirement_revision": requirement_revision,
"content": content,
"summary": summary,
"validation_status": validation_status,
"superseded_by": None,
"created_at": iso_now(),
}
)
async def mark(self, artifact: dict[str, Any], *, validation_status: str, superseded_by: str | None = None) -> dict[str, Any]:
payload = dict(artifact)
payload["validation_status"] = validation_status
if superseded_by is not None:
payload["superseded_by"] = superseded_by
return await self._store.save_artifact(payload)
async def supersede_previous(self, *, run_id: str, node_id: str, new_artifact_id: str, attempt: int | None = None) -> list[dict[str, Any]]:
"""Hide older attempts of the same node. Same-attempt siblings stay visible."""
updated: list[dict[str, Any]] = []
for item in await self._store.list_artifacts_full(run_id):
if item.get("node_id") != node_id or item.get("id") == new_artifact_id:
continue
if item.get("superseded_by"):
continue
if attempt is not None and int(item.get("attempt") or 0) >= attempt:
continue
updated.append(await self.mark(item, validation_status="superseded", superseded_by=new_artifact_id))
return updated
async def validated_for(self, run_id: str, artifact_ids: list[str] | None = None) -> list[dict[str, Any]]:
rows = await self._store.list_artifacts_full(run_id)
out = [
item
for item in rows
if item.get("validation_status") == "validated" and not item.get("superseded_by")
]
if artifact_ids is None:
return out
allowed = set(artifact_ids)
return [item for item in out if item["id"] in allowed]
@@ -0,0 +1,49 @@
"""Completion rules: a reply or assistance card never finishes a node by itself."""
from __future__ import annotations
from app.report_collaboration.contracts.enums import ArtifactValidationStatus, CollaborationNodeStatus
class NodeCompletionBlocked(ValueError):
"""Raised when a caller tries to mark a node completed without a validated artifact."""
def can_complete_node(
*,
status: CollaborationNodeStatus,
validation_status: ArtifactValidationStatus | None,
awaiting_input: bool,
cancelled: bool,
) -> bool:
"""Return whether TaskLedger may move this node to ``completed``."""
if cancelled or status in {"cancelled", "cancel_requested", "superseded"}:
return False
if awaiting_input or status == "awaiting_input":
return False
if status != "validating":
return False
return validation_status == "validated"
def require_can_complete_node(
*,
status: CollaborationNodeStatus,
validation_status: ArtifactValidationStatus | None,
awaiting_input: bool = False,
cancelled: bool = False,
) -> None:
if not can_complete_node(
status=status,
validation_status=validation_status,
awaiting_input=awaiting_input,
cancelled=cancelled,
):
raise NodeCompletionBlocked("node cannot complete without a validated artifact, or the current status forbids completion")
def late_output_may_write_completed(*, current_status: CollaborationNodeStatus) -> bool:
"""Cancelled / superseded nodes must ignore late AgentScope output."""
return current_status not in {"cancelled", "superseded", "completed"}
@@ -0,0 +1,131 @@
"""Lease-based dispatcher. ``start()`` is only for ``worker_enabled`` workers.
Gateway-only processes keep ``worker_enabled=false`` and never call ``start()``.
Tests drive ``dispatch_once()`` without mounting a background loop.
"""
from __future__ import annotations
import asyncio
import logging
import os
import socket
import uuid
from datetime import UTC, datetime, timedelta
from app.report_collaboration.execution.executor import LeaseParams, ReportCollaborationExecutor
from deerflow.config.report_collaboration_config import ReportCollaborationConfig
from deerflow.persistence.report_collaboration.base import ReportCollaborationStore
logger = logging.getLogger(__name__)
_POLL_INTERVAL_SECONDS = 2.0
_CLAIM_BATCH = 5
def _worker_id() -> str:
return f"{socket.gethostname()[:24]}-{os.getpid()}-{uuid.uuid4().hex[:6]}"
class ReportCollaborationDispatcher:
def __init__(
self,
store: ReportCollaborationStore,
executor: ReportCollaborationExecutor,
*,
config: ReportCollaborationConfig | None = None,
worker_id: str | None = None,
) -> None:
self._store = store
self._executor = executor
self._config = config or ReportCollaborationConfig()
self._worker_id = worker_id or _worker_id()
self._wake = asyncio.Event()
self._task: asyncio.Task[None] | None = None
self._stopping = False
@property
def worker_id(self) -> str:
return self._worker_id
def start(self) -> None:
if not self._config.worker_enabled:
logger.warning("report collaboration dispatcher.start ignored because worker_enabled is false")
return
if self._task is not None and not self._task.done():
return
self._stopping = False
self._task = asyncio.create_task(self._loop(), name="report-collaboration-dispatcher")
logger.info("report collaboration dispatcher started (worker=%s)", self._worker_id)
async def stop(self) -> None:
self._stopping = True
self._wake.set()
if self._task is not None:
self._task.cancel()
try:
await self._task
except (asyncio.CancelledError, Exception): # noqa: BLE001
pass
self._task = None
await self._executor.drain()
def nudge(self) -> None:
self._wake.set()
async def _loop(self) -> None:
await self._safe_dispatch()
while not self._stopping:
try:
await asyncio.wait_for(self._wake.wait(), timeout=_POLL_INTERVAL_SECONDS)
except TimeoutError:
pass
self._wake.clear()
if self._stopping:
return
await self._safe_dispatch()
async def _safe_dispatch(self) -> None:
try:
await self.dispatch_once()
except asyncio.CancelledError:
raise
except Exception: # noqa: BLE001
logger.exception("report collaboration dispatch round failed")
async def dispatch_once(self) -> int:
await self._reap_cancel_requested()
now = datetime.now(UTC)
candidates = await self._store.list_claimable(now=now, limit=_CLAIM_BATCH)
if not candidates:
return 0
ttl = max(30, int(self._config.lease_seconds))
started = 0
for run_id in candidates:
row = await self._store.claim_run(
run_id,
lease_owner=self._worker_id,
lease_until=now + timedelta(seconds=ttl),
)
if row is None:
continue
if self._executor.start(LeaseParams(run_id=run_id, lease_owner=self._worker_id, attempt=int(row.get("attempt") or 1))):
started += 1
return started
async def _reap_cancel_requested(self) -> None:
for run_id in await self._store.list_cancel_pending():
record = await self._store.get_run_record(run_id)
if record is None:
continue
owner = record.get("lease_owner")
if owner and self._executor.owns(run_id):
continue
finalized = await self._store.finalize_cancel(run_id)
if finalized is not None:
from app.report_collaboration.execution.recovery import cancel_in_flight_nodes
await cancel_in_flight_nodes(self._store, run_id)
__all__ = ["ReportCollaborationDispatcher"]
@@ -0,0 +1,161 @@
"""Claimed-run executor: heartbeat, cancel watcher, recovery, then TaskLedger waves.
Does not pick the next node. AgentScope is only a member kernel injected by the
caller; tests use ``ScriptedMemberKernel``.
"""
from __future__ import annotations
import asyncio
import logging
from dataclasses import dataclass
from datetime import UTC, datetime, timedelta
from typing import Any
from app.report_collaboration.execution.ledger import TaskResult
from app.report_collaboration.execution.member_runner import MemberKernel, WaveExecutor
from app.report_collaboration.execution.recovery import cancel_in_flight_nodes, recover_orphaned_attempts
from app.report_collaboration.interventions.service import RuntimeCommandService
from deerflow.config.report_collaboration_config import ReportCollaborationConfig
from deerflow.persistence.report_collaboration.base import ReportCollaborationStore
logger = logging.getLogger(__name__)
@dataclass(frozen=True)
class LeaseParams:
run_id: str
lease_owner: str
attempt: int = 1
class ReportCollaborationExecutor:
def __init__(
self,
store: ReportCollaborationStore,
kernel: MemberKernel,
*,
config: ReportCollaborationConfig | None = None,
) -> None:
self._store = store
self._kernel = kernel
self._config = config or ReportCollaborationConfig()
self._tasks: dict[str, asyncio.Task[str]] = {}
self._stop_local: dict[str, str] = {}
def start(self, params: LeaseParams) -> bool:
existing = self._tasks.get(params.run_id)
if existing is not None and not existing.done():
return False
self._tasks[params.run_id] = asyncio.create_task(self.execute(params), name=f"rc-run-{params.run_id}")
return True
async def drain(self) -> None:
tasks = [task for task in self._tasks.values() if not task.done()]
for task in tasks:
task.cancel()
for task in tasks:
try:
await task
except (asyncio.CancelledError, Exception): # noqa: BLE001
pass
self._tasks.clear()
def owns(self, run_id: str) -> bool:
task = self._tasks.get(run_id)
return task is not None and not task.done()
async def execute(self, params: LeaseParams) -> str:
main = asyncio.current_task()
heartbeat = asyncio.create_task(self._heartbeat(params, main))
watcher = asyncio.create_task(self._watch_cancel(params, main))
try:
run = await self._store.get_run(params.run_id)
if run is None:
return "missing"
if run.get("cancel_requested"):
return await self._finalize(params)
await recover_orphaned_attempts(self._store, params.run_id)
run = await self._store.get_run(params.run_id)
if run and run.get("cancel_requested"):
return await self._finalize(params)
command_service = RuntimeCommandService(self._store, config=self._config)
await command_service.reclaim_executing(params.run_id, force=True)
waves = WaveExecutor(
self._store,
self._GuardedKernel(self, params),
max_waves=32,
command_processor=command_service,
)
return await waves.run_until_idle(params.run_id)
except asyncio.CancelledError:
current = await self._store.get_run(params.run_id)
if current and (current.get("cancel_requested") or current.get("status") == "cancelled"):
return await self._finalize(params)
return str((current or {}).get("status") or "running")
finally:
heartbeat.cancel()
watcher.cancel()
for task in (heartbeat, watcher):
try:
await task
except (asyncio.CancelledError, Exception): # noqa: BLE001
pass
self._stop_local.pop(params.run_id, None)
self._tasks.pop(params.run_id, None)
async def _finalize(self, params: LeaseParams) -> str:
await self._store.finalize_cancel(params.run_id, lease_owner=params.lease_owner)
await cancel_in_flight_nodes(self._store, params.run_id)
run = await self._store.get_run(params.run_id)
if run:
await self._store.append_event(
session_id=str(run["session_id"]),
run_id=params.run_id,
event_type="run.status.changed",
data={"status": "cancelled"},
)
return "cancelled"
async def _heartbeat(self, params: LeaseParams, main: asyncio.Task[Any] | None) -> None:
interval = max(1, int(self._config.heartbeat_seconds))
ttl = max(int(self._config.lease_seconds), interval * 2)
while True:
await asyncio.sleep(interval)
until = datetime.now(UTC) + timedelta(seconds=ttl)
ok = await self._store.renew_lease(params.run_id, lease_owner=params.lease_owner, lease_until=until)
if not ok:
self._stop_local[params.run_id] = "lease"
if main is not None and not main.done():
main.cancel()
return
async def _watch_cancel(self, params: LeaseParams, main: asyncio.Task[Any] | None) -> None:
while True:
await asyncio.sleep(0.15)
run = await self._store.get_run(params.run_id)
if run is None:
return
if run.get("cancel_requested"):
self._stop_local[params.run_id] = "cancel"
if main is not None and not main.done():
main.cancel()
return
class _GuardedKernel:
def __init__(self, owner: ReportCollaborationExecutor, params: LeaseParams) -> None:
self._owner = owner
self._params = params
async def run(self, assignment: Any, *, context: dict[str, Any]) -> TaskResult:
if self._owner._stop_local.get(self._params.run_id):
raise asyncio.CancelledError
record = await self._owner._store.get_run_record(self._params.run_id)
if record is None or record.get("lease_owner") != self._params.lease_owner:
raise asyncio.CancelledError
if record.get("cancel_requested"):
raise asyncio.CancelledError
return await self._owner._kernel.run(assignment, context=context)
__all__ = ["LeaseParams", "ReportCollaborationExecutor"]
@@ -0,0 +1,736 @@
"""TaskLedger: deterministic wave scheduling. AgentScope never picks the next node."""
from __future__ import annotations
from dataclasses import dataclass, field
from typing import Any, Literal
from app.report_collaboration.contracts.node_machine import require_transition
from app.report_collaboration.execution.board import ArtifactBoard
from app.report_collaboration.execution.completion import late_output_may_write_completed, require_can_complete_node
from app.report_collaboration.execution.quality_gate import QualityGate, QualityGateContext, requirement_from_session_record
from deerflow.persistence.report_collaboration.base import ReportCollaborationStore
from deerflow.persistence.report_collaboration.codec import iso_now, make_node_run_id
TaskResultKind = Literal["artifact_draft", "clarification_request", "repair_request", "failure", "advice"]
_BLOCKING = frozenset({"running", "validating", "awaiting_input", "cancel_requested"})
_DONE = frozenset({"completed"})
_DEAD = frozenset({"cancelled", "superseded"})
@dataclass
class TaskAssignment:
session_id: str
run_id: str
node_id: str
node_run_id: str
phase_id: str
attempt: int
role_key: str
display_name: str
mission: str
requirement_revision: int
allowed_input_artifact_ids: list[str]
expected_artifact_type: str
acceptance_criteria: list[str]
allowed_tools: list[str]
max_attempts: int
agent_profile_snapshot: dict[str, Any]
command_overlay_revision: int
label: str
angle: str | None = None
command_overlays: list[dict[str, Any]] = field(default_factory=list)
@dataclass
class TaskResult:
kind: TaskResultKind
artifact_draft: Any = None
artifact_type: str | None = None
cited_artifact_ids: list[str] = field(default_factory=list)
source_ids: list[str] = field(default_factory=list)
error: str | None = None
clarification: dict[str, Any] | None = None
repair_reason: str | None = None
reply_text: str | None = None
suggested_next_node_ids: list[str] = field(default_factory=list)
additional_drafts: list[dict[str, Any]] = field(default_factory=list)
repair_target_node_ids: list[str] = field(default_factory=list)
reopen_downstream: bool = False
reply_streamed: bool = False
@dataclass
class ApplyOutcome:
node_status: str
run_status: str
repaired: bool = False
artifact: dict[str, Any] | None = None
ignored_coordinator_suggestions: list[str] = field(default_factory=list)
class TaskLedger:
"""Owns ready-set, attempts, and terminal node status.
Coordinator advice is recorded and then discarded as a scheduling input.
Downstream unlocks only after a validated artifact exists for every
dependency.
"""
def __init__(self, store: ReportCollaborationStore) -> None:
self._store = store
self._board = ArtifactBoard(store)
self._gate = QualityGate()
self._phase_seq = 0
async def ready_assignments(self, run_id: str) -> list[TaskAssignment]:
plan, run, latest, artifacts = await self._load(run_id)
if run.get("cancel_requested") or run.get("status") in {"cancelled", "completed", "failed"}:
return []
deps = _dependency_map(plan)
ready_ids = [
node_id
for node_id, node in _plan_nodes(plan).items()
if self._is_ready(node_id, latest, deps, artifacts)
]
if not ready_ids:
return []
self._phase_seq += 1
phase_id = f"phase-{self._phase_seq}"
assignments: list[TaskAssignment] = []
for node_id in ready_ids:
assignment = await self._queue_node(run=run, plan=plan, node_id=node_id, phase_id=phase_id, latest=latest, artifacts=artifacts, deps=deps)
assignments.append(assignment)
await self._store.patch_run(run_id, current_phase=phase_id, status="running")
return assignments
async def apply_result(self, assignment: TaskAssignment, result: TaskResult) -> ApplyOutcome:
ignored = list(result.suggested_next_node_ids or [])
if result.kind == "advice":
return await self.record_coordinator_advice(assignment.run_id, result)
nodes = await self._store.list_node_runs(assignment.run_id)
node = next((item for item in nodes if item["node_run_id"] == assignment.node_run_id), None)
if node is None:
raise KeyError(assignment.node_run_id)
run_row = await self._store.get_run(assignment.run_id) or {}
run_status = str(run_row.get("status") or "running")
if (
run_row.get("cancel_requested")
or run_status in {"cancelled", "completed", "failed"}
or not late_output_may_write_completed(current_status=node["status"])
or node["status"] in {"cancelled", "superseded", "completed", "interrupted"}
):
if result.kind == "artifact_draft" and result.artifact_draft:
content = result.artifact_draft if isinstance(result.artifact_draft, dict) else {"raw": result.artifact_draft}
await self._board.submit(
session_id=assignment.session_id,
run_id=assignment.run_id,
node_id=assignment.node_id,
attempt=assignment.attempt,
producer_node_run_id=assignment.node_run_id,
artifact_type=assignment.expected_artifact_type,
content=content,
requirement_revision=assignment.requirement_revision,
summary="late output after cancel or reclaim",
validation_status="superseded",
)
return ApplyOutcome(node_status=node["status"], run_status=run_status, ignored_coordinator_suggestions=ignored)
if node["status"] == "queued":
require_transition("queued", "running")
node["status"] = "running"
node["started_at"] = iso_now()
await self._store.save_node_run(node)
if result.kind == "clarification_request":
require_transition(node["status"], "awaiting_input")
node["status"] = "awaiting_input"
node["awaiting_input"] = result.clarification or {"reason": "clarification", "question": result.repair_reason or ""}
node["ended_at"] = iso_now()
await self._store.save_node_run(node)
await self._store.patch_run(assignment.run_id, status="awaiting_input", session_status="awaiting_input")
return ApplyOutcome(node_status="awaiting_input", run_status="awaiting_input", ignored_coordinator_suggestions=ignored)
if result.kind in {"failure", "repair_request"} or result.kind != "artifact_draft":
return await self._repair_or_fail(
assignment,
node,
result.error or result.repair_reason or result.kind,
ignored,
repair_target_node_ids=list(result.repair_target_node_ids or []),
reopen_downstream=bool(result.reopen_downstream),
)
expected = assignment.expected_artifact_type
session = await self._store.get_session_record(assignment.session_id)
run_row = await self._store.get_run(assignment.run_id) or {}
plan = await self._store.get_plan(str(run_row.get("plan_id") or ""))
context = QualityGateContext(
requirement=requirement_from_session_record(session),
upstream=await self._store.list_artifacts_full(assignment.run_id),
plan_nodes=list((plan or {}).get("nodes") or []),
node_id=assignment.node_id,
role_key=assignment.role_key,
angle=assignment.angle,
)
gate = self._gate.evaluate(result.artifact_type or expected, result.artifact_draft, context)
require_transition(node["status"], "validating")
node["status"] = "validating"
await self._store.save_node_run(node)
if not gate.ok:
if gate.parsed:
rejected = await self._board.submit(
session_id=assignment.session_id,
run_id=assignment.run_id,
node_id=assignment.node_id,
attempt=assignment.attempt,
producer_node_run_id=assignment.node_run_id,
artifact_type=expected,
content=gate.parsed,
requirement_revision=assignment.requirement_revision,
summary=_summary(gate.parsed),
validation_status="pending",
)
await self._board.mark(rejected, validation_status="rejected")
await self._emit(
assignment,
"artifact.rejected",
{"reason": gate.reason, "node_id": assignment.node_id, "issues": [issue.__dict__ for issue in gate.issues]},
)
return await self._repair_or_fail(assignment, node, gate.reason or "rejected", ignored)
artifact = await self._board.submit(
session_id=assignment.session_id,
run_id=assignment.run_id,
node_id=assignment.node_id,
attempt=assignment.attempt,
producer_node_run_id=assignment.node_run_id,
artifact_type=expected,
content=gate.parsed,
requirement_revision=assignment.requirement_revision,
summary=_summary(gate.parsed),
validation_status="pending",
)
artifact = await self._board.mark(artifact, validation_status="validated")
await self._board.supersede_previous(
run_id=assignment.run_id,
node_id=assignment.node_id,
new_artifact_id=artifact["id"],
attempt=assignment.attempt,
)
for extra in result.additional_drafts or []:
extra_type = str(extra.get("artifact_type") or expected)
extra_gate = self._gate.evaluate(extra_type, extra.get("draft"), context)
if not extra_gate.ok:
await self._emit(
assignment,
"artifact.rejected",
{"reason": extra_gate.reason, "node_id": assignment.node_id, "issues": [issue.__dict__ for issue in extra_gate.issues]},
)
return await self._repair_or_fail(assignment, node, extra_gate.reason or "rejected", ignored)
extra_art = await self._board.submit(
session_id=assignment.session_id,
run_id=assignment.run_id,
node_id=assignment.node_id,
attempt=assignment.attempt,
producer_node_run_id=assignment.node_run_id,
artifact_type=extra_type,
content=extra_gate.parsed,
requirement_revision=assignment.requirement_revision,
summary=_summary(extra_gate.parsed),
validation_status="pending",
)
await self._board.mark(extra_art, validation_status="validated")
require_can_complete_node(status="validating", validation_status="validated")
require_transition("validating", "completed")
node["status"] = "completed"
node["ended_at"] = iso_now()
node["error"] = None
await self._store.save_node_run(node)
await self._emit(assignment, "artifact.validated", {"artifact_id": artifact["id"], "node_id": assignment.node_id})
if expected == "ReviewDecision" and (gate.parsed or {}).get("verdict") == "revise":
await self._replan_review_targets(assignment, gate.parsed or {})
run_status = await self._refresh_run_terminal(assignment.run_id)
return ApplyOutcome(node_status="completed", run_status=run_status, artifact=artifact, ignored_coordinator_suggestions=ignored)
async def record_coordinator_advice(self, run_id: str, result: TaskResult) -> ApplyOutcome:
"""Persist advice without changing the ready set. Suggestions never dispatch nodes."""
run = await self._store.get_run(run_id)
session_id = run["session_id"] if run else ""
await self._store.append_event(
session_id=session_id,
run_id=run_id,
event_type="heartbeat",
data={
"kind": "coordinator_advice",
"suggested_next_node_ids": list(result.suggested_next_node_ids or []),
"ignored": True,
"text": result.reply_text,
},
)
return ApplyOutcome(
node_status="planned",
run_status=(run or {}).get("status") or "running",
ignored_coordinator_suggestions=list(result.suggested_next_node_ids or []),
)
async def apply_user_answer(self, run_id: str, *, command_id: str, instruction: str, node_ids: list[str]) -> list[str]:
"""Resume only the waiting attempts addressed by a user answer."""
_plan, run, latest, _artifacts = await self._load(run_id)
resumed: list[str] = []
for node_id in node_ids:
node = latest.get(node_id)
if node is None or node.get("status") != "awaiting_input":
continue
self._add_command_overlay(node, command_id=command_id, instruction=instruction)
require_transition("awaiting_input", "queued")
node["status"] = "queued"
node["awaiting_input"] = None
node["ended_at"] = None
await self._store.save_node_run(node)
await self._store.append_event(
session_id=str(run["session_id"]),
run_id=run_id,
event_type="node.status.changed",
data={"node_id": node_id, "node_run_id": node["node_run_id"], "status": "queued", "reason": "user_answer"},
)
resumed.append(node_id)
if resumed:
await self._store.patch_run(
run_id,
status="queued",
active_dedupe_key=str(run["session_id"]),
session_status="running",
)
return resumed
async def apply_command_rework(
self,
run_id: str,
*,
command_id: str,
instruction: str,
node_ids: list[str],
) -> list[str]:
"""Supersede affected attempts and persist an immutable command overlay.
A result that returns after this boundary sees its old attempt as
``superseded`` and is therefore stored only as superseded evidence.
User-directed rework is not counted against automatic quality-repair
limits; it creates the next monotonic attempt number.
"""
plan, run, latest, artifacts = await self._load(run_id)
if run.get("cancel_requested") or run.get("status") == "cancelled":
raise ValueError("cannot apply user rework to a cancelled run")
specs = _plan_nodes(plan)
applied: list[str] = []
for node_id in node_ids:
node = latest.get(node_id)
spec = specs.get(node_id)
if node is None or spec is None:
continue
snapshot = dict(node.get("agent_snapshot") or {})
overlays = list(snapshot.get("command_overlays") or [])
if any(str(item.get("command_id")) == command_id for item in overlays if isinstance(item, dict)):
applied.append(node_id)
continue
if node.get("status") in {"planned", "reopened"}:
self._add_command_overlay(node, command_id=command_id, instruction=instruction)
await self._store.save_node_run(node)
applied.append(node_id)
continue
if node.get("status") in {"cancelled", "superseded"}:
continue
require_transition(node["status"], "superseded")
node["status"] = "superseded"
node["ended_at"] = iso_now()
node["awaiting_input"] = None
await self._store.save_node_run(node)
for artifact in artifacts:
if (
artifact.get("node_id") == node_id
and int(artifact.get("attempt") or 0) == int(node.get("attempt") or 0)
and not artifact.get("superseded_by")
):
await self._board.mark(artifact, validation_status="superseded", superseded_by=f"command:{command_id}")
await self._store.append_event(
session_id=str(run["session_id"]),
run_id=run_id,
event_type="node.status.changed",
data={"node_id": node_id, "node_run_id": node["node_run_id"], "status": "superseded", "reason": "user_command"},
)
attempt = int(node.get("attempt") or 0) + 1
replacement = {
"node_run_id": make_node_run_id(run_id, node_id, attempt),
"session_id": run["session_id"],
"run_id": run_id,
"node_id": node_id,
"attempt": attempt,
"status": "planned",
"label": node.get("label") or spec.get("label") or node_id,
"role_display_name": node.get("role_display_name") or spec.get("role_display_name"),
"angle": node.get("angle") or spec.get("angle"),
"progress": None,
"awaiting_input": None,
"contract_json": node.get("contract_json"),
"input_artifact_ids": [],
"command_overlay_revision": int(node.get("command_overlay_revision") or 0),
"agent_snapshot": dict(node.get("agent_snapshot") or {}),
"error": None,
"started_at": None,
"ended_at": None,
}
self._add_command_overlay(replacement, command_id=command_id, instruction=instruction)
await self._store.save_node_run(replacement)
await self._store.append_event(
session_id=str(run["session_id"]),
run_id=run_id,
event_type="node.attempt.created",
data={
"node_id": node_id,
"node_run_id": replacement["node_run_id"],
"attempt": attempt,
"reason": "user_command",
"command_id": command_id,
},
)
applied.append(node_id)
if applied:
next_run_status = "queued" if run.get("status") in {"queued", "awaiting_input", "completed", "failed"} else "running"
await self._store.patch_run(
run_id,
status=next_run_status,
active_dedupe_key=str(run["session_id"]),
session_status="running",
)
return applied
@staticmethod
def _add_command_overlay(node: dict[str, Any], *, command_id: str, instruction: str) -> None:
snapshot = dict(node.get("agent_snapshot") or {})
overlays = [dict(item) for item in snapshot.get("command_overlays") or [] if isinstance(item, dict)]
if not any(str(item.get("command_id")) == command_id for item in overlays):
overlays.append({"command_id": command_id, "instruction": instruction, "created_at": iso_now()})
snapshot["command_overlays"] = overlays
node["agent_snapshot"] = snapshot
node["command_overlay_revision"] = int(node.get("command_overlay_revision") or 0) + 1
async def _repair_or_fail(
self,
assignment: TaskAssignment,
node: dict[str, Any],
reason: str,
ignored: list[str],
*,
repair_target_node_ids: list[str] | None = None,
reopen_downstream: bool = False,
) -> ApplyOutcome:
from_status = node["status"]
if from_status == "validating":
require_transition("validating", "failed")
elif from_status == "running":
require_transition("running", "failed")
elif from_status not in {"failed"}:
require_transition(from_status, "failed")
node["status"] = "failed"
node["error"] = reason
node["ended_at"] = iso_now()
await self._store.save_node_run(node)
if assignment.attempt >= assignment.max_attempts:
run_status = await self._refresh_run_terminal(assignment.run_id)
return ApplyOutcome(node_status="failed", run_status=run_status, ignored_coordinator_suggestions=ignored)
require_transition("failed", "superseded")
node["status"] = "superseded"
await self._store.save_node_run(node)
nxt = assignment.attempt + 1
await self._store.save_node_run(
{
"node_run_id": make_node_run_id(assignment.run_id, assignment.node_id, nxt),
"session_id": assignment.session_id,
"run_id": assignment.run_id,
"node_id": assignment.node_id,
"attempt": nxt,
"status": "planned",
"label": assignment.label,
"role_display_name": assignment.display_name,
"angle": assignment.angle,
"contract_json": node.get("contract_json"),
"input_artifact_ids": list(assignment.allowed_input_artifact_ids),
"command_overlay_revision": assignment.command_overlay_revision,
"agent_snapshot": assignment.agent_profile_snapshot,
"error": None,
"started_at": None,
"ended_at": None,
}
)
await self._replan_targets(
assignment.run_id,
list(repair_target_node_ids or []),
skip={assignment.node_id},
reopen_downstream=reopen_downstream,
)
return ApplyOutcome(node_status="planned", run_status="running", repaired=True, ignored_coordinator_suggestions=ignored)
async def _replan_review_targets(self, assignment: TaskAssignment, decision: dict[str, Any]) -> None:
plan, _run, latest, artifacts = await self._load(assignment.run_id)
mapped = _map_review_targets(plan, artifacts, list(decision.get("issues") or []))
mapped.add(assignment.node_id)
await self._replan_targets(assignment.run_id, sorted(mapped), skip=set(), reopen_downstream=False)
async def _replan_targets(self, run_id: str, node_ids: list[str], *, skip: set[str], reopen_downstream: bool) -> None:
if not node_ids and not reopen_downstream:
return
plan, run, latest, _artifacts = await self._load(run_id)
deps = _dependency_map(plan)
wanted = {node_id for node_id in node_ids if node_id and node_id not in skip}
if reopen_downstream:
changed = True
while changed:
changed = False
for node_id, parents in deps.items():
if node_id in wanted or node_id in skip:
continue
if any(parent in wanted or parent in node_ids for parent in parents):
wanted.add(node_id)
changed = True
for node_id in wanted:
if node_id in skip:
continue
await self._replan_completed_node(run, plan, node_id, latest)
async def _replan_completed_node(self, run: dict[str, Any], plan: dict[str, Any], node_id: str, latest: dict[str, dict[str, Any]]) -> bool:
node = latest.get(node_id)
if node is None or node["status"] != "completed":
return False
spec = _plan_nodes(plan).get(node_id) or {}
max_attempts = int((node.get("contract_json") or {}).get("max_attempts") or spec.get("max_attempts") or 3)
attempt = int(node["attempt"])
if attempt >= max_attempts:
return False
require_transition("completed", "superseded")
node["status"] = "superseded"
node["ended_at"] = iso_now()
await self._store.save_node_run(node)
nxt = attempt + 1
await self._store.save_node_run(
{
"node_run_id": make_node_run_id(str(run["id"]), node_id, nxt),
"session_id": run["session_id"],
"run_id": run["id"],
"node_id": node_id,
"attempt": nxt,
"status": "planned",
"label": node.get("label") or spec.get("label") or node_id,
"role_display_name": node.get("role_display_name") or spec.get("role_display_name"),
"angle": node.get("angle") or spec.get("angle"),
"contract_json": node.get("contract_json"),
"input_artifact_ids": list(node.get("input_artifact_ids") or []),
"command_overlay_revision": node.get("command_overlay_revision") or 0,
"agent_snapshot": node.get("agent_snapshot"),
"error": None,
"started_at": None,
"ended_at": None,
}
)
await self._store.append_event(
session_id=str(run["session_id"]),
run_id=str(run["id"]),
event_type="node.attempt.created",
data={"node_id": node_id, "node_run_id": make_node_run_id(str(run["id"]), node_id, nxt), "attempt": nxt, "reason": "targeted_rework"},
)
return True
async def _queue_node(
self,
*,
run: dict[str, Any],
plan: dict[str, Any],
node_id: str,
phase_id: str,
latest: dict[str, dict[str, Any]],
artifacts: list[dict[str, Any]],
deps: dict[str, list[str]],
) -> TaskAssignment:
spec = _plan_nodes(plan)[node_id]
current = latest[node_id]
status = current["status"]
if status in {"planned", "reopened"}:
require_transition(status, "queued")
current["status"] = "queued"
current["input_artifact_ids"] = _upstream_artifact_ids(deps.get(node_id) or [], latest, artifacts)
current["started_at"] = None
current["ended_at"] = None
current["error"] = None
await self._store.save_node_run(current)
await self._store.append_event(
session_id=str(run["session_id"]),
run_id=str(run["id"]),
event_type="node.status.changed",
data={"node_id": node_id, "node_run_id": current["node_run_id"], "status": current["status"], "phase_id": phase_id},
)
role_key = str(spec.get("role_key") or "")
attempt = int(current["attempt"])
session = await self._store.get_session_record(str(run["session_id"]))
snapshot = dict(current.get("agent_snapshot") or {})
return TaskAssignment(
session_id=str(run["session_id"]),
run_id=str(run["id"]),
node_id=node_id,
node_run_id=str(current["node_run_id"]),
phase_id=phase_id,
attempt=attempt,
role_key=role_key,
display_name=str(spec.get("role_display_name") or spec.get("label") or role_key),
mission=str(spec.get("mission") or ""),
requirement_revision=int((session or {}).get("requirement_revision") or plan.get("requirement_revision") or 0),
allowed_input_artifact_ids=list(current["input_artifact_ids"]),
expected_artifact_type=str(spec.get("output_artifact_type") or ""),
acceptance_criteria=list(spec.get("acceptance_criteria") or []),
allowed_tools=list(spec.get("allowed_tools") or []),
max_attempts=int((current.get("contract_json") or {}).get("max_attempts") or spec.get("max_attempts") or 3),
agent_profile_snapshot=snapshot,
command_overlay_revision=int(current.get("command_overlay_revision") or 0),
label=str(spec.get("label") or node_id),
angle=spec.get("angle"),
command_overlays=[dict(item) for item in snapshot.get("command_overlays") or [] if isinstance(item, dict)],
)
def _is_ready(
self,
node_id: str,
latest: dict[str, dict[str, Any]],
deps: dict[str, list[str]],
artifacts: list[dict[str, Any]],
) -> bool:
current = latest.get(node_id)
if current is None:
return False
status = current["status"]
if status in _BLOCKING or status in _DONE or status in _DEAD or status == "failed":
return False
if status not in {"planned", "reopened"}:
return False
for dep in deps.get(node_id) or []:
parent = latest.get(dep)
if parent is None or parent["status"] != "completed":
return False
if not _has_validated(artifacts, dep, int(parent["attempt"])):
return False
return True
async def _refresh_run_terminal(self, run_id: str) -> str:
_plan, run, latest, _artifacts = await self._load(run_id)
statuses = [item["status"] for item in latest.values()]
if statuses and all(status == "completed" for status in statuses):
from app.report_collaboration.reporting.finalizer import ReportFinalizationError, ReportFinalizer
try:
await ReportFinalizer(self._store).finalize_run(run_id)
except ReportFinalizationError:
await self._store.patch_run(run_id, status="failed", active_dedupe_key=None, session_status="failed")
return "failed"
await self._store.patch_run(run_id, status="completed", active_dedupe_key=None, session_status="completed")
return "completed"
if any(status in _BLOCKING or status == "queued" for status in statuses):
return str(run.get("status") or "running")
if any(status == "failed" for status in statuses):
await self._store.patch_run(run_id, status="failed", active_dedupe_key=None, session_status="failed")
return "failed"
return str(run.get("status") or "running")
async def _load(self, run_id: str) -> tuple[dict[str, Any], dict[str, Any], dict[str, dict[str, Any]], list[dict[str, Any]]]:
run = await self._store.get_run(run_id)
if run is None:
raise KeyError(run_id)
plan = await self._store.get_plan(run["plan_id"])
if plan is None:
raise KeyError(run["plan_id"])
nodes = await self._store.list_node_runs(run_id)
latest: dict[str, dict[str, Any]] = {}
for item in nodes:
current = latest.get(item["node_id"])
if current is None or int(item["attempt"]) >= int(current["attempt"]):
latest[item["node_id"]] = item
artifacts = await self._store.list_artifacts_full(run_id)
return plan, run, latest, artifacts
async def _emit(self, assignment: TaskAssignment, event_type: str, data: dict[str, Any]) -> None:
await self._store.append_event(session_id=assignment.session_id, run_id=assignment.run_id, event_type=event_type, data=data)
def _plan_nodes(plan: dict[str, Any]) -> dict[str, dict[str, Any]]:
return {str(item["id"]): item for item in (plan.get("nodes") or []) if item.get("id")}
def _dependency_map(plan: dict[str, Any]) -> dict[str, list[str]]:
deps: dict[str, list[str]] = {node_id: list(spec.get("depends_on") or []) for node_id, spec in _plan_nodes(plan).items()}
for edge in plan.get("edges") or []:
src, dst = str(edge.get("source") or ""), str(edge.get("target") or "")
if src and dst:
bucket = deps.setdefault(dst, [])
if src not in bucket:
bucket.append(src)
return deps
def _has_validated(artifacts: list[dict[str, Any]], node_id: str, attempt: int) -> bool:
return any(
item.get("node_id") == node_id
and int(item.get("attempt") or 0) == attempt
and item.get("validation_status") == "validated"
and not item.get("superseded_by")
for item in artifacts
)
def _upstream_artifact_ids(dep_ids: list[str], latest: dict[str, dict[str, Any]], artifacts: list[dict[str, Any]]) -> list[str]:
ids: list[str] = []
for dep in dep_ids:
parent = latest.get(dep)
if parent is None:
continue
for item in artifacts:
if (
item.get("node_id") == dep
and int(item.get("attempt") or 0) == int(parent["attempt"])
and item.get("validation_status") == "validated"
and not item.get("superseded_by")
):
ids.append(str(item["id"]))
return ids
def _map_review_targets(plan: dict[str, Any], artifacts: list[dict[str, Any]], issues: list[Any]) -> set[str]:
nodes = _plan_nodes(plan)
section_to_node: dict[str, str] = {}
for item in artifacts:
content = item.get("content") if isinstance(item.get("content"), dict) else {}
section_id = str(content.get("section_id") or "")
if section_id and item.get("node_id"):
section_to_node[section_id] = str(item["node_id"])
mapped: set[str] = set()
writers = {node_id for node_id, spec in nodes.items() if spec.get("role_key") in {"writer", "reviser"}}
for raw in issues:
target = str((raw.get("target") if isinstance(raw, dict) else getattr(raw, "target", None)) or "").strip()
if target in nodes:
mapped.add(target)
elif target in section_to_node:
mapped.add(section_to_node[target])
elif target:
mapped.update(writers)
if not mapped:
mapped.update(writers)
return mapped
def _summary(content: dict[str, Any]) -> str:
if content.get("title"):
return str(content["title"])[:200]
claims = content.get("claims") or []
if claims:
return str(claims[0].get("text") or "")[:200]
return (str(content.get("markdown") or "")[:200]).strip()
@@ -0,0 +1,365 @@
"""Run-scoped live hub, durable event sink, and SSE iterator.
The event log on the report-collaboration store is authoritative. This hub only
shortens tail latency: persist first, then publish. Slow SSE consumers lose the
oldest queued frame; the stream reconciles gaps from the store by ``seq``.
Does not start, cancel, or re-execute runs. Disconnecting a viewer is a no-op
for the worker (when one is mounted later).
"""
from __future__ import annotations
import asyncio
import json
import logging
from collections import defaultdict
from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
from dataclasses import dataclass
from typing import Any
from app.report_collaboration.security import sanitize_for_user
from deerflow.persistence.report_collaboration.base import ReportCollaborationStore
from deerflow.persistence.report_collaboration.codec import is_terminal_run
logger = logging.getLogger(__name__)
DELTA_EVENT_TYPES = frozenset(
{
"message.delta",
"tool_call.delta",
"tool_result.delta",
"team_message.delta",
"report.delta",
}
)
_CONCAT_FIELDS: dict[str, tuple[str, ...]] = {
"message.delta": ("delta", "reasoning_delta"),
"tool_call.delta": ("args_delta", "delta"),
"tool_result.delta": ("delta",),
"team_message.delta": ("delta",),
"report.delta": ("delta",),
}
_DROP_KEYS = frozenset(
{
"traceback",
"stack",
"stack_trace",
"stacktrace",
"exc_info",
"exception_tb",
"system_prompt",
"soul",
"soul_md",
}
)
_REPLAY_PAGE = 200
_DB_POLL_SECONDS = 0.8
_LIVE_WAIT_SECONDS = 0.25
_HEARTBEAT_SECONDS = 15.0
_STREAM_DEADLINE_SECONDS = 60 * 60
_SSE_FLUSH_PADDING = " " * 2_048
class ReportCollaborationLiveHub:
def __init__(self, *, queue_size: int = 512) -> None:
self._subscribers: dict[str, set[asyncio.Queue[dict[str, Any]]]] = defaultdict(set)
self._queue_size = queue_size
def subscribe(self, run_id: str) -> asyncio.Queue[dict[str, Any]]:
queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue(maxsize=self._queue_size)
self._subscribers[run_id].add(queue)
return queue
def unsubscribe(self, run_id: str, queue: asyncio.Queue[dict[str, Any]]) -> None:
subscribers = self._subscribers.get(run_id)
if not subscribers:
return
subscribers.discard(queue)
if not subscribers:
self._subscribers.pop(run_id, None)
def subscriber_count(self, run_id: str) -> int:
return len(self._subscribers.get(run_id) or ())
async def publish(self, event: Mapping[str, Any]) -> None:
run_id = str(event.get("runId") or "")
subscribers = self._subscribers.get(run_id)
if not run_id or not subscribers:
return
payload = dict(event)
for queue in list(subscribers):
if queue.full():
try:
queue.get_nowait()
except asyncio.QueueEmpty: # pragma: no cover - race with a reader
pass
try:
queue.put_nowait(payload)
except asyncio.QueueFull: # pragma: no cover - race with a reader
logger.debug("report collaboration live queue still full for run %s", run_id)
def _drop_secret_keys(value: Any) -> Any:
if isinstance(value, dict):
return {key: _drop_secret_keys(item) for key, item in value.items() if str(key).lower() not in _DROP_KEYS}
if isinstance(value, list):
return [_drop_secret_keys(item) for item in value]
return value
def sanitize_event_payload(data: dict[str, Any] | None) -> dict[str, Any]:
"""Strip stacks / prompts and redact secrets before persist or SSE emit."""
return sanitize_for_user(_drop_secret_keys(dict(data or {}))).value
def delta_identity(event_type: str, data: Mapping[str, Any]) -> str | None:
if event_type not in DELTA_EVENT_TYPES:
return None
if event_type in {"message.delta", "team_message.delta"}:
key = str(data.get("message_id") or "")
elif event_type in {"tool_call.delta", "tool_result.delta"}:
key = str(data.get("tool_call_id") or "")
else:
key = str(data.get("draft_id") or data.get("version_id") or data.get("section_id") or "")
return key or None
def merge_delta_payloads(event_type: str, first: Mapping[str, Any], second: Mapping[str, Any]) -> dict[str, Any]:
merged = dict(first)
concat = set(_CONCAT_FIELDS.get(event_type, ()))
for key, value in second.items():
if key in concat:
continue
merged[key] = value
for field in _CONCAT_FIELDS.get(event_type, ()):
merged[field] = str(first.get(field) or "") + str(second.get(field) or "")
return merged
def coalesce_consecutive_deltas(items: list[tuple[str, dict[str, Any]]]) -> list[tuple[str, dict[str, Any]]]:
"""Merge adjacent same-identity token deltas *before* seq assignment."""
merged: list[tuple[str, dict[str, Any]]] = []
for event_type, data in items:
payload = dict(data)
ident = delta_identity(event_type, payload)
if ident and merged:
prev_type, prev_data = merged[-1]
if prev_type == event_type and delta_identity(prev_type, prev_data) == ident:
merged[-1] = (event_type, merge_delta_payloads(event_type, prev_data, payload))
continue
merged.append((event_type, payload))
return merged
class EventRepository:
"""Paged read of the durable run event log."""
def __init__(self, store: ReportCollaborationStore, *, page_size: int = _REPLAY_PAGE) -> None:
self._store = store
self.page_size = page_size
async def list_after(self, run_id: str, *, after_seq: int, limit: int | None = None) -> list[dict[str, Any]]:
return await self._store.list_events(run_id, after_seq=after_seq, limit=limit or self.page_size)
class PublishingReportCollaborationStore:
"""Delegates to an inner store; sanitizes payloads and fans out after persist."""
def __init__(self, inner: ReportCollaborationStore, hub: ReportCollaborationLiveHub | None = None) -> None:
object.__setattr__(self, "_inner", inner)
object.__setattr__(self, "_hub", hub)
def __getattr__(self, name: str) -> Any:
return getattr(self._inner, name)
async def append_event(
self,
*,
session_id: str,
run_id: str,
event_type: str,
data: dict[str, Any] | None = None,
) -> dict[str, Any]:
raw = _drop_secret_keys(dict(data or {}))
sanitized = sanitize_for_user(raw)
envelope = await self._inner.append_event(
session_id=session_id,
run_id=run_id,
event_type=event_type,
data=sanitized.value if isinstance(sanitized.value, dict) else {"value": sanitized.value},
)
if sanitized.redactions:
await self._inner.append_audit(
session_id=session_id,
run_id=run_id,
category="security",
action="event.redacted",
resource_type="event",
resource_id=str(envelope.get("eventId") or ""),
reason="policy_redaction",
detail={"redactions": [item.as_dict() for item in sanitized.redactions], "event_type": event_type},
)
source = raw.get("source") if isinstance(raw, dict) else None
resource_id = None
resource_type = "event"
if event_type == "source.added" and isinstance(source, dict):
resource_id = str(source.get("id") or "") or None
resource_type = "source"
await self._inner.append_audit(
session_id=session_id,
run_id=run_id,
category="event",
action=event_type,
resource_type=resource_type,
resource_id=resource_id or str(envelope.get("eventId") or ""),
detail={"event_type": event_type},
)
if self._hub is not None:
await self._hub.publish(envelope)
return envelope
class CoalescingEventSink:
"""Buffers consecutive token deltas, then persists via ``append_event``."""
def __init__(self, append_event: Callable[..., Awaitable[dict[str, Any]]]) -> None:
self._append = append_event
self._pending: list[tuple[str, str, str, dict[str, Any]]] = []
async def emit(self, *, session_id: str, run_id: str, event_type: str, data: dict[str, Any] | None = None) -> dict[str, Any] | None:
payload = dict(data or {})
if delta_identity(event_type, payload) is not None:
self._pending.append((session_id, run_id, event_type, payload))
return None
await self.flush()
return await self._append(session_id=session_id, run_id=run_id, event_type=event_type, data=payload)
async def flush(self) -> list[dict[str, Any]]:
if not self._pending:
return []
batch = [(event_type, data) for _session_id, _run_id, event_type, data in self._pending]
session_id = self._pending[0][0]
run_id = self._pending[0][1]
self._pending = []
written: list[dict[str, Any]] = []
for event_type, data in coalesce_consecutive_deltas(batch):
written.append(await self._append(session_id=session_id, run_id=run_id, event_type=event_type, data=data))
return written
@dataclass(frozen=True)
class SseStreamSettings:
replay_page: int = _REPLAY_PAGE
db_poll_seconds: float = _DB_POLL_SECONDS
live_wait_seconds: float = _LIVE_WAIT_SECONDS
heartbeat_seconds: float = _HEARTBEAT_SECONDS
deadline_seconds: float = _STREAM_DEADLINE_SECONDS
flush_padding: str = _SSE_FLUSH_PADDING
def format_sse_frame(envelope: Mapping[str, Any]) -> str:
body = json.dumps(dict(envelope), ensure_ascii=False, separators=(",", ":"), default=str)
seq = envelope.get("seq", 0)
event_type = envelope.get("type") or "message"
return f"id: {seq}\nevent: {event_type}\ndata: {body}\n\n"
def replay_cursor(last_event_id: str | None, after_seq: int) -> int:
"""``Last-Event-ID`` wins when it is an integer seq; otherwise ``after_seq``."""
if last_event_id:
try:
return max(0, int(str(last_event_id).strip()))
except (TypeError, ValueError):
pass
return max(0, after_seq)
async def iter_run_sse(
*,
store: ReportCollaborationStore,
hub: ReportCollaborationLiveHub | None,
run_id: str,
cursor: int,
is_disconnected: Callable[[], Awaitable[bool]],
settings: SseStreamSettings | None = None,
) -> AsyncIterator[str]:
"""Replay from ``cursor`` then tail live. Disconnect does not cancel the run."""
cfg = settings or SseStreamSettings()
repo = EventRepository(store, page_size=cfg.replay_page)
live_queue = hub.subscribe(run_id) if hub is not None else None
loop = asyncio.get_running_loop()
deadline = loop.time() + cfg.deadline_seconds
next_poll = 0.0
last_beat = loop.time()
try:
yield f": stream-ready{cfg.flush_padding}\n\n"
while loop.time() < deadline:
if await is_disconnected():
return
if loop.time() >= next_poll:
try:
while True:
rows = await repo.list_after(run_id, after_seq=cursor)
if not rows:
break
for row in rows:
seq = int(row.get("seq") or 0)
if seq <= cursor:
continue
yield format_sse_frame(row)
cursor = seq
last_beat = loop.time()
if len(rows) < cfg.replay_page:
break
current = await store.get_run(run_id)
if current is None:
return
if is_terminal_run(str(current.get("status") or "")):
return
next_poll = loop.time() + cfg.db_poll_seconds
except Exception:
logger.exception("report collaboration event replay failed for run %s", run_id)
yield ": storage-retry\n\n"
last_beat = loop.time()
next_poll = loop.time() + cfg.db_poll_seconds
await asyncio.sleep(min(cfg.db_poll_seconds, 0.5))
continue
if live_queue is not None:
try:
event = await asyncio.wait_for(live_queue.get(), timeout=cfg.live_wait_seconds)
except TimeoutError:
event = None
if event is not None:
seq = int(event.get("seq") or 0)
if seq == cursor + 1:
yield format_sse_frame(event)
cursor = seq
last_beat = loop.time()
else:
await asyncio.sleep(cfg.live_wait_seconds)
if loop.time() - last_beat >= cfg.heartbeat_seconds:
yield ": heartbeat\n\n"
last_beat = loop.time()
finally:
if live_queue is not None and hub is not None:
hub.unsubscribe(run_id, live_queue)
__all__ = [
"CoalescingEventSink",
"DELTA_EVENT_TYPES",
"EventRepository",
"PublishingReportCollaborationStore",
"ReportCollaborationLiveHub",
"SseStreamSettings",
"coalesce_consecutive_deltas",
"delta_identity",
"format_sse_frame",
"iter_run_sse",
"merge_delta_payloads",
"replay_cursor",
"sanitize_event_payload",
]
@@ -0,0 +1,207 @@
"""Controlled member runner. AgentScope executes one assignment; it cannot pick the next node."""
from __future__ import annotations
from collections.abc import Callable
from typing import Any, Protocol
from uuid import uuid4
from app.report_collaboration.agentscope_runtime.event_adapter import ConversationReplica, MemberStreamContext, SeqAllocator, make_emitter
from app.report_collaboration.agentscope_runtime.permission_adapter import PermissionAdapter
from app.report_collaboration.execution.ledger import TaskAssignment, TaskLedger, TaskResult
from app.report_collaboration.execution.live_hub import CoalescingEventSink
from deerflow.persistence.report_collaboration.base import ReportCollaborationStore
from deerflow.persistence.report_collaboration.codec import iso_now
class MemberKernel(Protocol):
async def run(self, assignment: TaskAssignment, *, context: dict[str, Any]) -> TaskResult:
...
class SafePointProcessor(Protocol):
async def process_safe_point(self, run_id: str, *, completed_node_id: str | None = None) -> list[str]:
...
class ScriptedMemberKernel:
"""Deterministic kernel for tests. Never consults AgentScope Team scheduling."""
def __init__(self, scripts: dict[str, list[TaskResult]] | None = None) -> None:
self._scripts = {key: list(value) for key, value in (scripts or {}).items()}
self.calls: list[str] = []
def enqueue(self, node_id: str, *results: TaskResult) -> None:
self._scripts.setdefault(node_id, []).extend(results)
async def run(self, assignment: TaskAssignment, *, context: dict[str, Any]) -> TaskResult:
self.calls.append(assignment.node_id)
queue = self._scripts.get(assignment.node_id) or []
if queue:
return queue.pop(0)
fallback = self._scripts.get(assignment.role_key) or []
if fallback:
return fallback.pop(0)
raise AssertionError(f"no scripted result for node {assignment.node_id} role {assignment.role_key}")
class ControlledMemberRunner:
"""Runs one TaskAssignment: permission snapshot, replica events, TaskResult.
Does not inspect coordinator suggestions and does not call TaskLedger.ready.
"""
def __init__(self, store: ReportCollaborationStore, kernel: MemberKernel, *, permission: PermissionAdapter | None = None) -> None:
self._store = store
self._kernel = kernel
self._permission = permission or PermissionAdapter()
async def run(self, assignment: TaskAssignment, *, context: dict[str, Any] | None = None) -> TaskResult:
started = iso_now()
agent_run_id = f"ar-{assignment.node_run_id}"
snapshot = self._permission.freeze(
role_key=assignment.role_key,
member_id=agent_run_id,
node_run_id=assignment.node_run_id,
agent_run_id=agent_run_id,
allowed_tools=assignment.allowed_tools or None,
created_at=started,
)
await self._store.save_agent_run(
{
"agent_run_id": agent_run_id,
"session_id": assignment.session_id,
"run_id": assignment.run_id,
"node_run_id": assignment.node_run_id,
"phase_id": assignment.phase_id,
"role": assignment.role_key,
"display_name": assignment.display_name,
"status": "running",
"started_at": started,
"agent_snapshot": snapshot.model_dump(mode="json") if hasattr(snapshot, "model_dump") else {"role_key": assignment.role_key},
}
)
await self._snapshot_event(assignment, agent_run_id, status="running")
ctx = dict(context or {})
ctx["permission"] = snapshot
ctx["agent_run_id"] = agent_run_id
ctx["command_overlays"] = list(assignment.command_overlays)
result = await self._kernel.run(assignment, context=ctx)
await self._mirror_reply(assignment, agent_run_id, result)
if result.kind == "clarification_request":
agent_status = "waiting_input"
elif result.kind in {"failure", "repair_request"}:
agent_status = "failed"
else:
agent_status = "completed"
await self._store.save_agent_run(
{
"agent_run_id": agent_run_id,
"session_id": assignment.session_id,
"run_id": assignment.run_id,
"node_run_id": assignment.node_run_id,
"phase_id": assignment.phase_id,
"role": assignment.role_key,
"display_name": assignment.display_name,
"status": agent_status,
"started_at": started,
"ended_at": iso_now(),
}
)
await self._snapshot_event(assignment, agent_run_id, status=agent_status)
return result
async def _snapshot_event(self, assignment: TaskAssignment, agent_run_id: str, *, status: str) -> None:
await self._store.append_event(
session_id=assignment.session_id,
run_id=assignment.run_id,
event_type="session.snapshot",
data={
"agent_runs": [
{
"agent_run_id": agent_run_id,
"node_run_id": assignment.node_run_id,
"phase_id": assignment.phase_id,
"role": assignment.role_key,
"display_name": assignment.display_name,
"status": status,
}
],
"run": {"current_phase": assignment.phase_id},
},
)
async def _mirror_reply(self, assignment: TaskAssignment, agent_run_id: str, result: TaskResult) -> None:
text = result.reply_text
if not text:
return
allocator = SeqAllocator()
emit = make_emitter(assignment.session_id, assignment.run_id, allocator)
replica = ConversationReplica(
MemberStreamContext(
session_id=assignment.session_id,
run_id=assignment.run_id,
agent_run_id=agent_run_id,
node_run_id=assignment.node_run_id,
phase_id=assignment.phase_id,
display_name=assignment.display_name,
),
emit,
)
reply_id = f"msg_{uuid4().hex[:12]}"
events = []
events.extend(replica.ingest({"type": "REPLY_START", "reply_id": reply_id, "name": assignment.display_name}))
events.extend(replica.ingest({"type": "TEXT_BLOCK_DELTA", "reply_id": reply_id, "delta": text}))
events.extend(replica.ingest({"type": "REPLY_END", "reply_id": reply_id, "finished_reason": "completed"}))
sink = CoalescingEventSink(self._store.append_event)
for event in events:
await sink.emit(session_id=assignment.session_id, run_id=assignment.run_id, event_type=event.type, data=event.data)
await sink.flush()
class WaveExecutor:
"""Drive TaskLedger waves with a ControlledMemberRunner.
Not a dispatcher: no lease, no process claim, not mounted on the Gateway.
Tests and an explicit inline caller invoke ``run_until_idle``.
"""
def __init__(
self,
store: ReportCollaborationStore,
kernel: MemberKernel,
*,
max_waves: int = 32,
command_processor: SafePointProcessor | None = None,
) -> None:
self._store = store
self._ledger = TaskLedger(store)
self._runner = ControlledMemberRunner(store, kernel)
self._kernel = kernel
self._max_waves = max_waves
self._command_processor = command_processor
self.dispatched: list[str] = []
@property
def ledger(self) -> TaskLedger:
return self._ledger
async def run_until_idle(self, run_id: str, *, coordinator: Callable[[], TaskResult] | None = None) -> str:
if coordinator is not None:
advice = coordinator()
await self._ledger.record_coordinator_advice(run_id, advice)
for _ in range(self._max_waves):
if self._command_processor is not None:
await self._command_processor.process_safe_point(run_id)
wave = await self._ledger.ready_assignments(run_id)
if not wave:
run = await self._store.get_run(run_id)
return str((run or {}).get("status") or "queued")
for assignment in wave:
self.dispatched.append(assignment.node_id)
result = await self._runner.run(assignment)
if self._command_processor is not None:
await self._command_processor.process_safe_point(run_id, completed_node_id=assignment.node_id)
await self._ledger.apply_result(assignment, result)
run = await self._store.get_run(run_id)
return str((run or {}).get("status") or "running")
@@ -0,0 +1,437 @@
"""Claim-level QualityGate. Schema-ok drafts still fail here on conflicts, unverified facts, or unmapped review targets.
Writer/analysis may not pick a side when two numbers conflict. Downstream facts may only cite supported (or, if no verifier ran, schema-clean) claim IDs.
"""
from __future__ import annotations
import re
from dataclasses import dataclass, field
from typing import Any
from app.report_collaboration.contracts.artifacts import (
AngleAnalysis,
CoverageMatrix,
EvidenceBundle,
EvidenceClaim,
ReportSectionDraft,
ReviewDecision,
ReviewIssue,
VerificationResult,
)
from app.report_collaboration.contracts.reports import ReportVersion
from app.report_collaboration.contracts.requirements import ReportRequirementSnapshot
from app.report_collaboration.execution.schema_gate import SchemaGateResult, validate_artifact_draft
_YEAR = re.compile(r"\b(19|20)\d{2}\b")
_QUANTITY = re.compile(r"(?<!\d)(\d+(?:\.\d+)?)(\s*(?:%|%|个百分点|万亿|万|亿|倍)?)")
_VAGUE_TARGETS = frozenset({"", "整体", "全文", "整篇", "报告", "全部", "整体再优化"})
_VAGUE_REQUIREMENT = re.compile(r"^(请)?(整体)?(再)?(优化|润色|改进)(一下|一?下)?$")
_STOP = frozenset({"的", "了", "在", "与", "和", "及", "年", "为", "是", "对", "中"})
@dataclass
class GateIssue:
code: str
message: str
target: str | None = None
@dataclass
class QualityGateResult:
ok: bool
reason: str | None = None
issues: list[GateIssue] = field(default_factory=list)
parsed: dict[str, Any] = field(default_factory=dict)
@dataclass
class QualityGateContext:
requirement: ReportRequirementSnapshot | None = None
upstream: list[dict[str, Any]] = field(default_factory=list)
plan_nodes: list[dict[str, Any]] = field(default_factory=list)
node_id: str = ""
role_key: str = ""
angle: str | None = None
class QualityGate:
"""Deterministic claim/citation/review gates. No model calls."""
def evaluate(self, artifact_type: str, draft: Any, context: QualityGateContext | None = None) -> QualityGateResult:
schema: SchemaGateResult = validate_artifact_draft(artifact_type, draft)
if not schema.ok:
return QualityGateResult(
ok=False,
reason=schema.reason,
issues=[GateIssue(code=schema.reason or "schema", message=schema.reason or "schema")],
parsed=schema.parsed,
)
ctx = context or QualityGateContext()
issues = self._check(artifact_type, schema.parsed, ctx)
if issues:
return QualityGateResult(ok=False, reason=issues[0].code, issues=issues, parsed=schema.parsed)
return QualityGateResult(ok=True, parsed=schema.parsed)
def _check(self, artifact_type: str, parsed: dict[str, Any], ctx: QualityGateContext) -> list[GateIssue]:
if artifact_type == "EvidenceBundle":
return _check_evidence(EvidenceBundle.model_validate(parsed), ctx)
if artifact_type == "VerificationResult":
return _check_verification(VerificationResult.model_validate(parsed), ctx)
if artifact_type == "AngleAnalysis":
return _check_analysis(AngleAnalysis.model_validate(parsed), ctx)
if artifact_type == "ReportSectionDraft":
return _check_section(ReportSectionDraft.model_validate(parsed), ctx)
if artifact_type == "ReviewDecision":
return _check_review(ReviewDecision.model_validate(parsed), ctx)
if artifact_type == "CoverageMatrix":
return _check_coverage(CoverageMatrix.model_validate(parsed), ctx)
if artifact_type == "ReportVersion":
return _check_report_version(ReportVersion.model_validate(parsed), ctx)
return []
def requirement_from_session_record(record: dict[str, Any] | None) -> ReportRequirementSnapshot | None:
if not record:
return None
raw = record.get("requirement_json")
snapshot: dict[str, Any] | None = None
if isinstance(raw, dict) and isinstance(raw.get("snapshot"), dict):
snapshot = dict(raw["snapshot"])
elif isinstance(raw, dict) and raw.get("topic"):
snapshot = dict(raw)
if snapshot is None:
return None
snapshot.setdefault("required_angles", [])
snapshot.setdefault("excluded_angles", [])
snapshot["revision"] = max(1, int(snapshot.get("revision") or record.get("requirement_revision") or 1))
try:
return ReportRequirementSnapshot.model_validate(snapshot)
except Exception:
return None
def verified_claim_ids(upstream: list[dict[str, Any]]) -> set[str]:
"""Claim IDs that may appear in downstream facts.
If a verifier has produced results, only ``supported`` claims count.
Otherwise schema-clean evidence counts, minus numeric conflict pairs —
the writer must not pick a side.
"""
bundles = [_content(item) for item in upstream if item.get("artifact_type") == "EvidenceBundle" and item.get("validation_status") == "validated"]
all_ids = {str(claim.get("claim_id")) for bundle in bundles for claim in (bundle.get("claims") or []) if claim.get("claim_id")}
pair_conflicts: set[str] = set()
for bundle in bundles:
try:
parsed = EvidenceBundle.model_validate(bundle)
except Exception:
continue
for left, right in _conflict_pairs(parsed.claims):
pair_conflicts.add(left)
pair_conflicts.add(right)
verifications = [
_content(item)
for item in upstream
if item.get("artifact_type") == "VerificationResult" and item.get("validation_status") == "validated"
]
if not verifications:
return all_ids - pair_conflicts
return {str(item.get("claim_id")) for item in verifications if item.get("verdict") == "supported" and item.get("claim_id")}
def conflicting_claim_ids(upstream: list[dict[str, Any]]) -> set[str]:
"""Numeric conflicts across all validated evidence bundles, not just inside one row."""
claims: list[EvidenceClaim] = []
for row in upstream:
if row.get("artifact_type") != "EvidenceBundle" or row.get("validation_status") != "validated":
continue
if row.get("superseded_by"):
continue
try:
claims.extend(EvidenceBundle.model_validate(_content(row)).claims)
except Exception:
continue
return {claim_id for pair in _conflict_pairs(claims) for claim_id in pair}
def contested_claim_ids(upstream: list[dict[str, Any]]) -> set[str]:
from_verdicts = {
str(item.get("claim_id"))
for item in (_content(row) for row in upstream if row.get("artifact_type") == "VerificationResult" and row.get("validation_status") == "validated")
if item.get("verdict") in {"contested", "unsupported", "stale"} and item.get("claim_id")
}
from_bundles: set[str] = set()
for row in upstream:
if row.get("artifact_type") != "EvidenceBundle" or row.get("validation_status") != "validated":
continue
bundle = EvidenceBundle.model_validate(_content(row))
blob = " ".join(bundle.conflicts)
from_bundles.update(claim.claim_id for claim in bundle.claims if claim.claim_id and claim.claim_id in blob)
for left, right in _conflict_pairs(bundle.claims):
from_bundles.add(left)
from_bundles.add(right)
return from_verdicts | from_bundles
def _content(row: dict[str, Any]) -> dict[str, Any]:
raw = row.get("content")
return raw if isinstance(raw, dict) else {}
def _check_evidence(bundle: EvidenceBundle, ctx: QualityGateContext) -> list[GateIssue]:
issues: list[GateIssue] = []
source_ids = {item.source_id for item in bundle.sources}
seen: set[str] = set()
for claim in bundle.claims:
if claim.claim_id in seen:
issues.append(GateIssue("duplicate_claim", f"重复主张 {claim.claim_id}", claim.claim_id))
seen.add(claim.claim_id)
missing = [sid for sid in claim.source_ids if sid not in source_ids]
if missing:
issues.append(GateIssue("dangling_source", f"主张 {claim.claim_id} 引用了不存在的来源", claim.claim_id))
if claim.kind == "fact" and _needs_unit(claim.text) and not (claim.unit or "").strip():
issues.append(GateIssue("missing_unit", f"数字主张 {claim.claim_id} 缺少口径/单位", claim.claim_id))
for pair in _conflict_pairs(bundle.claims):
issues.append(GateIssue("numeric_conflict", f"主张 {pair[0]} 与 {pair[1]} 数字冲突且未核验", pair[0]))
if ctx.angle and ctx.requirement and ctx.requirement.required_angles and ctx.angle in ctx.requirement.required_angles:
if not _mentions(bundle, ctx.angle):
issues.append(GateIssue("coverage_gap", f"未覆盖必选角度 {ctx.angle}", ctx.angle))
return issues
def _check_verification(result: VerificationResult, ctx: QualityGateContext) -> list[GateIssue]:
issues: list[GateIssue] = []
all_claims = {
str(claim.get("claim_id"))
for row in ctx.upstream
if row.get("artifact_type") == "EvidenceBundle"
for claim in (_content(row).get("claims") or [])
if claim.get("claim_id")
}
if result.claim_id not in all_claims:
issues.append(GateIssue("unknown_claim", f"核验目标 {result.claim_id} 不在上游证据中", result.claim_id))
if result.verdict == "supported" and not result.supporting_source_ids:
issues.append(GateIssue("unsupported_support", "支持结论缺少来源", result.claim_id))
if result.verdict == "contested" and not result.conflicts and not result.opposing_source_ids:
issues.append(GateIssue("empty_contest", "争议结论必须指出反对来源或冲突", result.claim_id))
return issues
def _check_analysis(analysis: AngleAnalysis, ctx: QualityGateContext) -> list[GateIssue]:
issues: list[GateIssue] = []
allowed = verified_claim_ids(ctx.upstream)
contested = contested_claim_ids(ctx.upstream)
if _plan_has_verifier(ctx) and not any(item.get("artifact_type") == "VerificationResult" and item.get("validation_status") == "validated" for item in ctx.upstream):
issues.append(GateIssue("unverified_sources", "计划含核验节点,分析不能跳过 VerificationResult", analysis.angle))
for eid in analysis.evidence_ids:
if eid in contested:
issues.append(GateIssue("contested_claim", f"分析引用了冲突/未通过核验的主张 {eid}", eid))
elif eid not in allowed:
issues.append(GateIssue("unverified_sources", f"分析引用了未核验主张 {eid}", eid))
if not analysis.facts and not analysis.inferences:
issues.append(GateIssue("empty_output", "分析未区分事实或推断", analysis.angle))
return issues
def _check_section(draft: ReportSectionDraft, ctx: QualityGateContext) -> list[GateIssue]:
issues: list[GateIssue] = []
allowed = verified_claim_ids(ctx.upstream)
contested = contested_claim_ids(ctx.upstream)
cited: set[str] = set(draft.evidence_ids)
for extra in draft.claim_citation_map.values():
cited.update(extra)
for eid in cited:
if eid in contested and eid not in allowed:
issues.append(GateIssue("contested_claim", f"章节把冲突主张 {eid} 写成了事实", eid))
elif eid not in allowed:
issues.append(GateIssue("unverified_sources", f"章节引用了未核验主张 {eid}", eid))
issues.extend(_lint_citations(draft.markdown, cited, ctx))
issues.extend(_coverage_against_requirement(draft.markdown, ctx))
return issues
def _check_review(decision: ReviewDecision, ctx: QualityGateContext) -> list[GateIssue]:
issues: list[GateIssue] = []
if decision.verdict == "revise" and not decision.issues:
issues.append(GateIssue("empty_review", "revise 必须列出可映射的问题", None))
known_targets = _review_targets(ctx)
for item in decision.issues:
issues.extend(_review_issue_problems(item, known_targets))
return issues
def _check_coverage(matrix: CoverageMatrix, ctx: QualityGateContext) -> list[GateIssue]:
required = list(matrix.required_angles) or list((ctx.requirement.required_angles if ctx.requirement else []) or [])
missing = [angle for angle in required if angle not in set(matrix.covered_angles)]
issues = [GateIssue("coverage_gap", f"覆盖矩阵缺少角度 {angle}", angle) for angle in missing]
if matrix.gaps and required:
issues.append(GateIssue("coverage_gap", "覆盖矩阵仍有缺口", None))
questions = list(matrix.required_questions)
missing_q = [q for q in questions if q not in set(matrix.covered_questions)]
issues.extend(GateIssue("coverage_gap", f"未覆盖必答问题 {q}", q) for q in missing_q)
return issues
def _check_report_version(version: ReportVersion, ctx: QualityGateContext) -> list[GateIssue]:
issues: list[GateIssue] = []
if not (version.markdown or "").strip():
issues.append(GateIssue("empty_output", "正式版本正文为空", None))
matrices = [
CoverageMatrix.model_validate(_content(row))
for row in ctx.upstream
if row.get("artifact_type") == "CoverageMatrix" and row.get("validation_status") == "validated"
]
if ctx.requirement and ctx.requirement.required_angles:
if matrices:
for matrix in matrices:
issues.extend(_check_coverage(matrix, ctx))
else:
issues.extend(_coverage_against_requirement(version.markdown, ctx))
cited = {str(src.id) for src in version.source_index if src.id}
issues.extend(_lint_citations(version.markdown, cited, ctx))
return issues
def _review_issue_problems(item: ReviewIssue, known_targets: set[str]) -> list[GateIssue]:
issues: list[GateIssue] = []
target = (item.target or "").strip()
requirement = (item.requirement or "").strip()
if target in _VAGUE_TARGETS or _VAGUE_REQUIREMENT.match(requirement):
issues.append(GateIssue("vague_review", "审稿问题必须指向具体节点或章节,不能只要求整体再优化", target or None))
if not item.severity.strip():
issues.append(GateIssue("unmapped_review_target", "缺少严重度", target or None))
if not requirement:
issues.append(GateIssue("unmapped_review_target", "缺少修复要求", target or None))
if not (item.evidence or "").strip():
issues.append(GateIssue("unmapped_review_target", "缺少证据", target or None))
if target and target not in known_targets and not _looks_like_section(target):
issues.append(GateIssue("unmapped_review_target", f"返工目标无法映射到节点或章节:{target}", target))
return issues
def _review_targets(ctx: QualityGateContext) -> set[str]:
targets = {str(node.get("id")) for node in ctx.plan_nodes if node.get("id")}
for row in ctx.upstream:
content = _content(row)
if content.get("section_id"):
targets.add(str(content["section_id"]))
if row.get("node_id"):
targets.add(str(row["node_id"]))
if ctx.node_id:
targets.add(ctx.node_id)
return targets
def _looks_like_section(target: str) -> bool:
return bool(re.search(r"(第.+章|chapter|section|ch\d+|章节)", target, re.I))
def _lint_citations(markdown: str, cited: set[str], ctx: QualityGateContext) -> list[GateIssue]:
issues: list[GateIssue] = []
allowed = verified_claim_ids(ctx.upstream)
key_facts = [
str(claim.get("claim_id"))
for row in ctx.upstream
if row.get("artifact_type") == "EvidenceBundle" and row.get("validation_status") == "validated"
for claim in (_content(row).get("claims") or [])
if claim.get("kind") == "fact" and _needs_unit(str(claim.get("text") or ""))
]
for claim_id in key_facts:
if claim_id in allowed and claim_id not in cited and claim_id in markdown:
# mentioned in prose without evidence_ids — still require explicit cite
issues.append(GateIssue("uncited_key_fact", f"关键数字主张 {claim_id} 未进入引用映射", claim_id))
elif claim_id in allowed and claim_id not in cited:
issues.append(GateIssue("uncited_key_fact", f"关键数字主张 {claim_id} 未被章节引用", claim_id))
stale = []
cutoff_year = _cutoff_year(ctx)
for row in ctx.upstream:
if row.get("artifact_type") != "EvidenceBundle":
continue
for source in _content(row).get("sources") or []:
year = _year_of(str(source.get("published_at") or ""))
if cutoff_year and year and year < cutoff_year:
stale.append(str(source.get("source_id") or source.get("title")))
if stale:
issues.append(GateIssue("stale_source", f"来源过期:{', '.join(stale[:5])}", None))
return issues
def _coverage_against_requirement(markdown: str, ctx: QualityGateContext) -> list[GateIssue]:
if ctx.requirement is None:
return []
text = markdown or ""
missing = [angle for angle in ctx.requirement.required_angles if angle and angle not in text]
return [GateIssue("coverage_gap", f"正文未覆盖必选角度 {angle}", angle) for angle in missing]
def _plan_has_verifier(ctx: QualityGateContext) -> bool:
return any(str(node.get("role_key") or "") == "verifier" or node.get("output_artifact_type") == "VerificationResult" for node in ctx.plan_nodes)
def _mentions(bundle: EvidenceBundle, angle: str) -> bool:
blob = " ".join([claim.text for claim in bundle.claims] + [src.title for src in bundle.sources] + list(bundle.coverage_gaps))
return angle in blob
def _needs_unit(text: str) -> bool:
for match in _QUANTITY.finditer(text):
number, unit = match.group(1), (match.group(2) or "").strip()
if _YEAR.fullmatch(number):
continue
if len(number) == 4 and number.startswith(("19", "20")):
continue
if unit in {"%", "%", "个百分点", "万", "亿", "万亿", "倍"}:
return True
# bare statistic like "份额 25" still needs 口径
if any(token in text for token in ("份额", "增速", "销量", "营收", "利润", "占比", "规模")):
return True
return False
def _conflict_pairs(claims: list[EvidenceClaim]) -> list[tuple[str, str]]:
facts = [claim for claim in claims if claim.kind == "fact"]
pairs: list[tuple[str, str]] = []
for index, left in enumerate(facts):
qty_l = _quantities(left.text)
tokens_l = _tokens(left.text)
for right in facts[index + 1 :]:
if left.scope and right.scope and left.scope != right.scope:
continue
qty_r = _quantities(right.text)
if not qty_l or not qty_r:
continue
overlap = tokens_l & _tokens(right.text)
if len(overlap) < 1:
continue
if qty_l != qty_r:
pairs.append((left.claim_id, right.claim_id))
return pairs
def _quantities(text: str) -> set[tuple[str, str]]:
found: set[tuple[str, str]] = set()
for match in _QUANTITY.finditer(text):
number, unit = match.group(1), (match.group(2) or "").strip()
if _YEAR.fullmatch(number) or (len(number) == 4 and number.startswith(("19", "20"))):
continue
found.add((number, unit))
return found
def _tokens(text: str) -> set[str]:
cleaned = _QUANTITY.sub(" ", text)
parts = re.split(r"[\s,。;、,/]+", cleaned)
return {part for part in parts if len(part) >= 2 and part not in _STOP}
def _cutoff_year(ctx: QualityGateContext) -> int | None:
text = (ctx.requirement.time_range if ctx.requirement else None) or ""
years = [int(match.group(0)) for match in re.finditer(r"(19|20)\d{2}", text)]
return min(years) if years else None
def _year_of(value: str) -> int | None:
match = re.search(r"(19|20)\d{2}", value or "")
return int(match.group(0)) if match else None
@@ -0,0 +1,402 @@
"""Deterministic Verifier / Analyst / Writer / Reviewer / Reviser members.
These roles run as TaskLedger members (``TaskResult``), not as AgentScope Team
schedulers. Real ``reply_stream`` / ``web_search`` stay out of this ticket.
"""
from __future__ import annotations
import re
from typing import Any
from app.report_collaboration.execution.ledger import TaskAssignment, TaskResult
from app.report_collaboration.execution.member_runner import ScriptedMemberKernel
from app.report_collaboration.execution.quality_gate import QualityGateContext, conflicting_claim_ids, contested_claim_ids, requirement_from_session_record, verified_claim_ids
from deerflow.persistence.report_collaboration.base import ReportCollaborationStore
from deerflow.persistence.report_collaboration.codec import iso_now
_YEAR = re.compile(r"(19|20)\d{2}")
class QualityRoleKernel:
"""Auto-builds typed artifacts from upstream board rows.
Optional ``scripts`` / ``enqueue`` still win, so tests can inject a stale
bundle or a first-round ``revise`` without replacing the rest of the chain.
"""
def __init__(self, store: ReportCollaborationStore, scripts: dict[str, list[TaskResult]] | None = None) -> None:
self._store = store
self._scripts = ScriptedMemberKernel(scripts)
self.calls: list[str] = self._scripts.calls
def enqueue(self, node_id: str, *results: TaskResult) -> None:
self._scripts.enqueue(node_id, *results)
async def run(self, assignment: TaskAssignment, *, context: dict[str, Any]) -> TaskResult:
queue = self._scripts._scripts.get(assignment.node_id) or self._scripts._scripts.get(assignment.role_key)
if queue:
return await self._scripts.run(assignment, context=context)
self.calls.append(assignment.node_id)
artifacts = await self._store.list_artifacts_full(assignment.run_id)
session = await self._store.get_session_record(assignment.session_id)
run = await self._store.get_run(assignment.run_id)
plan = await self._store.get_plan(str((run or {}).get("plan_id") or ""))
requirement = requirement_from_session_record(session)
ctx = QualityGateContext(
requirement=requirement,
upstream=artifacts,
plan_nodes=list((plan or {}).get("nodes") or []),
node_id=assignment.node_id,
role_key=assignment.role_key,
angle=assignment.angle,
)
role = assignment.role_key
if role == "researcher":
return self._research(assignment, ctx)
if role == "verifier":
return self._verify(assignment, ctx)
if role == "analyst":
return self._analyze(assignment, ctx)
if role in {"writer", "reviser"}:
return self._write(assignment, ctx)
if role == "reviewer":
return self._review(assignment, ctx)
raise AssertionError(f"no quality-role kernel for {assignment.node_id} role {role}")
def _research(self, assignment: TaskAssignment, ctx: QualityGateContext) -> TaskResult:
angles = list(assignment.angle and [assignment.angle] or [])
if ctx.requirement:
for angle in ctx.requirement.required_angles:
if angle and angle not in angles:
angles.append(angle)
if not angles:
angles = ["综合趋势"]
year = _fresh_year(ctx)
claims = []
sources = []
for index, angle in enumerate(angles, start=1):
claim_id = f"c_{assignment.node_id}_{index}"
source_id = f"src_{assignment.node_id}_{index}"
claims.append(
{
"claim_id": claim_id,
"text": f"{angle} 在 {year} 年保持可核验进展",
"kind": "fact",
"source_ids": [source_id],
"excerpt": f"{angle} 进展",
"published_at": f"{year}-06-01",
"unit": None,
"scope": angle,
}
)
sources.append(
{
"source_id": source_id,
"title": f"{angle} 公开月报",
"excerpt": f"{angle} 进展",
"published_at": f"{year}-06-01",
}
)
overlay = _overlay_text(assignment)
if overlay and claims:
claims[0]["text"] = f"{claims[0]['text']}(已按用户要求:{overlay})"
draft = {"schema_version": 1, "claims": claims, "sources": sources, "conflicts": [], "coverage_gaps": []}
return TaskResult(
kind="artifact_draft",
artifact_type="EvidenceBundle",
artifact_draft=draft,
reply_text=f"已覆盖角度:{'、'.join(angles)}。",
)
def _verify(self, assignment: TaskAssignment, ctx: QualityGateContext) -> TaskResult:
claims = _evidence_claims(ctx.upstream)
if not claims:
return TaskResult(kind="repair_request", repair_reason="empty_output", reply_text="上游没有可核验主张。")
cutoff = _cutoff_year(ctx)
conflicted = _conflicted_ids(ctx.upstream)
drafts: list[dict[str, Any]] = []
for claim in claims:
source_ids = [str(item) for item in (claim.get("source_ids") or [])]
stale = _stale_sources_for(claim, ctx.upstream, cutoff)
if stale:
verdict = "stale"
freshness = f"早于 {cutoff}"
conflicts = [f"{claim['claim_id']} 来源过期:{', '.join(stale)}"]
opposing = source_ids
supporting: list[str] = []
conclusion = f"{claim['claim_id']} 资料过期,不能作为可用结论"
elif claim["claim_id"] in conflicted:
verdict = "contested"
freshness = None
peer = next((item for item in conflicted if item != claim["claim_id"]), claim["claim_id"])
conflicts = [f"{claim['claim_id']} 与 {peer} 数字冲突"]
opposing = source_ids
supporting = []
conclusion = f"{claim['claim_id']} 存在冲突口径,禁止下游选用"
else:
verdict = "supported"
freshness = None
conflicts = []
opposing = []
supporting = source_ids
conclusion = str(claim.get("text") or claim["claim_id"])
drafts.append(
{
"schema_version": 1,
"claim_id": claim["claim_id"],
"supporting_source_ids": supporting,
"opposing_source_ids": opposing,
"conflicts": conflicts,
"freshness": freshness,
"independent_sources": len(source_ids) > 1,
"usable_conclusion": conclusion,
"verdict": verdict,
}
)
primary, extra = drafts[0], drafts[1:]
return TaskResult(
kind="artifact_draft",
artifact_type="VerificationResult",
artifact_draft=primary,
additional_drafts=[{"artifact_type": "VerificationResult", "draft": item} for item in extra],
reply_text=f"核验 {len(drafts)} 条主张。",
)
def _analyze(self, assignment: TaskAssignment, ctx: QualityGateContext) -> TaskResult:
allowed = verified_claim_ids(ctx.upstream)
contested = contested_claim_ids(ctx.upstream)
usable = [claim_id for claim_id in allowed if claim_id not in contested]
missing = _missing_angles(ctx)
research_ids = _nodes_with_role(ctx, "researcher") or _upstream_node_ids(ctx)
if missing:
return TaskResult(
kind="repair_request",
repair_reason="coverage_gap",
repair_target_node_ids=research_ids,
reopen_downstream=True,
reply_text=f"缺失角度:{'、'.join(missing)},定向补充检索。",
)
if not usable:
return TaskResult(
kind="repair_request",
repair_reason="unverified_sources",
repair_target_node_ids=research_ids,
reopen_downstream=True,
reply_text="没有已核验主张,定向补充检索。",
)
claims = [claim for claim in _evidence_claims(ctx.upstream) if claim.get("claim_id") in usable]
angle = assignment.angle or (ctx.requirement.required_angles[0] if ctx.requirement and ctx.requirement.required_angles else "综合")
facts = [str(claim.get("text") or claim["claim_id"]) for claim in claims]
overlay = _overlay_text(assignment)
draft = {
"schema_version": 1,
"angle": angle,
"thesis": f"基于已核验主张,{angle} 可形成判断。",
"evidence_ids": [str(claim["claim_id"]) for claim in claims],
"facts": facts,
"inferences": [f"{angle} 仍受公开口径限制"] + ([f"已按用户要求重新审视:{overlay}"] if overlay else []),
"assumptions": ["公开月报口径稳定"],
"limitations": ["未覆盖未核验主张"],
"gaps": [],
}
return TaskResult(kind="artifact_draft", artifact_type="AngleAnalysis", artifact_draft=draft, reply_text=f"完成「{angle}」分析。")
def _write(self, assignment: TaskAssignment, ctx: QualityGateContext) -> TaskResult:
allowed = [claim_id for claim_id in verified_claim_ids(ctx.upstream) if claim_id not in contested_claim_ids(ctx.upstream)]
if not allowed:
return TaskResult(kind="repair_request", repair_reason="unverified_sources", reply_text="没有可写入的已核验主张。")
claims = [claim for claim in _evidence_claims(ctx.upstream) if claim.get("claim_id") in set(allowed)]
angles = list((ctx.requirement.required_angles if ctx.requirement else []) or [])
review = _latest_review(ctx.upstream)
fix = ""
if review and review.get("verdict") == "revise":
issues = review.get("issues") or []
fix = ";".join(str(item.get("requirement") or "") for item in issues if item.get("requirement"))
body_bits = [str(claim.get("text") or "") for claim in claims]
if angles:
body_bits.extend(angles)
if fix:
body_bits.append(f"已按审稿意见修订:{fix}")
overlay = _overlay_text(assignment)
if overlay:
body_bits.append(f"已按用户要求调整:{overlay}")
markdown = "。".join(part for part in body_bits if part) + f"。引用 {' '.join(allowed)}。"
section_id = "overview"
draft: dict[str, Any] = {
"schema_version": 1,
"section_id": section_id,
"title": assignment.label or "报告",
"markdown": markdown,
"evidence_ids": allowed,
"claim_citation_map": {str(claim.get("text") or claim["claim_id"]): [str(claim["claim_id"])] for claim in claims},
}
expected = assignment.expected_artifact_type or "ReportSectionDraft"
if expected == "ReportVersion":
now = iso_now()
draft = {
"id": f"rv_{assignment.node_run_id}",
"session_id": assignment.session_id,
"version": assignment.attempt,
"parent_version_id": None,
"change_type": "revision" if fix else "initial",
"change_summary": fix or (f"按用户要求调整:{overlay}" if overlay else "首稿"),
"markdown": markdown,
"source_index": [
{"id": sid, "title": sid, "url": None, "published_at": None, "added_at": now, "agent_run_id": None}
for sid in allowed
],
"created_at": now,
"is_head": True,
}
return TaskResult(kind="artifact_draft", artifact_type=expected, artifact_draft=draft, reply_text="已提交章节草稿。" if not fix else "已按审稿意见定向修订。")
def _review(self, assignment: TaskAssignment, ctx: QualityGateContext) -> TaskResult:
write_nodes = _nodes_with_role(ctx, "writer") + _nodes_with_role(ctx, "reviser")
target = write_nodes[0] if write_nodes else "write"
drafts = [row for row in ctx.upstream if row.get("artifact_type") in {"ReportSectionDraft", "ReportVersion"} and row.get("validation_status") == "validated"]
if not drafts:
return TaskResult(
kind="artifact_draft",
artifact_type="ReviewDecision",
artifact_draft={
"schema_version": 1,
"verdict": "revise",
"issues": [
{
"severity": "high",
"target": target,
"requirement": "补写带引用的报告正文",
"evidence": "写作节点没有 validated 草稿",
}
],
},
reply_text="审稿要求补写正文。",
)
missing = _missing_angles(ctx, text=_draft_text(drafts))
if missing:
return TaskResult(
kind="artifact_draft",
artifact_type="ReviewDecision",
artifact_draft={
"schema_version": 1,
"verdict": "revise",
"issues": [
{
"severity": "high",
"target": target,
"requirement": f"正文补上必选角度 {'、'.join(missing)},不要重新检索",
"evidence": f"当前草稿未覆盖 {missing[0]}",
}
],
},
reply_text=f"审稿未通过,只返工 {target}。",
)
return TaskResult(
kind="artifact_draft",
artifact_type="ReviewDecision",
artifact_draft={"schema_version": 1, "verdict": "pass", "issues": []},
reply_text="审稿通过。",
)
def _evidence_claims(upstream: list[dict[str, Any]]) -> list[dict[str, Any]]:
claims: list[dict[str, Any]] = []
for row in upstream:
if row.get("artifact_type") != "EvidenceBundle" or row.get("validation_status") != "validated":
continue
if row.get("superseded_by"):
continue
content = row.get("content") if isinstance(row.get("content"), dict) else {}
for claim in content.get("claims") or []:
if claim.get("claim_id"):
claims.append(claim)
return claims
def _conflicted_ids(upstream: list[dict[str, Any]]) -> set[str]:
return set(contested_claim_ids(upstream)) | conflicting_claim_ids(upstream)
def _stale_sources_for(claim: dict[str, Any], upstream: list[dict[str, Any]], cutoff: int | None) -> list[str]:
if cutoff is None:
return []
wanted = set(claim.get("source_ids") or [])
stale: list[str] = []
for row in upstream:
if row.get("artifact_type") != "EvidenceBundle":
continue
content = row.get("content") if isinstance(row.get("content"), dict) else {}
for source in content.get("sources") or []:
sid = str(source.get("source_id") or "")
if sid not in wanted:
continue
year = _year_of(str(source.get("published_at") or ""))
if year is not None and year < cutoff:
stale.append(sid)
return stale
def _missing_angles(ctx: QualityGateContext, text: str | None = None) -> list[str]:
if ctx.requirement is None:
return []
blob = text if text is not None else " ".join(str(claim.get("text") or "") for claim in _evidence_claims(ctx.upstream))
return [angle for angle in ctx.requirement.required_angles if angle and angle not in blob]
def _draft_text(rows: list[dict[str, Any]]) -> str:
parts: list[str] = []
for row in rows:
content = row.get("content") if isinstance(row.get("content"), dict) else {}
parts.append(str(content.get("markdown") or ""))
return " ".join(parts)
def _latest_review(upstream: list[dict[str, Any]]) -> dict[str, Any] | None:
reviews = [
row.get("content")
for row in upstream
if row.get("artifact_type") == "ReviewDecision" and isinstance(row.get("content"), dict)
]
return reviews[-1] if reviews else None
def _nodes_with_role(ctx: QualityGateContext, role_key: str) -> list[str]:
return [str(node.get("id")) for node in ctx.plan_nodes if str(node.get("role_key") or "") == role_key and node.get("id")]
def _upstream_node_ids(ctx: QualityGateContext) -> list[str]:
ids: list[str] = []
for row in ctx.upstream:
node_id = str(row.get("node_id") or "")
if node_id and node_id not in ids:
ids.append(node_id)
return ids
def _cutoff_year(ctx: QualityGateContext) -> int | None:
text = (ctx.requirement.time_range if ctx.requirement else None) or ""
years = [int(match.group(0)) for match in _YEAR.finditer(text)]
return min(years) if years else None
def _fresh_year(ctx: QualityGateContext) -> int:
cutoff = _cutoff_year(ctx)
return cutoff if cutoff else 2026
def _year_of(value: str) -> int | None:
match = _YEAR.search(value or "")
return int(match.group(0)) if match else None
def _overlay_text(assignment: TaskAssignment) -> str:
instructions = [
str(item.get("instruction") or "").strip()
for item in assignment.command_overlays
if isinstance(item, dict) and str(item.get("instruction") or "").strip()
]
return ";".join(instructions[-3:])[:600]
__all__ = ["QualityRoleKernel"]
@@ -0,0 +1,157 @@
"""Crash recovery: interrupt leftover attempts; keep validated work."""
from __future__ import annotations
from dataclasses import dataclass, field
from typing import Any
from app.report_collaboration.contracts.node_machine import require_transition
from deerflow.persistence.report_collaboration.base import ReportCollaborationStore
from deerflow.persistence.report_collaboration.codec import iso_now, make_node_run_id
_ORPHAN_TO_INTERRUPTED = frozenset({"queued", "running"})
_ORPHAN_TO_SUPERSEDED = frozenset({"validating"})
@dataclass
class RecoveryReport:
interrupted_node_run_ids: list[str] = field(default_factory=list)
new_attempt_ids: list[str] = field(default_factory=list)
preserved_completed: list[str] = field(default_factory=list)
def _max_attempts(node: dict[str, Any], spec: dict[str, Any] | None) -> int:
contract = node.get("contract_json") if isinstance(node.get("contract_json"), dict) else {}
return int(contract.get("max_attempts") or (spec or {}).get("max_attempts") or 3)
async def recover_orphaned_attempts(store: ReportCollaborationStore, run_id: str) -> RecoveryReport:
"""Mark leftover in-flight attempts and open a new planned attempt when allowed.
Completed nodes and ``awaiting_input`` pauses are left untouched so a
takeover does not re-search finished work or drop a human question.
"""
run = await store.get_run(run_id)
if run is None:
raise KeyError(run_id)
plan = await store.get_plan(str(run.get("plan_id") or ""))
specs = {str(item.get("id")): item for item in (plan or {}).get("nodes") or [] if item.get("id")}
nodes = await store.list_node_runs(run_id)
latest: dict[str, dict[str, Any]] = {}
for item in nodes:
current = latest.get(item["node_id"])
if current is None or int(item["attempt"]) >= int(current["attempt"]):
latest[item["node_id"]] = item
report = RecoveryReport()
for node_id, node in latest.items():
status = str(node.get("status") or "")
if status == "completed":
report.preserved_completed.append(str(node["node_run_id"]))
continue
if status == "awaiting_input":
continue
if status in _ORPHAN_TO_INTERRUPTED:
require_transition(status, "interrupted")
node["status"] = "interrupted"
elif status in _ORPHAN_TO_SUPERSEDED:
require_transition(status, "superseded")
node["status"] = "superseded"
else:
continue
node["ended_at"] = iso_now()
node["error"] = node.get("error") or "lease_reclaimed"
await store.save_node_run(node)
report.interrupted_node_run_ids.append(str(node["node_run_id"]))
await store.append_event(
session_id=str(run["session_id"]),
run_id=run_id,
event_type="node.status.changed",
data={"node_id": node_id, "node_run_id": node["node_run_id"], "status": node["status"], "recovered": True},
)
await _maybe_open_next_attempt(store, run, node, specs.get(node_id), report)
return report
async def cancel_in_flight_nodes(store: ReportCollaborationStore, run_id: str) -> list[str]:
"""Best-effort cancel leftover work after ``finalize_cancel``."""
run = await store.get_run(run_id)
if run is None:
return []
nodes = await store.list_node_runs(run_id)
latest: dict[str, dict[str, Any]] = {}
for item in nodes:
current = latest.get(item["node_id"])
if current is None or int(item["attempt"]) >= int(current["attempt"]):
latest[item["node_id"]] = item
changed: list[str] = []
for node in latest.values():
status = str(node.get("status") or "")
target: str | None = None
if status in {"planned", "queued", "awaiting_input"}:
target = "cancelled"
elif status == "running":
require_transition("running", "cancel_requested")
node["status"] = "cancel_requested"
await store.save_node_run(node)
target = "cancelled"
elif status in {"validating", "interrupted", "failed"}:
target = "superseded"
elif status == "cancel_requested":
target = "cancelled"
if target is None:
continue
require_transition(node["status"], target)
node["status"] = target
node["ended_at"] = iso_now()
await store.save_node_run(node)
changed.append(str(node["node_run_id"]))
await store.append_event(
session_id=str(run["session_id"]),
run_id=run_id,
event_type="node.status.changed",
data={"node_id": node["node_id"], "node_run_id": node["node_run_id"], "status": target, "cancelled": True},
)
return changed
async def _maybe_open_next_attempt(
store: ReportCollaborationStore,
run: dict[str, Any],
node: dict[str, Any],
spec: dict[str, Any] | None,
report: RecoveryReport,
) -> None:
attempt = int(node.get("attempt") or 1)
if attempt >= _max_attempts(node, spec):
return
nxt = attempt + 1
node_run_id = make_node_run_id(str(run["id"]), str(node["node_id"]), nxt)
await store.save_node_run(
{
"node_run_id": node_run_id,
"session_id": run["session_id"],
"run_id": run["id"],
"node_id": node["node_id"],
"attempt": nxt,
"status": "planned",
"label": node.get("label") or node["node_id"],
"role_display_name": node.get("role_display_name"),
"angle": node.get("angle"),
"contract_json": node.get("contract_json"),
"input_artifact_ids": list(node.get("input_artifact_ids") or []),
"command_overlay_revision": node.get("command_overlay_revision") or 0,
"agent_snapshot": node.get("agent_snapshot"),
"error": None,
"started_at": None,
"ended_at": None,
}
)
report.new_attempt_ids.append(node_run_id)
await store.append_event(
session_id=str(run["session_id"]),
run_id=str(run["id"]),
event_type="node.attempt.created",
data={"node_id": node["node_id"], "node_run_id": node_run_id, "attempt": nxt},
)
@@ -0,0 +1,104 @@
"""Minimal schema gate for RC-BE-009.
Claim-level QualityGate (coverage, conflicts, citations) stays in RC-BE-010.
This gate only decides whether a TaskResult draft is a typed artifact the
ledger may mark ``validated``. Empty output and illegal JSON become repair.
"""
from __future__ import annotations
import json
from typing import Any
from pydantic import BaseModel, ValidationError
from app.report_collaboration.contracts.artifacts import (
AngleAnalysis,
CoverageMatrix,
EvidenceBundle,
ReportSectionDraft,
ReviewDecision,
SynthesisOutline,
VerificationResult,
)
from app.report_collaboration.contracts.reports import ReportVersion
_SCHEMA: dict[str, type[BaseModel]] = {
"EvidenceBundle": EvidenceBundle,
"VerificationResult": VerificationResult,
"AngleAnalysis": AngleAnalysis,
"SynthesisOutline": SynthesisOutline,
"ReportSectionDraft": ReportSectionDraft,
"ReviewDecision": ReviewDecision,
"CoverageMatrix": CoverageMatrix,
"ReportVersion": ReportVersion,
}
class SchemaGateResult:
def __init__(self, *, ok: bool, reason: str | None = None, parsed: dict[str, Any] | None = None) -> None:
self.ok = ok
self.reason = reason
self.parsed = parsed or {}
def _loads_draft(draft: Any) -> tuple[dict[str, Any] | None, str | None]:
if draft is None:
return None, "empty_output"
if isinstance(draft, str):
text = draft.strip()
if not text:
return None, "empty_output"
try:
parsed = json.loads(text)
except json.JSONDecodeError:
return None, "illegal_json"
draft = parsed
if not isinstance(draft, dict):
return None, "illegal_json"
if not draft:
return None, "empty_output"
return draft, None
def validate_artifact_draft(artifact_type: str, draft: Any) -> SchemaGateResult:
"""Return whether ``draft`` may become a validated artifact of ``artifact_type``."""
payload, reason = _loads_draft(draft)
if payload is None:
return SchemaGateResult(ok=False, reason=reason or "empty_output")
model = _SCHEMA.get(artifact_type)
if model is None:
return SchemaGateResult(ok=False, reason="unknown_artifact_type")
try:
parsed = model.model_validate(payload)
except ValidationError:
return SchemaGateResult(ok=False, reason="schema_mismatch")
dumped = parsed.model_dump(mode="json")
extra = _semantic_reject(artifact_type, parsed)
if extra:
return SchemaGateResult(ok=False, reason=extra, parsed=dumped)
return SchemaGateResult(ok=True, parsed=dumped)
def _semantic_reject(artifact_type: str, parsed: BaseModel) -> str | None:
if artifact_type == "EvidenceBundle":
bundle = parsed
assert isinstance(bundle, EvidenceBundle)
if not bundle.claims:
return "empty_output"
if any(not claim.source_ids for claim in bundle.claims):
return "missing_sources"
if artifact_type == "ReportSectionDraft":
draft = parsed
assert isinstance(draft, ReportSectionDraft)
if not (draft.markdown or "").strip():
return "empty_output"
if not draft.evidence_ids:
return "missing_sources"
if artifact_type == "ReportVersion":
version = parsed
assert isinstance(version, ReportVersion)
if not (version.markdown or "").strip():
return "empty_output"
return None