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

server/services/notification_stream.py

@@ -0,0 +1,138 @@
+"""In-process pub/sub for agent notification SSE streams.
+
+支持 ``Last-Event-ID`` 重连（P2 #9）：
+
+- 每个 agent 维护一个单调递增的 ``event_id``（从 1 开始），每个发布的
+  event 都带一个 id。
+- SSE frame 形如 ``id: {event_id}\\ndata: {json}\\n\\n``，浏览器
+  ``EventSource`` 会自动记录最后接收的 id，断线重连时通过
+  ``Last-Event-ID`` 请求头传回。
+- 服务端读取该 header，从 per-agent ring buffer 中 replay id 大于它的
+  事件，再进入正常的 pub/sub 循环。
+
+注意：本实现是 in-process（重启即丢），ring buffer 容量 200 条，覆盖
+常见的网络抖动断线重连场景。跨进程或重启场景需要持久化事件历史，
+那是后续 P3 的范围。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import threading
+import uuid
+from collections import deque
+from queue import Empty, Queue
+from typing import Any
+
+from fastapi.responses import StreamingResponse
+
+HEARTBEAT_SECONDS = 25
+# 每个 agent 保留最近多少条事件用于 Last-Event-ID replay。
+# 200 条对 wakeable 通知足够（远多于一次 remind 周期内的量），
+# 内存开销可控（每条 ~1KB JSON × 200 × N agents）。
+REPLAY_BUFFER_SIZE = 200
+
+_subscribers: dict[uuid.UUID, list[Queue[str]]] = {}
+# per-agent 单调事件 id 计数器 + ring buffer。
+# (next_id, [(event_id, payload_json), ...])
+_event_seqs: dict[uuid.UUID, int] = {}
+_replay_buffers: dict[uuid.UUID, deque[tuple[int, str]]] = {}
+_lock = threading.Lock()
+
+
+def subscribe(agent_id: uuid.UUID) -> Queue[str]:
+    queue: Queue[str] = Queue(maxsize=100)
+    with _lock:
+        _subscribers.setdefault(agent_id, []).append(queue)
+    return queue
+
+
+def unsubscribe(agent_id: uuid.UUID, queue: Queue[str]) -> None:
+    with _lock:
+        queues = _subscribers.get(agent_id)
+        if not queues:
+            return
+        try:
+            queues.remove(queue)
+        except ValueError:
+            return
+        if not queues:
+            _subscribers.pop(agent_id, None)
+
+
+def publish(agent_id: uuid.UUID, event: dict[str, Any]) -> None:
+    """发布一个事件，分配单调 id 并写入 per-agent ring buffer。
+
+    event dict 会被原样序列化（caller 看到的字段不变），SSE 层在 frame
+    外面套 ``id:`` 行；客户端解析时 ``event.id`` 即此 id。
+    """
+    payload = json.dumps(event, ensure_ascii=False)
+    with _lock:
+        _event_seqs[agent_id] = _event_seqs.get(agent_id, 0) + 1
+        event_id = _event_seqs[agent_id]
+        buf = _replay_buffers.setdefault(agent_id, deque(maxlen=REPLAY_BUFFER_SIZE))
+        buf.append((event_id, payload))
+        queues = list(_subscribers.get(agent_id, []))
+    frame = f"id: {event_id}\ndata: {payload}\n\n"
+    for queue in queues:
+        with contextlib.suppress(Exception):
+            queue.put_nowait(frame)
+
+
+def publish_many(agent_ids: list[uuid.UUID], event: dict[str, Any]) -> None:
+    for agent_id in agent_ids:
+        publish(agent_id, event)
+
+
+def _drain_replay(agent_id: uuid.UUID, last_event_id: int) -> list[str]:
+    """返回 agent 的 ring buffer 中 id > last_event_id 的事件 frames。"""
+    with _lock:
+        buf = _replay_buffers.get(agent_id)
+        if not buf:
+            return []
+        return [f"id: {eid}\ndata: {payload}\n\n" for eid, payload in buf if eid > last_event_id]
+
+
+def _parse_last_event_id(header_value: str | None) -> int:
+    """解析 ``Last-Event-ID`` header，非法或缺失返回 0。"""
+    if not header_value:
+        return 0
+    try:
+        return max(0, int(header_value.strip()))
+    except (ValueError, TypeError):
+        return 0
+
+
+async def _sse_generator(agent_id: uuid.UUID, last_event_id: int = 0):
+    # 1. 先 replay 历史事件（id > last_event_id）
+    for frame in _drain_replay(agent_id, last_event_id):
+        yield frame
+    # 2. 再进入正常 pub/sub 循环
+    queue = subscribe(agent_id)
+    try:
+        while True:
+            try:
+                data = await asyncio.to_thread(queue.get, True, HEARTBEAT_SECONDS)
+                yield data
+            except Empty:
+                yield ": heartbeat\n\n"
+    finally:
+        unsubscribe(agent_id, queue)
+
+
+def notification_sse_response(agent_id: uuid.UUID, last_event_id_header: str | None = None) -> StreamingResponse:
+    last_event_id = _parse_last_event_id(last_event_id_header)
+    return StreamingResponse(
+        _sse_generator(agent_id, last_event_id),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+            # 告知客户端支持 Last-Event-ID 重连（虽然 EventSource 默认就支持，
+            # 显式声明便于其他客户端实现识别）。
+            "X-Accel-Allow-Last-Event-ID": "true",
+        },
+    )

server/services/permissions.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session, joinedload
+
+from server.domain.models import (
+    Agent,
+    AgentRole,
+    Comment,
+    Experiment,
+    PlanVersion,
+    ProjectStatusVersion,
+    Review,
+    ReviewItem,
+    Topic,
+    TopicActionItem,
+    TopicComment,
+)
+from server.services.errors import ForbiddenError, NotFoundError, UnauthorizedError
+
+
+def is_admin(agent: Agent) -> bool:
+    return agent.role == AgentRole.admin
+
+
+def require_admin(agent: Agent) -> None:
+    if not is_admin(agent):
+        raise ForbiddenError("Admin role required")
+
+
+def ensure_project_access(agent: Agent, project_id: uuid.UUID) -> None:
+    if is_admin(agent):
+        return
+    if agent.project_id != project_id:
+        raise ForbiddenError("Access denied to this project")
+
+
+def ensure_can_revise_project_status(agent: Agent, project_id: uuid.UUID) -> None:
+    """Admin or project-bound agent (e.g. host persona) may revise Current Status MD."""
+    ensure_project_access(agent, project_id)
+
+
+def ensure_experiment_access(db: Session, agent: Agent, experiment_id: uuid.UUID) -> Experiment:
+    experiment = db.get(Experiment, experiment_id)
+    if experiment is None or experiment.deleted_at is not None:
+        raise NotFoundError("Experiment not found")
+    ensure_project_access(agent, experiment.project_id)
+    return experiment
+
+
+def ensure_review_item_access(db: Session, agent: Agent, item_id: uuid.UUID) -> ReviewItem:
+    stmt = select(ReviewItem).where(ReviewItem.id == item_id).options(joinedload(ReviewItem.review))
+    item = db.scalar(stmt)
+    if item is None:
+        raise NotFoundError("Review item not found")
+    ensure_experiment_access(db, agent, item.review.experiment_id)
+    return item
+
+
+def ensure_topic_access(db: Session, agent: Agent, topic_id: uuid.UUID) -> Topic:
+    topic = db.get(Topic, topic_id)
+    if topic is None or topic.deleted_at is not None:
+        raise NotFoundError("Topic not found")
+    ensure_project_access(agent, topic.project_id)
+    return topic
+
+
+def ensure_topic_host_or_admin(db: Session, agent: Agent, topic_id: uuid.UUID) -> Topic:
+    topic = ensure_topic_access(db, agent, topic_id)
+    if topic.creator_agent_id != agent.id and not is_admin(agent):
+        raise ForbiddenError("Only the topic host or admin can manage the topic")
+    return topic
+
+
+def ensure_topic_comment_access(db: Session, agent: Agent, comment_id: uuid.UUID) -> TopicComment:
+    comment = db.get(TopicComment, comment_id)
+    if comment is None:
+        raise NotFoundError("Topic comment not found")
+    ensure_topic_access(db, agent, comment.topic_id)
+    return comment
+
+
+def ensure_audit_target_access(
+    db: Session,
+    agent: Agent,
+    target_type: str,
+    target_id: uuid.UUID,
+) -> None:
+    if target_type == "experiment":
+        ensure_experiment_access(db, agent, target_id)
+    elif target_type == "topic":
+        ensure_topic_access(db, agent, target_id)
+    elif target_type == "plan_version":
+        plan = db.get(PlanVersion, target_id)
+        if plan is None:
+            raise NotFoundError("Plan version not found")
+        ensure_experiment_access(db, agent, plan.experiment_id)
+    elif target_type == "review":
+        review = db.get(Review, target_id)
+        if review is None:
+            raise NotFoundError("Review not found")
+        ensure_experiment_access(db, agent, review.experiment_id)
+    elif target_type == "comment":
+        comment = db.get(Comment, target_id)
+        if comment is None:
+            raise NotFoundError("Comment not found")
+        ensure_experiment_access(db, agent, comment.experiment_id)
+    elif target_type == "project_status_version":
+        version = db.get(ProjectStatusVersion, target_id)
+        if version is None:
+            raise NotFoundError("Project status version not found")
+        ensure_project_access(agent, version.project_id)
+    elif target_type == "topic_action_item":
+        item = db.get(TopicActionItem, target_id)
+        if item is None:
+            raise NotFoundError("Action item not found")
+        ensure_project_access(agent, item.project_id)
+    else:
+        raise NotFoundError(f"Unknown audit target type: {target_type}")
+
+
+def resolve_project_id_for_agent(agent: Agent, project_id: uuid.UUID | None) -> uuid.UUID:
+    if is_admin(agent):
+        if project_id is None:
+            raise ForbiddenError("Admin must specify project_id")
+        return project_id
+    if agent.project_id is None:
+        raise ForbiddenError("Agent is not bound to a project")
+    if project_id is not None and project_id != agent.project_id:
+        raise ForbiddenError("Access denied to this project")
+    return agent.project_id
+
+
+def ensure_can_register_agent(db: Session, actor: Agent | None, role: AgentRole) -> None:
+    """Allow unauthenticated bootstrap of the first admin; thereafter require admin."""
+    from sqlalchemy import func, select
+
+    count = db.scalar(select(func.count()).select_from(Agent)) or 0
+    if count == 0:
+        if role != AgentRole.admin:
+            raise ForbiddenError("Bootstrap: first agent must have role=admin")
+        return
+    if actor is None:
+        raise UnauthorizedError("Authentication required")
+    require_admin(actor)

server/services/persona_activity_service.py

@@ -0,0 +1,108 @@
+"""0db51e10 I3(5f): 默认选人逻辑（活跃 agent 时间窗 N=7）服务端 helper.
+
+承接 plan v2 (5c) / acceptance (f):
+
+> 默认选人逻辑单元测试(覆盖 project_id 边界 + agent 状态过滤 +
+> N=7 时间窗边界:恰好 7 天 / 8 天动作 / 7 天内无动作三种边界 case)
+
+判定: "活跃 agent" = **最近 7 天(N=7)内有 `log` / `topic` /
+`review` 任一动作的同 project agent**。N=7 可配置(默认 7),过期 agent
+自动排除。
+
+沿用 ``escalation_resolver._recent_same_role_agent`` 的判定来源
+(experiment_logs / comments / reviews 三个 source table),但
+本函数返回**所有** role 的活跃 agent 集合(用于 CLI
+``--persona-compare`` 默认选人),不做 single-role 过滤与
+exclude_agent_id。
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime, timedelta
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from server.domain.models import Agent, ExperimentLog, Review, TopicComment
+
+# 7 天窗口作为 plan v2 (5c) 默认;CLI/SDK 调用方可通过参数覆盖。
+DEFAULT_ACTIVE_WINDOW_DAYS = 7
+
+
+def list_active_personas(
+    db: Session,
+    *,
+    project_id: uuid.UUID,
+    window_days: int = DEFAULT_ACTIVE_WINDOW_DAYS,
+    now: datetime | None = None,
+) -> list[uuid.UUID]:
+    """Return agent UUIDs active in ``project_id`` within the time window.
+
+    "Active" = any row in ``experiment_logs`` / ``comments`` / ``reviews``
+    with ``created_at >= now - window_days`` AND the author /
+    reviewer agent belongs to ``project_id``. The function returns the
+    **distinct set** of agent UUIDs that satisfy the predicate; no
+    ordering guarantee beyond stable iteration order.
+
+    Args:
+        db: SQLAlchemy session.
+        project_id: Project scope for the lookup.
+        window_days: Lookback window in days (default 7, matches plan
+            v2 (5c) / (f) acceptance). Must be >= 1; ``window_days=0``
+            is rejected because it would always return zero rows and
+            provide a confusing default.
+        now: Reference "now" timestamp. Defaults to ``datetime.now(UTC)``.
+            Tests inject a fixed value to pin the boundary at exactly
+            7 / 8 / 0 days.
+
+    Returns:
+        List of distinct agent UUIDs active in the window. May be empty
+        when no agent has any recent action. Stable order across
+        invocations given the same DB state.
+    """
+    if window_days < 1:
+        raise ValueError(
+            f"window_days must be >= 1 (got {window_days}); "
+            "use the default 7 (plan v2 (5c)) or larger."
+        )
+    if now is None:
+        now = datetime.now(UTC)
+    cutoff = now - timedelta(days=window_days)
+
+    project_agents = set(
+        db.scalars(select(Agent.id).where(Agent.project_id == project_id)).all()
+    )
+    if not project_agents:
+        return []
+
+    active: set[uuid.UUID] = set()
+
+    log_authors = db.execute(
+        select(ExperimentLog.author_agent_id).where(
+            ExperimentLog.created_at >= cutoff,
+            ExperimentLog.author_agent_id.in_(project_agents),
+        )
+    ).all()
+    for (agent_id,) in log_authors:
+        active.add(agent_id)
+
+    comment_authors = db.execute(
+        select(TopicComment.author_agent_id).where(
+            TopicComment.created_at >= cutoff,
+            TopicComment.author_agent_id.in_(project_agents),
+        )
+    ).all()
+    for (agent_id,) in comment_authors:
+        active.add(agent_id)
+
+    reviewer_ids = db.execute(
+        select(Review.reviewer_agent_id).where(
+            Review.created_at >= cutoff,
+            Review.reviewer_agent_id.in_(project_agents),
+        )
+    ).all()
+    for (agent_id,) in reviewer_ids:
+        active.add(agent_id)
+
+    return list(active)

server/services/phase_owner_resolver.py

@@ -0,0 +1,95 @@
+"""Phase → owner resolution (experiment f873c287 I1(b)).
+
+A single source of truth that maps each ``ExperimentPhase`` value to the
+persona who currently holds decision authority to *advance* that phase.
+
+This module is intentionally pure (no DB, no side effects) so the
+``my_open_experiments.partition`` layer, the UI copy helper, and the
+``experiments_needing_attention`` filter can all import the same table
+without a circular dependency.
+
+Schema: ``PhaseOwner`` enum lives in ``sdk/python/map_types/enums.py`` and
+is the public contract; the string values here MUST match it. Keeping a
+local mirror avoids importing the SDK inside Alembic / CLI layers that
+should not pull pydantic.
+
+Why per phase? The decision-owner semantics are stable across runs (see
+experiment plan v2 I1(b) acceptance), but the resolver makes it easy to
+re-route by changing one mapping instead of grepping every consumer.
+
+Caveats
+-------
+- ``revise`` is not an ``ExperimentPhase`` value (revising happens inside
+  the ``review`` phase via ``plan_revise``); we keep it in the table as a
+  "logical phase" so callers can ask ``owner_for("revise")`` when
+  computing informational_only / UI copy during plan-revise windows.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+# Reuse the SDK enum so the public contract stays single-source. If the
+# enum is ever renamed, this import will surface that immediately at the
+# service layer.
+from map_types.enums import ExperimentPhase, PhaseOwner
+
+# Mirror the enum values verbatim so Alembic / non-SDK callers don't need
+# to import pydantic. KEPT IN SYNC with PhaseOwner — assertion below.
+_OWNERS: Final[dict[str, str]] = {
+    ExperimentPhase.draft.value: PhaseOwner.host.value,
+    ExperimentPhase.review.value: PhaseOwner.reviewer.value,
+    # "revise" is a logical sub-phase of review; ``plan_revise`` action
+    # is a host decision so the host owns advancement.
+    "revise": PhaseOwner.host.value,
+    ExperimentPhase.approved.value: PhaseOwner.host.value,
+    ExperimentPhase.running.value: PhaseOwner.host.value,
+    ExperimentPhase.result_review.value: PhaseOwner.reviewer.value,
+    ExperimentPhase.done.value: PhaseOwner.host.value,
+    ExperimentPhase.cancelled.value: PhaseOwner.host.value,
+}
+
+assert set(_OWNERS) == {*{p.value for p in ExperimentPhase}, "revise"}, (
+    f"phase_owner_resolver: phase coverage drifted. "
+    f"missing={set(p.value for p in ExperimentPhase) - _OWNERS.keys() - {'revise'}} "
+    f"extra={set(_OWNERS) - {p.value for p in ExperimentPhase} - {'revise'}}"
+)
+
+
+def owner_for(phase: str | ExperimentPhase) -> PhaseOwner:
+    """Return the persona who currently holds decision authority for ``phase``.
+
+    Accepts either an ``ExperimentPhase`` enum member or its raw string
+    value. Unknown phases fall back to ``host`` — the conservative default
+    that keeps ``informational_only`` false (which means the experiment
+    stays in the host's actionable obligation list).
+    """
+    key = phase.value if isinstance(phase, ExperimentPhase) else phase
+    return PhaseOwner(_OWNERS.get(key, PhaseOwner.host.value))
+
+
+def is_informational_only(
+    phase: str | ExperimentPhase,
+    *,
+    actions: list[str],
+    blocked_on: str | None,
+) -> bool:
+    """I1(a) auto-classification predicate.
+
+    Returns True iff all three preconditions hold:
+
+    1. ``actions`` is empty (host has no actionable next step).
+    2. ``blocked_on`` is non-empty (a state-machine gate is engaged).
+    3. ``phase_owner`` is **not** the host (decision authority is held by
+       another persona, so the host can only wait).
+
+    This predicate is the single source of truth for the
+    ``my_open_experiments.partition[].informational_only`` field; it is
+    re-used by the waker exclusion rule (I1(f)) and by the participant
+    filter (I1(e)).
+    """
+    if actions:
+        return False
+    if not blocked_on:
+        return False
+    return owner_for(phase) is not PhaseOwner.host