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

server/services/acceptance_service.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import hashlib
+import re
+
+from map_types.enums import AcceptanceType
+
+from server.domain.schemas import AcceptanceStatusRead
+from server.services.errors import StateTransitionError
+from server.services.evidence_service import metadata_has_completion_evidence
+
+_ACCEPTANCE_MARKER_RE = re.compile(
+    r"\[acceptance_type:\s*(?P<kind>[a-zA-Z_]+)\]",
+    re.IGNORECASE,
+)
+_ACCEPTANCE_ITEM_RE = re.compile(
+    r"^\s*(?:[-*]|\d+[.)])\s*"
+    r"\[acceptance_type:\s*(?P<kind>[a-zA-Z_]+)\]\s*"
+    r"(?P<description>.+?)\s*$",
+    re.IGNORECASE,
+)
+
+
+def parse_acceptance_status(
+    content_md: str, *, completion_metadata: dict | None = None
+) -> list[AcceptanceStatusRead]:
+    statuses: list[AcceptanceStatusRead] = []
+    has_generic_evidence = metadata_has_completion_evidence(completion_metadata)
+    for line in content_md.splitlines():
+        match = _ACCEPTANCE_ITEM_RE.match(line)
+        if match is None:
+            continue
+        raw_kind = match.group("kind").lower()
+        try:
+            acceptance_type = AcceptanceType(raw_kind)
+        except ValueError as exc:
+            allowed = ", ".join(item.value for item in AcceptanceType)
+            raise StateTransitionError(
+                f"Unknown acceptance_type {raw_kind!r}; allowed values: {allowed}"
+            ) from exc
+        description = " ".join(match.group("description").split())
+        acceptance_id = _stable_acceptance_id(acceptance_type.value, description)
+        statuses.append(
+            AcceptanceStatusRead(
+                id=acceptance_id,
+                description=description,
+                acceptance_type=acceptance_type,
+                evidence_provided=has_generic_evidence
+                or _metadata_has_acceptance_evidence(
+                    completion_metadata,
+                    acceptance_id=acceptance_id,
+                    acceptance_type=acceptance_type.value,
+                    description=description,
+                ),
+                reviewer_verdict=None,
+            )
+        )
+    return statuses
+
+
+def _stable_acceptance_id(acceptance_type: str, description: str) -> str:
+    digest = hashlib.sha1(f"{acceptance_type}:{description}".encode()).hexdigest()
+    return f"acc-{digest[:12]}"
+
+
+def _metadata_has_acceptance_evidence(
+    metadata: object, *, acceptance_id: str, acceptance_type: str, description: str
+) -> bool:
+    if not isinstance(metadata, dict):
+        return False
+    acceptance = metadata.get("acceptance")
+    if isinstance(acceptance, dict):
+        for key in (acceptance_id, acceptance_type, description):
+            value = acceptance.get(key)
+            if value not in (None, "", [], {}, False):
+                return True
+    if isinstance(acceptance, list):
+        for item in acceptance:
+            if not isinstance(item, dict):
+                continue
+            evidence = item.get("evidence") or item.get("evidence_provided")
+            if evidence in (None, "", [], {}, False):
+                continue
+            if (
+                item.get("id") == acceptance_id
+                or item.get("acceptance_type") == acceptance_type
+                or item.get("description") == description
+            ):
+                return True
+    return False

server/services/action_item_migration_service.py

@@ -0,0 +1,190 @@
+"""Migrate or deliver open action items tied to closed/archived topics."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+
+from sqlalchemy import or_, select
+from sqlalchemy.orm import Session, joinedload
+
+from server.domain.models import AuditLog, Topic, TopicActionItem, TopicActionItemStatus, TopicStatus
+from server.services import audit_service, topic_service
+
+
+@dataclass(frozen=True)
+class MigrationResult:
+    action_item_id: uuid.UUID
+    strategy: str
+    from_topic_id: uuid.UUID
+    to_topic_id: uuid.UUID | None
+    dry_run: bool
+    skipped: bool
+    reason: str | None = None
+
+
+def _idempotency_key(item_id: uuid.UUID) -> str:
+    return f"action_item_migrate:{item_id}"
+
+
+def migration_already_applied(db: Session, item_id: uuid.UUID) -> bool:
+    key = _idempotency_key(item_id)
+    rows = db.scalars(
+        select(AuditLog).where(
+            AuditLog.action == "action_item.migrated",
+            AuditLog.target_id == item_id,
+        )
+    ).all()
+    return any((row.payload_json or {}).get("idempotency_key") == key for row in rows)
+
+
+def list_stale_open_action_items(db: Session) -> list[TopicActionItem]:
+    """Open items whose source topic is closed or archived (not soft-deleted)."""
+    return list(
+        db.scalars(
+            select(TopicActionItem)
+            .join(Topic, TopicActionItem.topic_id == Topic.id)
+            .options(joinedload(TopicActionItem.topic))
+            .where(
+                TopicActionItem.status == TopicActionItemStatus.open,
+                Topic.deleted_at.is_(None),
+                or_(
+                    Topic.status == TopicStatus.closed,
+                    Topic.archived_at.isnot(None),
+                ),
+            )
+            .order_by(TopicActionItem.updated_at.desc())
+        )
+    )
+
+
+def migrate_action_item(
+    db: Session,
+    item: TopicActionItem,
+    *,
+    migrate_to_topic_id: uuid.UUID | None = None,
+    agent_id: uuid.UUID | None = None,
+    dry_run: bool = False,
+) -> MigrationResult:
+    from_topic_id = item.topic_id
+    if migration_already_applied(db, item.id):
+        return MigrationResult(
+            action_item_id=item.id,
+            strategy="skip",
+            from_topic_id=from_topic_id,
+            to_topic_id=None,
+            dry_run=dry_run,
+            skipped=True,
+            reason="already_migrated",
+        )
+
+    if migrate_to_topic_id is not None:
+        target = db.get(Topic, migrate_to_topic_id)
+        if target is None or target.deleted_at is not None:
+            raise ValueError(f"Target topic {migrate_to_topic_id} not found")
+        strategy = "migrate_to"
+        to_topic_id = migrate_to_topic_id
+        if not dry_run:
+            item.topic_id = migrate_to_topic_id
+            audit_service.log_no_commit(
+                db,
+                action="action_item.migrated",
+                target_type="topic_action_item",
+                target_id=item.id,
+                agent_id=agent_id,
+                project_id=item.project_id,
+                summary=f"迁移行动项「{item.title}」到新话题",
+                payload={
+                    "idempotency_key": _idempotency_key(item.id),
+                    "from_topic_id": str(from_topic_id),
+                    "to_topic_id": str(to_topic_id),
+                    "strategy": strategy,
+                },
+            )
+            db.commit()
+        return MigrationResult(
+            action_item_id=item.id,
+            strategy=strategy,
+            from_topic_id=from_topic_id,
+            to_topic_id=to_topic_id,
+            dry_run=dry_run,
+            skipped=False,
+        )
+
+    strategy = "cascade_backlog"
+    if not dry_run:
+        suggested_id, _ = topic_service._suggest_linked_experiment(db, item)
+        if suggested_id is not None:
+            item.linked_experiment_id = suggested_id
+        topic_service.deliver_action_item_no_commit(
+            db,
+            item,
+            triggered_by="migration:cascade_backlog",
+        )
+        audit_service.log_no_commit(
+            db,
+            action="action_item.migrated",
+            target_type="topic_action_item",
+            target_id=item.id,
+            agent_id=agent_id,
+            project_id=item.project_id,
+            summary=f"迁移关闭行动项「{item.title}」（cascade backlog）",
+            payload={
+                "idempotency_key": _idempotency_key(item.id),
+                "from_topic_id": str(from_topic_id),
+                "to_topic_id": None,
+                "strategy": strategy,
+                "linked_experiment_id": str(item.linked_experiment_id)
+                if item.linked_experiment_id
+                else None,
+            },
+        )
+        db.commit()
+    return MigrationResult(
+        action_item_id=item.id,
+        strategy=strategy,
+        from_topic_id=from_topic_id,
+        to_topic_id=None,
+        dry_run=dry_run,
+        skipped=False,
+    )
+
+
+def migrate_stale_open_action_items(
+    db: Session,
+    *,
+    migrate_to_topic_id: uuid.UUID | None = None,
+    agent_id: uuid.UUID | None = None,
+    dry_run: bool = False,
+) -> list[MigrationResult]:
+    results: list[MigrationResult] = []
+    for item in list_stale_open_action_items(db):
+        try:
+            results.append(
+                migrate_action_item(
+                    db,
+                    item,
+                    migrate_to_topic_id=migrate_to_topic_id,
+                    agent_id=agent_id,
+                    dry_run=dry_run,
+                )
+            )
+        except Exception as exc:
+            if not dry_run:
+                db.rollback()
+                audit_service.log(
+                    db,
+                    action="action_item.migration_failed",
+                    target_type="topic_action_item",
+                    target_id=item.id,
+                    agent_id=agent_id,
+                    project_id=item.project_id,
+                    summary=f"迁移行动项失败「{item.title}」",
+                    payload={
+                        "action_item_id": str(item.id),
+                        "from_topic_id": str(item.topic_id),
+                        "error": str(exc),
+                    },
+                )
+            raise
+    return results

server/services/action_item_service.py

@@ -0,0 +1,200 @@
+"""Action-item wake / stale lifecycle helpers (experiment B, plan §3).
+
+This module owns the *transaction-internal* mutations that the runtime-waker
+needs to advance the three-stage escalation timeline:
+
+- ``mark_wake_sent_no_commit``: bump ``wake_count``, stamp ``last_woken_at``,
+  emit the ``action_item.wake_sent`` audit row — all in the caller's tx.
+- ``mark_stale_no_commit``: stamp ``stale_at``, emit the ``action_item.stale``
+  audit row — all in the caller's tx.
+
+Public ``mark_wake_sent`` / ``mark_stale`` wrappers add lookup + commit for
+direct callers (API, dogfood scripts). The ``_no_commit`` variants are what
+the waker should call from its own session.
+
+Why a separate service module instead of inlining into ``topic_service.py``:
+the waker has its own import surface (no FastAPI deps, no project_status
+recursion) and the topic module is already 700+ lines. Splitting keeps the
+mutation contract co-located with its audit helpers and the I3 acceptance
+tests.
+
+Related plan sections:
+- §1  audit event ``action_item.stale`` payload schema
+- §2  ``first_open_at`` / ``last_woken_at`` / ``stale_at`` lifecycle
+- §3  waker scan / stale trigger
+- §4  clock-skew policy: every timestamp is server time, never client time
+- §8  B-1..B-13 acceptance — these helpers back B-2..B-7, B-11
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+
+from sqlalchemy.orm import Session
+
+from server.domain.models import TopicActionItem
+from server.services import audit_service
+
+# Wake-history window from plan §3. Mirrored here so service-level callers
+# (admin scripts, dogfood) can introspect the same numbers the waker uses
+# without re-parsing the plan markdown.
+WAKE_STAGE_THRESHOLDS: tuple[tuple[int, int], ...] = (
+    # (wake_count_after_increment, minimum_hours_since_first_open)
+    (1, 24),   # T+24h  first wake
+    (2, 72),   # T+72h  second wake
+)
+WAKE_REPEAT_INTERVAL_DAYS = 7  # after the 72h wake, fire every 7d
+WAKE_MAX_COUNT_BEFORE_STALE = 4  # 4th unanswered wake -> stale
+
+
+def _utcnow() -> datetime:
+    """Return the waker-canonical ``datetime.now(UTC)``.
+
+    Centralised so tests can monkey-patch the service module rather than
+    chasing ``datetime.now`` through every call site (plan §4 clock-skew
+    requirement: only server time, never client time).
+    """
+    return datetime.now(UTC)
+
+
+def _ensure_first_open_at(item: TopicActionItem, now: datetime) -> None:
+    """Stamp ``first_open_at`` on the first transition into ``open``.
+
+    Per plan §2: ``first_open_at`` is written when an item enters the ``open``
+    status (creation, or reopen from ``done``/``cancelled``). Re-triggering
+    a wake on an already-open item must NOT reset this — the T+24h / T+72h
+    window is anchored to the moment the item first became open.
+
+    The backfill for already-open rows is handled by alembic migration
+    ``027_topic_action_item_escalation_fields.py`` — this helper only sets
+    the timestamp when it's still null.
+    """
+    if item.status.value == "open" and item.first_open_at is None:
+        item.first_open_at = now
+
+
+def mark_wake_sent_no_commit(
+    db: Session,
+    *,
+    item: TopicActionItem,
+    now: datetime | None = None,
+) -> int:
+    """Bump ``wake_count`` + stamp ``last_woken_at`` + audit row, no commit.
+
+    Caller is responsible for the final ``db.commit()``. Returns the new
+    ``wake_count`` so the waker can decide whether to advance to ``stale``
+    on the next cycle (returns 1..4; values beyond ``WAKE_MAX_COUNT_BEFORE_STALE``
+    mean the waker is calling this too aggressively and the caller should
+    pivot to ``mark_stale_no_commit`` instead).
+
+    Invariants (plan §3 + §4):
+      - Only fires when ``status == open`` and ``owner_agent_id`` is set;
+        ``wake_count`` is meaningless on closed items.
+      - ``last_woken_at`` and the audit row's ``last_woken_at`` field both
+        use the same ``now`` value (caller-supplied or server-time default)
+        so grep-side reconstruction matches the DB.
+      - First call also writes ``first_open_at`` if it's still null — this
+        covers the I1 contract that backfill only handles pre-existing rows.
+    """
+    if item.status.value != "open":
+        raise ValueError(
+            f"mark_wake_sent requires status=open, got {item.status.value}"
+        )
+    if item.owner_agent_id is None:
+        raise ValueError(
+            "mark_wake_sent requires owner_agent_id — "
+            "waker only wakes the assignee"
+        )
+
+    when = now or _utcnow()
+    _ensure_first_open_at(item, when)
+    item.wake_count = (item.wake_count or 0) + 1
+    item.last_woken_at = when
+
+    audit_service.log_action_item_wake_sent(db, item=item, now=when)
+    return item.wake_count
+
+
+def mark_stale_no_commit(
+    db: Session,
+    *,
+    item: TopicActionItem,
+    now: datetime | None = None,
+    admin_notified: bool = True,
+    creator_audit_only: bool = True,
+) -> None:
+    """Stamp ``stale_at`` + write the diagnostic audit row, no commit.
+
+    Idempotent: if ``stale_at`` is already set we skip re-writing (the audit
+    row is a one-shot diagnostic — repeat wakes after stale must not spam
+    audit). Caller still owns the commit boundary.
+
+    Validation is delegated to ``audit_service._log_action_item_stale_no_commit``
+    which rejects unassigned items, items with no prior wake, and
+    ``stale_after_attempt < 1``. We pass ``stale_after_attempt=item.wake_count``
+    because the plan defines stale as "the 4th unanswered wake" — the count
+    after the increment.
+    """
+    if item.status.value != "open":
+        raise ValueError(
+            f"mark_stale requires status=open, got {item.status.value}"
+        )
+
+    if item.stale_at is not None:
+        return  # already stale — plan §5: do not re-write diagnostic
+
+    when = now or _utcnow()
+    item.stale_at = when
+
+    audit_service._log_action_item_stale_no_commit(
+        db,
+        item=item,
+        stale_after_attempt=item.wake_count,
+        admin_notified=admin_notified,
+        creator_audit_only=creator_audit_only,
+    )
+
+
+def mark_wake_sent(
+    db: Session,
+    action_item_id: uuid.UUID,
+    *,
+    now: datetime | None = None,
+) -> TopicActionItem:
+    """Public wrapper: lookup + ``mark_wake_sent_no_commit`` + commit.
+
+    Kept for API symmetry with ``complete_action_item`` / ``cancel_action_item``.
+    The waker itself should call the ``_no_commit`` variant directly.
+    """
+    item = db.get(TopicActionItem, action_item_id)
+    if item is None:
+        raise LookupError(f"action item {action_item_id} not found")
+    mark_wake_sent_no_commit(db, item=item, now=now)
+    db.commit()
+    db.refresh(item)
+    return item
+
+
+def mark_stale(
+    db: Session,
+    action_item_id: uuid.UUID,
+    *,
+    now: datetime | None = None,
+    admin_notified: bool = True,
+    creator_audit_only: bool = True,
+) -> TopicActionItem:
+    """Public wrapper: lookup + ``mark_stale_no_commit`` + commit."""
+    item = db.get(TopicActionItem, action_item_id)
+    if item is None:
+        raise LookupError(f"action item {action_item_id} not found")
+    mark_stale_no_commit(
+        db,
+        item=item,
+        now=now,
+        admin_notified=admin_notified,
+        creator_audit_only=creator_audit_only,
+    )
+    db.commit()
+    db.refresh(item)
+    return item