multi-agent-platform 0.1.0__py3-none-any.whl

server/services/agent_work_service.py

@@ -0,0 +1,405 @@
+"""Unified agent work snapshot (whoami + topic-progress + todos + wakeable notifications)."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Iterable
+from datetime import datetime
+
+from map_types.enums import AgentRole, NotificationCategory
+from sqlalchemy.orm import Session
+
+from server.domain.models import Agent
+from server.domain.schemas import (
+    AgentRead,
+    AgentWorkRead,
+    AgentWorkSummaryRead,
+    BucketVisibility,
+    NotificationListRead,
+    NotificationRead,
+    SummaryBucket,
+    SummaryBucketItem,
+    SummaryBucketKind,
+)
+from server.services import notification_service, todo_service, topic_progress_service
+from server.services import project_service as svc
+from server.services import topic_work_item_service as work_items
+from server.services.notification_service import PERSONA_AGENT_NAMES
+
+_BUCKET_KIND_VISIBILITY: dict[SummaryBucketKind, BucketVisibility] = {
+    "mention": "all",
+    "round_ack": "all",
+    "pending_reply": "all",
+    "explicit_only": "host_only",
+    "informational_only": "host_only",
+    "action_items": "host_only",
+}
+
+
+def _is_host_persona(agent: Agent) -> bool:
+    """A persona 'sees host-only buckets' when they are the host (admin
+    always sees everything).
+    """
+    if agent.role == AgentRole.admin:
+        return True
+    host_name = PERSONA_AGENT_NAMES.get("host", "")
+    return bool(host_name) and agent.name == host_name
+
+
+def _make_item(*, kind: SummaryBucketKind, topic_id=None, topic_title=None, excerpt=None, updated_at=None) -> SummaryBucketItem:
+    return SummaryBucketItem(
+        kind=kind, topic_id=topic_id, topic_title=topic_title, excerpt=excerpt, updated_at=updated_at
+    )
+
+
+def _bucket(
+    *,
+    kind: SummaryBucketKind,
+    items: Iterable[SummaryBucketItem],
+    top_excerpt: str | None = None,
+) -> SummaryBucket:
+    items = list(items)
+    return SummaryBucket(
+        kind=kind,
+        count=len(items),
+        visibility=_BUCKET_KIND_VISIBILITY[kind],
+        items=items[:5],
+        top_excerpt=top_excerpt or (items[0].excerpt if items else None),
+    )
+
+
+def get_agent_work(
+    db: Session,
+    agent: Agent,
+    *,
+    notification_limit: int = 50,
+    notification_category: NotificationCategory | None = NotificationCategory.wakeable,
+) -> AgentWorkRead:
+    project_key: str | None = None
+    if agent.project_id is not None:
+        project_key = svc.get_project(db, agent.project_id).project_key
+
+    agent_read = AgentRead(
+        id=agent.id,
+        name=agent.name,
+        role=agent.role,
+        project_id=agent.project_id,
+        project_key=project_key,
+        created_at=agent.created_at,
+    )
+
+    bundle = work_items.topic_work_items_bundle_for_agent(db, agent)
+    todos = todo_service.get_todos(db, agent, bundle=bundle)
+    topic_progress = topic_progress_service.list_topic_progress_for_agent(
+        db, agent, bundle=bundle
+    )
+
+    notif_items, notif_total = notification_service.list_for_agent(
+        db,
+        agent,
+        unread_only=True,
+        category=notification_category,
+        limit=notification_limit,
+        offset=0,
+    )
+    unread_count = notification_service.count_unread(
+        db,
+        agent,
+        category=notification_category,
+    )
+    notifications = NotificationListRead(
+        items=[NotificationRead.model_validate(n) for n in notif_items],
+        total=notif_total,
+        unread_count=unread_count,
+    )
+
+    return AgentWorkRead(
+        agent=agent_read,
+        topic_progress=topic_progress,
+        todos=todos,
+        notifications=notifications,
+    )
+
+
+def get_agent_work_summary(
+    db: Session,
+    agent: Agent,
+    *,
+    include_all_personas: bool = False,
+    topics_limit: int = 10,
+    experiments_limit: int = 5,
+) -> AgentWorkSummaryRead:
+    """Compact 6-bucket by_kind summary of the agent's work.
+
+    Buckets: mention, round_ack, pending_reply, explicit_only,
+    informational_only, action_items. Persona filtering drops host-only
+    buckets for non-host personas unless ``include_all_personas=True``.
+    Truncation caps how many topics / experiments contribute per bucket to
+    keep the summary card small.
+    """
+    project_key: str | None = None
+    if agent.project_id is not None:
+        project_key = svc.get_project(db, agent.project_id).project_key
+    agent_read = AgentRead(
+        id=agent.id,
+        name=agent.name,
+        role=agent.role,
+        project_id=agent.project_id,
+        project_key=project_key,
+        created_at=agent.created_at,
+    )
+
+    bundle = work_items.topic_work_items_bundle_for_agent(db, agent)
+    todos = todo_service.get_todos(db, agent, bundle=bundle)
+    items = bundle.items
+
+    bucket_items: dict[SummaryBucketKind, list[SummaryBucketItem]] = defaultdict(list)
+
+    # topic-derived work items (mention / round_ack / pending_reply)
+    for w in items:
+        if w.kind == "mention":
+            bucket_items["mention"].append(
+                _make_item(
+                    kind="mention",
+                    topic_id=w.topic_id,
+                    topic_title=w.topic_title,
+                    excerpt=w.excerpt,
+                    updated_at=w.created_at,
+                )
+            )
+        elif w.kind == "round_ack":
+            bucket_items["round_ack"].append(
+                _make_item(
+                    kind="round_ack",
+                    topic_id=w.topic_id,
+                    topic_title=w.topic_title,
+                    excerpt=w.excerpt,
+                    updated_at=w.created_at,
+                )
+            )
+        elif w.kind == "pending_topic_reply":
+            bucket_items["pending_reply"].append(
+                _make_item(
+                    kind="pending_reply",
+                    topic_id=w.topic_id,
+                    topic_title=w.topic_title,
+                    excerpt=w.excerpt,
+                    updated_at=w.created_at,
+                )
+            )
+
+    # mentions that didn't come through topic work items (experiment-scope)
+    topic_mention_ids = {w.topic_id for w in items if w.kind == "mention"}
+    for m in todos.mentions:
+        if m.topic_id is None or m.topic_id in topic_mention_ids:
+            continue
+        bucket_items["mention"].append(
+            _make_item(
+                kind="mention",
+                topic_id=m.topic_id,
+                excerpt=m.excerpt,
+                updated_at=m.created_at,
+            )
+        )
+
+    # round_ack todo mirror
+    for r in todos.pending_round_acks:
+        bucket_items["round_ack"].append(
+            _make_item(
+                kind="round_ack",
+                topic_id=r.topic_id,
+                topic_title=r.topic_title,
+                excerpt=r.summary_excerpt,
+                updated_at=r.updated_at,
+            )
+        )
+
+    # pending_reply todo mirror
+    for reply in todos.pending_topic_replies:
+        bucket_items["pending_reply"].append(
+            _make_item(
+                kind="pending_reply",
+                topic_id=reply.topic_id,
+                topic_title=reply.topic_title,
+                excerpt=reply.excerpt,
+                updated_at=reply.created_at,
+            )
+        )
+
+    # explicit_only: host's lifecycle action items (visible only on host persona
+    # by default; persona filter applies below).
+    #
+    # f873c287 I1(f) partition boundary: ``informational_only`` experiments
+    # (phase_owner != host, actions=[], blocked_on is set) do NOT enter
+    # the obligation partition (``explicit_only``); they route to
+    # ``informational_only`` so the waker treats them as read-only noise.
+    #
+    # f873c287 I1(e): both bucket excerpts share the ``experiment:{phase}:
+    # {phase_owner}`` shape so the by_owner breakdown algorithm below can
+    # count them uniformly.
+    for e in todos.my_open_experiments:
+        owner_value = e.phase_owner.value
+        phase_value = e.phase.value
+        if getattr(e, "informational_only", False):
+            bucket_items["informational_only"].append(
+                _make_item(
+                    kind="informational_only",
+                    topic_id=None,
+                    topic_title=e.title,
+                    excerpt=(
+                        f"experiment:{phase_value}:{owner_value}"
+                        f":blocked={e.blocked_on}"
+                        if e.blocked_on
+                        else f"experiment:{phase_value}:{owner_value}:waiting"
+                    ),
+                    updated_at=e.updated_at,
+                )
+            )
+            continue
+        bucket_items["explicit_only"].append(
+            _make_item(
+                kind="explicit_only",
+                topic_id=None,
+                topic_title=e.title,
+                excerpt=f"experiment:{phase_value}:{owner_value}",
+                updated_at=e.updated_at,
+            )
+        )
+    for p in todos.pending_advance_rounds:
+        bucket_items["explicit_only"].append(
+            _make_item(
+                kind="explicit_only",
+                topic_id=p.topic_id,
+                topic_title=p.topic_title,
+                excerpt=f"advance_round:{p.discussion_round.value}",
+                updated_at=p.updated_at,
+            )
+        )
+    for pending in todos.pending_replies:
+        bucket_items["explicit_only"].append(
+            _make_item(
+                kind="explicit_only",
+                topic_id=pending.experiment_id,
+                topic_title=pending.experiment_title,
+                excerpt=f"pending_reply:{pending.status.value}",
+                updated_at=pending.updated_at,
+            )
+        )
+
+    # informational_only: read-only review lifecycle (host can dismiss; non-host sees as informational)
+    for e in todos.pending_result_reviews:
+        bucket_items["informational_only"].append(
+            _make_item(
+                kind="informational_only",
+                topic_id=None,
+                topic_title=e.title,
+                excerpt=f"result_review:{e.phase.value}",
+                updated_at=e.updated_at,
+            )
+        )
+    for informational in todos.experiment_review_informational:
+        bucket_items["informational_only"].append(
+            _make_item(
+                kind="informational_only",
+                topic_id=None,
+                topic_title=informational.experiment_title,
+                excerpt=informational.review_progress,
+                updated_at=informational.updated_at,
+            )
+        )
+
+    # action_items
+    for a in todos.action_items:
+        bucket_items["action_items"].append(
+            _make_item(
+                kind="action_items",
+                topic_id=a.topic_id,
+                topic_title=a.topic_title,
+                excerpt=a.title,
+                updated_at=a.updated_at,
+            )
+        )
+
+    # Apply truncation per bucket: keep top-N by updated_at desc.
+    truncated_by_bucket: dict[str, int] = {}
+    for kind, blist in bucket_items.items():
+        blist.sort(key=lambda it: it.updated_at or datetime.min, reverse=True)
+        cap = topics_limit if kind != "explicit_only" else experiments_limit
+        if len(blist) > cap:
+            truncated_by_bucket[kind] = len(blist) - cap
+            del blist[cap:]
+
+    # f873c287 I1(e): compute the per-phase_owner experiment counter BEFORE
+    # the persona filter so the host can see "3 are mine, 2 are waiting on
+    # reviewer" at a glance. The ``host`` key is dropped after the filter
+    # below because the underlying bucket is host_only.
+    #
+    # Counts BOTH explicit_only and informational_only items; both share
+    # the ``experiment:{phase}:{owner}[:...]`` excerpt format. We use
+    # maxsplit=3 so informational_only entries (which append ``:blocked=``
+    # or ``:waiting``) keep the owner as a clean segment.
+    experiments_needing_attention_by_owner: dict[str, int] = {}
+    for kind in ("explicit_only", "informational_only"):
+        for it in bucket_items.get(kind, []):
+            if not it.excerpt or not it.excerpt.startswith("experiment:"):
+                continue
+            parts = it.excerpt.split(":", maxsplit=3)
+            if len(parts) < 3:
+                continue
+            owner = parts[2].strip()
+            if not owner:
+                continue
+            experiments_needing_attention_by_owner[owner] = (
+                experiments_needing_attention_by_owner.get(owner, 0) + 1
+            )
+
+    # Apply persona filter: non-host loses host_only buckets unless --include-all-personas.
+    is_host = _is_host_persona(agent)
+    visibility_filter_applied = not (include_all_personas or is_host)
+    if visibility_filter_applied:
+        bucket_items = {
+            k: v for k, v in bucket_items.items() if _BUCKET_KIND_VISIBILITY[k] == "all"
+        }
+        # f873c287 I1(e): participant/reviewer personas don't see
+        # host-owned experiments in the breakdown either — the
+        # ``explicit_only`` bucket is host_only.
+        experiments_needing_attention_by_owner.pop("host", None)
+
+    buckets = [
+        _bucket(kind=kind, items=items_)
+        for kind, items_ in bucket_items.items()
+    ]
+
+    # Topics needing attention = unique topics that contributed to all / round_ack / pending_reply.
+    topics_with_action_items = {
+        it.topic_id
+        for kind, items_ in bucket_items.items()
+        if kind in {"mention", "round_ack", "pending_reply"}
+        for it in items_
+        if it.topic_id is not None
+    }
+    topics_needing_attention = len(topics_with_action_items)
+
+    experiments_needing_attention = sum(
+        experiments_needing_attention_by_owner.values()
+    )
+
+    topics_truncated = sum(
+        n for kind, n in truncated_by_bucket.items() if kind != "explicit_only"
+    )
+    experiments_truncated = sum(
+        n for kind, n in truncated_by_bucket.items() if kind == "explicit_only"
+    )
+
+    return AgentWorkSummaryRead(
+        agent=agent_read,
+        buckets=buckets,
+        topics_needing_attention=topics_needing_attention,
+        experiments_needing_attention=experiments_needing_attention,
+        experiments_needing_attention_by_owner=experiments_needing_attention_by_owner,
+        topics_truncated=topics_truncated,
+        experiments_truncated=experiments_truncated,
+        visibility_filter_applied=visibility_filter_applied,
+        topics_limit=topics_limit,
+        experiments_limit=experiments_limit,
+    )

server/services/archive_lint_service.py

@@ -0,0 +1,156 @@
+"""a764abf6 I1.(b) — archive metadata lint helper.
+
+Surfaces consistency problems with the ``review.archived_at`` /
+``review.archived_reason`` metadata so drift between the auto-archive
+cascade (I1(b)) and the default filter (I1(c)) becomes observable.
+
+Two checks per plan (b):
+
+* **检测 1 — archived review 一致性**: archived reviews must NOT appear
+  in the default ``list_reviews(include_archived=False)`` output.
+
+  - ``N=2_transition`` phase (``include_archived`` 默认 True 过渡期,
+    before release checklist flip): leaked archived review is
+    ``WARN`` only (existing prod tests rely on the default and we do
+    not want to fail mid-flight).
+  - ``N=2_post_flip`` phase (``include_archived`` 默认 False,
+    after release checklist flip): leaked archived review is
+    ``FAIL`` (the new contract is violated).
+
+* **检测 2 — plan_version drift**: every archived review's
+  ``plan_version`` must be less than ``experiment.current_plan_version``.
+  Drift (archived review referencing a plan that is still canonical)
+  is always ``FAIL`` regardless of N=2 phase.
+
+Output: list of :class:`ArchiveLintIssue` with ``code``,
+``severity`` (``WARN`` / ``FAIL``), ``message``, and references to the
+``review_id`` / ``plan_version`` involved.
+
+The CLI / API wrapper passes ``n2_phase`` explicitly based on the
+release checklist; this helper does not infer it from live prod data
+(``list_reviews(include_archived=...)`` defaults are not introspectable
+from the service layer without a deliberate API probe).
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Literal
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from server.domain.models import Review
+from server.services.project_service import get_experiment
+from server.services.review_service import list_reviews  # re-export for test monkey-patch
+
+ArchiveLintCode = Literal[
+    "ARCHIVED_IN_DEFAULT_LIST",
+    "ARCHIVED_PLAN_VERSION_DRIFT",
+]
+
+ArchiveLintSeverity = Literal["WARN", "FAIL"]
+
+ArchiveLintN2Phase = Literal["transition", "post_flip"]
+
+
+@dataclass(frozen=True)
+class ArchiveLintIssue:
+    code: ArchiveLintCode
+    severity: ArchiveLintSeverity
+    message: str
+    review_id: uuid.UUID | None = None
+    plan_version: int | None = None
+
+
+@dataclass(frozen=True)
+class ArchiveLintResult:
+    issues: list[ArchiveLintIssue] = field(default_factory=list)
+    n2_phase: ArchiveLintN2Phase = "post_flip"
+    reviews_total: int = 0
+    reviews_archived: int = 0
+
+    @property
+    def has_failures(self) -> bool:
+        return any(issue.severity == "FAIL" for issue in self.issues)
+
+    @property
+    def has_warnings(self) -> bool:
+        return any(issue.severity == "WARN" for issue in self.issues)
+
+
+def archive_lint(
+    db: Session,
+    experiment_id: uuid.UUID,
+    *,
+    n2_phase: ArchiveLintN2Phase = "post_flip",
+) -> ArchiveLintResult:
+    """Lint helper — returns all ``ArchiveLintIssue``s found.
+
+    Implementation steps:
+
+    1. Pull all reviews (archived + non-archived).
+    2. Pull ``list_reviews(include_archived=False)`` to model the default
+       filter exactly as the API exposes it.
+    3. 检测 1 — diff the two sets: any review that is archived but
+       appears in the default list is an inconsistency. Severity depends
+       on the supplied ``n2_phase``.
+    4. 检测 2 — for every archived review, assert
+       ``review.plan_version < experiment.current_plan_version``.
+       Drift ⇒ ``FAIL``.
+    """
+    experiment = get_experiment(db, experiment_id)
+    all_reviews = list(
+        db.scalars(select(Review).where(Review.experiment_id == experiment_id))
+    )
+    default_list = list_reviews(db, experiment_id, include_archived=False)
+    default_ids = {r.id for r in default_list}
+
+    issues: list[ArchiveLintIssue] = []
+    archived = [r for r in all_reviews if r.archived_at is not None]
+
+    # 检测 1: archived review leaked into default list.
+    severity_for_drift: ArchiveLintSeverity = (
+        "WARN" if n2_phase == "transition" else "FAIL"
+    )
+    for review in archived:
+        if review.id in default_ids:
+            issues.append(
+                ArchiveLintIssue(
+                    code="ARCHIVED_IN_DEFAULT_LIST",
+                    severity=severity_for_drift,
+                    message=(
+                        f"Review {review.id} is archived but appears in "
+                        f"list_reviews(include_archived=False) default "
+                        f"output (N=2 phase={n2_phase})"
+                    ),
+                    review_id=review.id,
+                    plan_version=review.plan_version,
+                )
+            )
+
+    # 检测 2: archived review's plan_version must be < current_plan_version.
+    for review in archived:
+        if review.plan_version >= experiment.current_plan_version:
+            issues.append(
+                ArchiveLintIssue(
+                    code="ARCHIVED_PLAN_VERSION_DRIFT",
+                    severity="FAIL",
+                    message=(
+                        f"Archived review {review.id} references "
+                        f"plan_version={review.plan_version} but "
+                        f"experiment.current_plan_version="
+                        f"{experiment.current_plan_version}"
+                    ),
+                    review_id=review.id,
+                    plan_version=review.plan_version,
+                )
+            )
+
+    return ArchiveLintResult(
+        issues=issues,
+        n2_phase=n2_phase,
+        reviews_total=len(all_reviews),
+        reviews_archived=len(archived),
+    )