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

server/domain/schemas.py

@@ -0,0 +1,3 @@
+"""Backward-compatible re-exports; prefer `map_types` in SDK/MCP code."""
+
+from map_types.schemas import *  # noqa: F403

server/domain/state_machine.py

@@ -0,0 +1,79 @@
+from dataclasses import dataclass
+
+from server.domain.models import ExperimentPhase, ReviewItem, ReviewItemStatus
+
+
+class StateMachineError(Exception):
+    pass
+
+
+TERMINAL_PHASES = frozenset({ExperimentPhase.done, ExperimentPhase.cancelled})
+
+
+@dataclass
+class ReviewItemTransitionContext:
+    is_creator: bool
+    is_reviewer: bool
+    is_admin: bool
+    via_plan_revision: bool = False
+
+
+def validate_phase_transition(current: ExperimentPhase, target: ExperimentPhase) -> None:
+    allowed: dict[ExperimentPhase, set[ExperimentPhase]] = {
+        ExperimentPhase.draft: {ExperimentPhase.review, ExperimentPhase.cancelled},
+        ExperimentPhase.review: {
+            ExperimentPhase.approved,
+            ExperimentPhase.draft,
+            ExperimentPhase.cancelled,
+        },
+        ExperimentPhase.approved: {ExperimentPhase.running, ExperimentPhase.cancelled},
+        ExperimentPhase.running: {ExperimentPhase.result_review, ExperimentPhase.cancelled},
+        ExperimentPhase.result_review: {
+            ExperimentPhase.done,
+            ExperimentPhase.running,
+            ExperimentPhase.cancelled,
+        },
+        ExperimentPhase.done: set(),
+        ExperimentPhase.cancelled: set(),
+    }
+    if current in TERMINAL_PHASES:
+        raise StateMachineError(f"Cannot transition from terminal phase '{current.value}'")
+    if target not in allowed.get(current, set()):
+        raise StateMachineError(f"Invalid phase transition: {current.value} -> {target.value}")
+
+
+def validate_review_item_transition(
+    current: ReviewItemStatus,
+    target: ReviewItemStatus,
+    ctx: ReviewItemTransitionContext,
+) -> None:
+    transitions: dict[tuple[ReviewItemStatus, ReviewItemStatus], callable] = {
+        (ReviewItemStatus.open, ReviewItemStatus.addressed): lambda c: c.via_plan_revision,
+        (ReviewItemStatus.open, ReviewItemStatus.rebutted): lambda c: c.is_creator,
+        (ReviewItemStatus.open, ReviewItemStatus.withdrawn): lambda c: c.is_reviewer,
+        (ReviewItemStatus.open, ReviewItemStatus.escalated): lambda c: c.is_reviewer or c.is_admin,
+        (ReviewItemStatus.addressed, ReviewItemStatus.resolved): lambda c: c.is_reviewer,
+        (ReviewItemStatus.addressed, ReviewItemStatus.open): lambda c: c.is_reviewer,
+        (ReviewItemStatus.rebutted, ReviewItemStatus.resolved): lambda c: c.is_reviewer,
+        (ReviewItemStatus.rebutted, ReviewItemStatus.open): lambda c: c.is_reviewer,
+        (ReviewItemStatus.escalated, ReviewItemStatus.resolved): lambda c: c.is_reviewer or c.is_admin,
+    }
+    key = (current, target)
+    if key not in transitions:
+        raise StateMachineError(f"Invalid review item transition: {current.value} -> {target.value}")
+    if not transitions[key](ctx):
+        raise StateMachineError("Actor is not allowed to perform this review item transition")
+
+
+def count_open_unreasonable(unreasonable_items: list[ReviewItem]) -> int:
+    return sum(
+        1
+        for item in unreasonable_items
+        if item.status
+        in (
+            ReviewItemStatus.open,
+            ReviewItemStatus.addressed,
+            ReviewItemStatus.rebutted,
+            ReviewItemStatus.escalated,
+        )
+    )

server/domain/topic_ack_constants.py

@@ -0,0 +1,9 @@
+"""Constants for topic advance-round participant acknowledgement."""
+
+from datetime import timedelta
+
+ADVANCE_ROUND_ACK_TIMEOUT = timedelta(hours=24)
+
+ACK_ACCEPT_MARKER = "map:ack=accept"
+ACK_REJECT_MARKER = "map:ack=reject"
+ACK_DISMISS_MARKER = "map:ack=dismiss"

server/main.py

@@ -0,0 +1,148 @@
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+import uvicorn
+from fastapi import FastAPI, Request, status
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from server.__version__ import __version__
+from server.api.router import (
+    action_items_router,
+    agents_router,
+    audit_router,
+    experiments_router,
+    feedback_router,
+    notifications_router,
+    status_router,
+    topics_router,
+    webhooks_router,
+)
+from server.api.router import (
+    router as projects_router,
+)
+from server.config import get_settings
+from server.db.session import init_db
+from server.services.errors import (
+    BadRequestError,
+    ConflictError,
+    ForbiddenError,
+    NotFoundError,
+    StateTransitionError,
+    UnauthorizedError,
+)
+
+
+def register_domain_exception_handlers(app: FastAPI) -> None:
+    """集中把领域异常映射为 HTTP 响应。
+
+    取代过去在每个端点里手写的 ``try: ... except (...) as exc: raise http_error(exc)``
+    样板——端点现在只需让领域异常自然抛出，由本处理器统一翻译。
+    输出与原 ``http_error`` 完全一致：``{"detail": str(exc)}`` + 对应状态码。
+    """
+
+    mapping = {
+        NotFoundError: status.HTTP_404_NOT_FOUND,
+        UnauthorizedError: status.HTTP_401_UNAUTHORIZED,
+        ForbiddenError: status.HTTP_403_FORBIDDEN,
+        ConflictError: status.HTTP_409_CONFLICT,
+        BadRequestError: status.HTTP_400_BAD_REQUEST,
+        StateTransitionError: status.HTTP_422_UNPROCESSABLE_ENTITY,
+    }
+
+    def make_handler(code: int):
+        def handler(_request: Request, exc: Exception) -> JSONResponse:
+            content: dict[str, str] = {"detail": str(exc)}
+            reason = getattr(exc, "reason", None)
+            if isinstance(reason, str) and reason:
+                content["reason"] = reason
+            actor_id = getattr(exc, "actor_id", None)
+            if isinstance(actor_id, str) and actor_id:
+                content["actor_id"] = actor_id
+            experiment_id = getattr(exc, "experiment_id", None)
+            if isinstance(experiment_id, str) and experiment_id:
+                content["experiment_id"] = experiment_id
+            # State-machine errors may carry a stable subcode + remediation
+            # hint. Surface them so CLI / SDK callers can route on the
+            # failure mode instead of pattern-matching the human-readable
+            # ``detail`` string. Defaults are skipped so the response stays
+            # compact for ordinary state-machine refusals.
+            if isinstance(exc, StateTransitionError):
+                error_code = getattr(exc, "error_code", None)
+                if isinstance(error_code, str) and error_code:
+                    content["error_code"] = error_code
+                hint = getattr(exc, "hint", None)
+                if isinstance(hint, str) and hint:
+                    content["hint"] = hint
+                retryable = getattr(exc, "retryable", None)
+                if isinstance(retryable, bool):
+                    content["retryable"] = retryable
+            return JSONResponse(status_code=code, content=content)
+
+        return handler
+
+    for exc_type, code in mapping.items():
+        app.add_exception_handler(exc_type, make_handler(code))
+
+
+def create_app(*, init_db_on_startup: bool = True) -> FastAPI:
+    """Build the ASGI app.
+
+    Args:
+        init_db_on_startup: When ``True`` (default), the app runs
+            :func:`server.db.session.init_db` inside a FastAPI lifespan
+            handler so ``uvicorn server.main:app`` self-bootstraps the
+            schema. Tests pass ``False`` and inject a per-test session via
+            ``app.dependency_overrides``.
+    """
+    settings = get_settings()
+
+    @asynccontextmanager
+    async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
+        if init_db_on_startup:
+            init_db()
+        yield
+
+    app = FastAPI(
+        title="Multi-Agent Platform",
+        version=__version__,
+        lifespan=lifespan,
+    )
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.cors_origin_list,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+    prefix = settings.api_prefix
+    app.include_router(projects_router, prefix=prefix)
+    app.include_router(experiments_router, prefix=prefix)
+    app.include_router(agents_router, prefix=prefix)
+    app.include_router(notifications_router, prefix=prefix)
+    app.include_router(status_router, prefix=prefix)
+    app.include_router(topics_router, prefix=prefix)
+    app.include_router(webhooks_router, prefix=prefix)
+    app.include_router(audit_router, prefix=prefix)
+    app.include_router(feedback_router, prefix=prefix)
+    app.include_router(action_items_router, prefix=prefix)
+
+    register_domain_exception_handlers(app)
+
+    @app.get("/health")
+    def health() -> dict[str, str]:
+        return {"status": "ok"}
+
+    return app
+
+
+app = create_app()
+
+
+def run() -> None:
+    settings = get_settings()
+    uvicorn.run("server.main:app", host="0.0.0.0", port=settings.port, reload=settings.debug)
+
+
+if __name__ == "__main__":
+    run()

server/scripts/migrate_notification_unique.py

@@ -0,0 +1,231 @@
+"""Notification UNIQUE(recipient_agent_id, group_key) migration (race PR2).
+
+Independent script — does NOT go through alembic. The plan's rationale:
+``CREATE UNIQUE INDEX CONCURRENTLY`` cannot run inside a transaction, and
+alembic migrations are always wrapped in a transaction. This script
+therefore executes raw SQL against the live database.
+
+Usage
+-----
+    # dry-run: print plan, no DDL
+    python -m server.scripts.migrate_notification_unique --dry-run
+
+    # actually create the index
+    python -m server.scripts.migrate_notification_unique --execute
+
+    # idempotent: re-run safely (detects existing index)
+
+PG-only
+-------
+SQLite / MySQL are intentionally skipped because:
+
+* SQLite test/dev: the model's ``UniqueConstraint`` already enforces it
+  via ``create_all``; production SQLite is not in scope for race PR2.
+* MySQL: race PR2 is PG-only (per the topic-level scope and per
+  ``multi-waker 跨机器部署需 PG`` PRD note). MySQL would need a separate
+  ``ALTER TABLE ... ADD UNIQUE`` script.
+
+Pre-flight (data dedup)
+-----------------------
+The unique constraint assumes no duplicate ``(recipient, group_key)``
+pairs already exist. The plan's current production state should be
+clean (the application layer's select-then-insert was the only path),
+but a belt-and-braces dedup runs first: for each duplicate cluster,
+keep the row with the highest ``wake_version`` (or ``updated_at`` as
+tiebreaker) and delete the rest. The dedup log is printed so an
+operator can sanity-check the count.
+
+Failure handling
+----------------
+* ``CREATE UNIQUE INDEX CONCURRENTLY`` may leave an INVALID index if
+  the second attempt fails or is interrupted. The script ends with a
+  defensive ``DROP INDEX CONCURRENTLY IF EXISTS invalid_idx`` so the
+  table is not left carrying a bloat index that the planner won't use.
+* Re-runs are idempotent: existing-index detection skips the CREATE
+  and reports current row counts.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from sqlalchemy.engine import Connection, Engine
+
+logger = logging.getLogger("map.scripts.migrate_notification_unique")
+
+INDEX_NAME = "uq_notifications_recipient_group_key"
+
+
+def _is_pg(conn: Connection) -> bool:
+    return conn.dialect.name == "postgresql"
+
+
+def _index_exists(conn: Connection, table: str, index: str) -> bool:
+    rows = conn.exec_driver_sql(
+        "SELECT 1 FROM pg_indexes WHERE schemaname = current_schema() "
+        "AND tablename = %s AND indexname = %s",
+        (table, index),
+    ).first()
+    return rows is not None
+
+
+def _count_duplicates(conn: Connection) -> int:
+    """Return the number of duplicate (recipient_agent_id, group_key)
+    rows that the new unique index would reject. Zero is the target."""
+    rows = conn.exec_driver_sql(
+        sa.text(
+            "SELECT COUNT(*) FROM ("
+            "  SELECT recipient_agent_id, group_key, COUNT(*) AS n "
+            "  FROM notifications "
+            "  WHERE group_key IS NOT NULL "
+            "  GROUP BY recipient_agent_id, group_key HAVING COUNT(*) > 1"
+            ") d"
+        )
+    ).first()
+    return int(rows[0]) if rows else 0
+
+
+def _deduplicate(conn: Connection) -> int:
+    """Delete duplicate rows, keeping the most recently updated per
+    (recipient, group_key). Returns the number of rows deleted.
+    """
+    # Use a CTE: pick the keeper row (highest wake_version, then
+    # most-recent updated_at, then most-recent created_at), delete the
+    # rest. ctid is PG-specific but this script is PG-only.
+    sql = sa.text(
+        """
+        WITH ranked AS (
+          SELECT
+            ctid,
+            ROW_NUMBER() OVER (
+              PARTITION BY recipient_agent_id, group_key
+              ORDER BY wake_version DESC, updated_at DESC, created_at DESC
+            ) AS rn
+          FROM notifications
+          WHERE group_key IS NOT NULL
+        ),
+        deleted AS (
+          DELETE FROM notifications n
+          USING ranked r
+          WHERE n.ctid = r.ctid AND r.rn > 1
+          RETURNING n.id
+        )
+        SELECT COUNT(*) FROM deleted
+        """
+    )
+    rows = conn.exec_driver_sql(sql).first()
+    return int(rows[0]) if rows else 0
+
+
+def _create_index(conn: Connection) -> None:
+    # CONCURRENTLY cannot run in a transaction; the script is invoked
+    # outside any alembic revision for that reason.
+    conn.exec_driver_sql(
+        sa.text(
+            f"CREATE UNIQUE INDEX CONCURRENTLY IF NOT EXISTS {INDEX_NAME} "
+            f"ON notifications (recipient_agent_id, group_key) "
+            f"WHERE group_key IS NOT NULL"
+        )
+    )
+
+
+def _drop_invalid_index(conn: Connection) -> bool:
+    """If a prior failed run left an INVALID index, drop it.
+
+    Returns True if a stale invalid index was found and dropped.
+    """
+    rows = conn.exec_driver_sql(
+        sa.text(
+            "SELECT indexname FROM pg_indexes "
+            "WHERE schemaname = current_schema() AND tablename = 'notifications' "
+            "AND indexname LIKE %s"
+        ),
+        (f"%{INDEX_NAME}%",),
+    ).all()
+    names = [r[0] for r in rows]
+    dropped_any = False
+    for name in names:
+        # pg_index.indisvalid is False for indexes whose build failed.
+        invalid = conn.exec_driver_sql(
+            sa.text("SELECT indisvalid FROM pg_index WHERE indexname = :n"),
+            {"n": name},
+        ).first()
+        if invalid is not None and not invalid[0]:
+            conn.exec_driver_sql(
+                sa.text(f"DROP INDEX CONCURRENTLY IF EXISTS {sa.quoted_name(name, quote=True)}")
+            )
+            logger.warning("dropped invalid index notifications.%s", name)
+            dropped_any = True
+    return dropped_any
+
+
+def run(engine: Engine, *, dry_run: bool, execute: bool) -> int:
+    if not execute and not dry_run:
+        print("Nothing to do: pass --dry-run or --execute", file=sys.stderr)
+        return 2
+
+    with engine.begin() as conn:
+        if not _is_pg(conn):
+            print(
+                f"skip: dialect={conn.dialect.name!r} (PG-only script; "
+                f"SQLite/MySQL use the model's UniqueConstraint via create_all)",
+                file=sys.stderr,
+            )
+            return 0
+
+        if _index_exists(conn, "notifications", INDEX_NAME):
+            print(f"index notifications.{INDEX_NAME} already exists — nothing to do")
+            return 0
+
+        duplicates = _count_duplicates(conn)
+        if duplicates:
+            print(f"WARNING: {duplicates} duplicate (recipient, group_key) clusters exist")
+            if dry_run:
+                print("dry-run: would deduplicate then create index")
+                return 1
+            assert execute
+            deleted = _deduplicate(conn)
+            print(f"deduplicated {deleted} rows")
+        elif dry_run:
+            print("dry-run: no duplicates, would create index")
+            return 0
+
+        if execute:
+            _create_index(conn)
+            print(f"created index notifications.{INDEX_NAME}")
+            _drop_invalid_index(conn)
+            return 0
+        return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--dry-run", action="store_true", help="print plan only")
+    parser.add_argument("--execute", action="store_true", help="actually create the index")
+    parser.add_argument(
+        "--database-url",
+        default=None,
+        help="override MAP_DATABASE_URL (default: use the app's configured engine)",
+    )
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+
+    if args.database_url:
+        engine = sa.create_engine(args.database_url)
+    else:
+        from server.config import get_settings
+        from server.db.session import engine as app_engine
+
+        get_settings()  # validates env
+        engine = app_engine
+
+    return run(engine, dry_run=args.dry_run, execute=args.execute)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

server/scripts/purge_audit_pollution.py

@@ -0,0 +1,116 @@
+"""purge_audit_pollution — clean cross_persona_call audit rows that pre-date the capability gate.
+
+authz experiment (0e6926fa) PR2: before this PR, the
+``POST /experiments/{id}/cross-persona-call`` endpoint only enforced
+``ensure_experiment_access`` (project membership), which let any
+project member — including ``participant`` / ``reviewer`` personas —
+write audit rows. Those rows are now ``rejected=True`` + 403, but the
+historical rows pre-date the gate and need to be removed from the
+audit log so R6 metrics stop double-counting them.
+
+Usage::
+
+    # dry-run (default): count rows that would be deleted
+    python -m server.scripts.purge_audit_pollution
+
+    # actually delete
+    python -m server.scripts.purge_audit_pollution --apply
+
+    # scope to one project
+    python -m server.scripts.purge_audit_pollution --project-id <uuid> --apply
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import datetime
+from uuid import UUID
+
+from sqlalchemy import delete, select
+
+from server.db.session import SessionLocal
+from server.domain.models import Agent, AgentRole, AuditLog
+from server.services.audit_service import CROSS_PERSONA_CALL
+
+
+def _whitelist_agent_ids(db) -> set[UUID]:
+    """Agents allowed to call cross_persona_call: admin (any project) +
+    host persona (same project as the audit row)."""
+    admin_ids = set(
+        db.scalars(select(Agent.id).where(Agent.role == AgentRole.admin)).all()
+    )
+    host_ids = set(
+        db.scalars(
+            select(Agent.id).where(Agent.name == "multi-agent-platform-host")
+        ).all()
+    )
+    return admin_ids | host_ids
+
+
+def _polluted_row_ids(db, project_id: UUID | None) -> tuple[list[UUID], int]:
+    """Return (ids_to_purge, total_cross_persona_rows) for context."""
+    whitelist = _whitelist_agent_ids(db)
+    stmt = select(AuditLog.id, AuditLog.agent_id).where(
+        AuditLog.action == CROSS_PERSONA_CALL
+    )
+    if project_id is not None:
+        stmt = stmt.where(AuditLog.project_id == project_id)
+    polluted: list[UUID] = []
+    for row_id, agent_id in db.execute(stmt).all():
+        if agent_id not in whitelist:
+            polluted.append(row_id)
+    total = len(polluted)
+    return polluted, total
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    parser.add_argument(
+        "--apply",
+        action="store_true",
+        help="Actually delete rows. Default is dry-run (count only).",
+    )
+    parser.add_argument(
+        "--project-id",
+        type=UUID,
+        default=None,
+        help="Scope the purge to one project.",
+    )
+    args = parser.parse_args(argv)
+
+    db = SessionLocal()
+    try:
+        polluted, total = _polluted_row_ids(db, args.project_id)
+        ts = datetime.utcnow().isoformat(timespec="seconds")
+        if not args.apply:
+            print(
+                f"[dry-run {ts}] would delete {len(polluted)} polluted "
+                f"cross_persona_call audit rows (project_id={args.project_id or 'ALL'})"
+            )
+            return 0
+        if not polluted:
+            print(f"[apply {ts}] no polluted rows found")
+            return 0
+        # Delete in chunks to avoid huge single statements; SQLite
+        # parameter cap is 999, Postgres has none but the chunk keeps
+        # the transaction small.
+        CHUNK = 200
+        deleted = 0
+        for i in range(0, len(polluted), CHUNK):
+            chunk = polluted[i : i + CHUNK]
+            stmt = delete(AuditLog).where(AuditLog.id.in_(chunk))
+            result = db.execute(stmt)
+            deleted += result.rowcount or 0
+        db.commit()
+        print(
+            f"[apply {ts}] deleted {deleted} polluted cross_persona_call "
+            f"audit rows (project_id={args.project_id or 'ALL'})"
+        )
+        return 0
+    finally:
+        db.close()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

server/services/_lookups.py

@@ -0,0 +1,26 @@
+"""Project / experiment lookup helpers shared across services.
+
+从 ``project_service`` 抽出 ``get_project`` 以打破 ``project_service ↔ topic_service``
+循环 import：``topic_service`` 顶部需要 ``get_project`` 做存在性检查，而
+``project_service`` 顶部又 import ``topic_service`` 做聚合 read——双向顶部 import
+会导致 ``ImportError: cannot import name 'get_project' from partially initialized
+module``。把纯查询 helper 下沉到本无 service 依赖的模块后，``topic_service`` 不再
+需要在顶部 import ``project_service``。
+
+``project_service`` 仍 re-export ``get_project``，保持现有
+``from server.services.project_service import get_project`` 调用方不变。
+"""
+
+import uuid
+
+from sqlalchemy.orm import Session
+
+from server.domain.models import Project
+from server.services.errors import NotFoundError
+
+
+def get_project(db: Session, project_id: uuid.UUID) -> Project:
+    project = db.get(Project, project_id)
+    if project is None:
+        raise NotFoundError("Project not found")
+    return project