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

server/api/feedback.py

@@ -0,0 +1,75 @@
+import uuid
+
+from fastapi import APIRouter, Depends, Query, Response, status
+from map_types.enums import FeedbackCategory, FeedbackStatus
+from sqlalchemy.orm import Session
+
+from server.api.deps import get_current_agent
+from server.db.session import get_db
+from server.domain.models import Agent
+from server.domain.schemas import (
+    PlatformFeedbackCreate,
+    PlatformFeedbackRead,
+    PlatformFeedbackUpdate,
+)
+from server.services import permissions as perm
+from server.services import platform_feedback_service as svc
+
+feedback_router = APIRouter(prefix="/feedback", tags=["feedback"])
+
+
+@feedback_router.post("", response_model=PlatformFeedbackRead, status_code=status.HTTP_201_CREATED)
+def submit_feedback(
+    payload: PlatformFeedbackCreate,
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> PlatformFeedbackRead:
+    """Any authenticated agent may submit feedback. No project boundary enforced."""
+    return svc.create_feedback(db, agent, payload)
+
+
+@feedback_router.get("", response_model=list[PlatformFeedbackRead])
+def list_feedback(
+    response: Response,
+    feedback_status: FeedbackStatus | None = Query(default=None, alias="status"),
+    category: FeedbackCategory | None = Query(default=None),
+    project_id: uuid.UUID | None = Query(default=None),
+    page: int = Query(default=1, ge=1),
+    page_size: int = Query(default=50, ge=1, le=200),
+    include_archived: bool = Query(default=False),
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> list[PlatformFeedbackRead]:
+    perm.require_admin(agent)
+    items, total = svc.list_feedback(
+        db,
+        status=feedback_status,
+        category=category,
+        project_id=project_id,
+        page=page,
+        page_size=page_size,
+        include_archived=include_archived,
+    )
+    response.headers["X-Total-Count"] = str(total)
+    return items
+
+
+@feedback_router.get("/{feedback_id}", response_model=PlatformFeedbackRead)
+def get_feedback(
+    feedback_id: uuid.UUID,
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> PlatformFeedbackRead:
+    perm.require_admin(agent)
+    return svc.get_feedback_read(db, feedback_id)
+
+
+@feedback_router.patch("/{feedback_id}", response_model=PlatformFeedbackRead)
+def update_feedback(
+    feedback_id: uuid.UUID,
+    payload: PlatformFeedbackUpdate,
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> PlatformFeedbackRead:
+    perm.require_admin(agent)
+    return svc.update_feedback(db, feedback_id, payload)

server/api/notifications.py

@@ -0,0 +1,22 @@
+import uuid
+
+from fastapi import APIRouter, Depends
+from sqlalchemy.orm import Session
+
+from server.api.deps import get_current_agent
+from server.db.session import get_db
+from server.domain.models import Agent
+from server.domain.schemas import NotificationRead
+from server.services import notification_service
+
+notifications_router = APIRouter(prefix="/notifications", tags=["notifications"])
+
+
+@notifications_router.post("/{notification_id}/read", response_model=NotificationRead)
+def mark_notification_read(
+    notification_id: uuid.UUID,
+    agent: Agent = Depends(get_current_agent),
+    db: Session = Depends(get_db),
+) -> NotificationRead:
+    notification = notification_service.mark_read(db, agent, notification_id)
+    return NotificationRead.model_validate(notification)

server/api/projects.py

@@ -0,0 +1,209 @@
+import uuid
+
+from fastapi import APIRouter, Depends, Query, status
+from map_types.enums import TopicActionItemStatus
+from sqlalchemy import or_, select
+from sqlalchemy.orm import Session
+
+from server.api.background_tasks import bind_background_tasks
+from server.api.common import emit
+from server.api.deps import get_current_agent
+from server.db.session import get_db
+from server.domain.models import Agent, AgentRole
+from server.domain.schemas import (
+    AgentRead,
+    ProjectCreate,
+    ProjectRead,
+    ProjectStatusRead,
+    ProjectStatusRevise,
+    ProjectStatusVersionRead,
+    ProjectUpdate,
+    TopicActionItemRead,
+    TopicDecisionRead,
+)
+from server.services import permissions as perm
+from server.services import project_service as svc
+from server.services import project_status_service as status_doc_service
+
+router = APIRouter(
+    prefix="/projects",
+    tags=["projects"],
+    dependencies=[Depends(bind_background_tasks)],
+)
+
+
+@router.post("", response_model=ProjectRead, status_code=status.HTTP_201_CREATED)
+def create_project(
+    payload: ProjectCreate,
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> ProjectRead:
+    perm.require_admin(agent)
+    project = svc.create_project(db, payload, author_agent_id=agent.id)
+    return ProjectRead.model_validate(project)
+
+
+@router.get("", response_model=list[ProjectRead])
+def list_projects(
+    include_archived: bool = Query(default=False),
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> list[ProjectRead]:
+    if perm.is_admin(agent):
+        projects = svc.list_projects(db, include_archived=include_archived)
+    elif agent.project_id is None:
+        projects = []
+    else:
+        projects = svc.list_projects(
+            db, include_archived=include_archived, project_id=agent.project_id
+        )
+    return [ProjectRead.model_validate(p) for p in projects]
+
+
+@router.get("/by-key/{project_key}", response_model=ProjectRead)
+def get_project_by_key(
+    project_key: str,
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> ProjectRead:
+    project = svc.get_project_by_key(db, project_key)
+    perm.ensure_project_access(agent, project.id)
+    return ProjectRead.model_validate(project)
+
+
+@router.get("/{project_id}", response_model=ProjectRead)
+def get_project(
+    project_id: uuid.UUID,
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> ProjectRead:
+    perm.ensure_project_access(agent, project_id)
+    project = svc.get_project(db, project_id)
+    return ProjectRead.model_validate(project)
+
+
+@router.get("/{project_id}/agents", response_model=list[AgentRead])
+def list_project_agents(
+    project_id: uuid.UUID,
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> list[AgentRead]:
+    perm.ensure_project_access(agent, project_id)
+    svc.get_project(db, project_id)
+    agents = list(
+        db.scalars(
+            select(Agent)
+            .where(or_(Agent.project_id == project_id, Agent.role == AgentRole.admin))
+            .order_by(Agent.name)
+        )
+    )
+    return [
+        AgentRead(
+            id=a.id,
+            name=a.name,
+            role=a.role,
+            project_id=a.project_id,
+            project_key=None,
+            created_at=a.created_at,
+        )
+        for a in agents
+    ]
+
+
+@router.patch("/{project_id}", response_model=ProjectRead)
+def update_project(
+    project_id: uuid.UUID,
+    payload: ProjectUpdate,
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> ProjectRead:
+    perm.require_admin(agent)
+    project = svc.update_project(db, project_id, payload)
+    return ProjectRead.model_validate(project)
+
+
+@router.get("/{project_id}/status", response_model=ProjectStatusRead)
+def get_project_status(
+    project_id: uuid.UUID,
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> ProjectStatusRead:
+    perm.ensure_project_access(agent, project_id)
+    return svc.get_project_status(db, project_id)
+
+
+@router.get("/{project_id}/decisions", response_model=list[TopicDecisionRead])
+def list_project_decisions(
+    project_id: uuid.UUID,
+    limit: int = Query(default=20, ge=1, le=100),
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> list[TopicDecisionRead]:
+    perm.ensure_project_access(agent, project_id)
+    return svc.list_project_decisions(db, project_id, limit=limit)
+
+
+@router.get("/{project_id}/action-items", response_model=list[TopicActionItemRead])
+def list_project_action_items(
+    project_id: uuid.UUID,
+    owner_agent_id: uuid.UUID | None = Query(default=None),
+    item_status: TopicActionItemStatus | None = Query(default=None, alias="status"),
+    limit: int = Query(default=100, ge=1, le=200),
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> list[TopicActionItemRead]:
+    perm.ensure_project_access(agent, project_id)
+    return svc.list_project_action_items(
+        db,
+        project_id,
+        owner_agent_id=owner_agent_id,
+        status=item_status,
+        limit=limit,
+    )
+
+
+@router.post(
+    "/{project_id}/status/revisions",
+    response_model=ProjectStatusVersionRead,
+    status_code=status.HTTP_201_CREATED,
+)
+def revise_project_status(
+    project_id: uuid.UUID,
+    payload: ProjectStatusRevise,
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> ProjectStatusVersionRead:
+    perm.ensure_can_revise_project_status(agent, project_id)
+    version = status_doc_service.revise_status(db, project_id, agent.id, payload)
+    emit(
+        db,
+        agent,
+        action="project_status.revised",
+        target_type="project_status_version",
+        target_id=version.id,
+        project_id=project_id,
+        summary=f"修订项目 Status v{version.version}",
+    )
+    return ProjectStatusVersionRead.model_validate(version)
+
+
+@router.get("/{project_id}/status/versions", response_model=list[ProjectStatusVersionRead])
+def list_project_status_versions(
+    project_id: uuid.UUID,
+    limit: int = Query(default=50, ge=1, le=200),
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> list[ProjectStatusVersionRead]:
+    perm.ensure_project_access(agent, project_id)
+    return status_doc_service.list_status_versions(db, project_id, limit=limit)
+
+
+@router.get("/{project_id}/status/versions/{version}", response_model=ProjectStatusVersionRead)
+def get_project_status_version(
+    project_id: uuid.UUID,
+    version: int,
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> ProjectStatusVersionRead:
+    perm.ensure_project_access(agent, project_id)
+    return status_doc_service.get_status_version(db, project_id, version)

server/api/router.py

@@ -0,0 +1,25 @@
+"""Aggregate API routers for backward compatibility."""
+
+from server.api.action_items import action_items_router
+from server.api.agents import agents_router
+from server.api.audit import audit_router
+from server.api.experiments import experiments_router
+from server.api.feedback import feedback_router
+from server.api.notifications import notifications_router
+from server.api.projects import router
+from server.api.status import status_router
+from server.api.topics import topics_router
+from server.api.webhooks import webhooks_router
+
+__all__ = [
+    "action_items_router",
+    "notifications_router",
+    "router",
+    "agents_router",
+    "audit_router",
+    "experiments_router",
+    "feedback_router",
+    "status_router",
+    "topics_router",
+    "webhooks_router",
+]

server/api/status.py

@@ -0,0 +1,33 @@
+import uuid
+
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.orm import Session
+
+from server.api.deps import get_current_agent
+from server.db.session import get_db
+from server.domain.models import Agent
+from server.domain.schemas import (
+    GlobalStatusRead,
+)
+from server.services import permissions as perm
+from server.services import status_service
+from server.services.errors import ForbiddenError
+
+status_router = APIRouter(prefix="/status", tags=["status"])
+
+
+@status_router.get("", response_model=GlobalStatusRead)
+def get_global_status(
+    project_id: uuid.UUID | None = Query(default=None),
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> GlobalStatusRead:
+    if project_id is None:
+        if not perm.is_admin(agent):
+            if agent.project_id is None:
+                raise ForbiddenError("Agent is not bound to a project")
+            project_id = agent.project_id
+        else:
+            return status_service.get_global_status(db, project_id=None)
+    perm.ensure_project_access(agent, project_id)
+    return status_service.get_global_status(db, project_id=project_id)

server/api/topics.py

@@ -0,0 +1,302 @@
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
+from sqlalchemy.orm import Session
+
+from server.api.background_tasks import bind_background_tasks
+from server.api.common import emit
+from server.api.deps import get_current_agent
+from server.db.session import get_db
+from server.domain.models import Agent, TopicStatus
+from server.domain.schemas import (
+    TopicAdvanceRound,
+    TopicCommentCreate,
+    TopicCommentRead,
+    TopicCommentTreeNode,
+    TopicCreate,
+    TopicDecisionRead,
+    TopicRead,
+    TopicResolve,
+    TopicSummaryRead,
+    TopicUpdate,
+)
+from server.services import notification_service, topic_service
+from server.services import permissions as perm
+from server.services.errors import ForbiddenError
+
+topics_router = APIRouter(tags=["topics"], dependencies=[Depends(bind_background_tasks)])
+
+
+@topics_router.post(
+    "/projects/{project_id}/topics",
+    response_model=TopicSummaryRead,
+    status_code=status.HTTP_201_CREATED,
+)
+def create_topic(
+    project_id: uuid.UUID,
+    payload: TopicCreate,
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> TopicSummaryRead:
+    resolved_project_id = perm.resolve_project_id_for_agent(agent, project_id)
+    perm.ensure_project_access(agent, resolved_project_id)
+    topic = topic_service.create_topic(db, resolved_project_id, agent.id, payload)
+    emit(
+        db,
+        agent,
+        action="topic.created",
+        target_type="topic",
+        target_id=topic.id,
+        project_id=resolved_project_id,
+        summary=f"创建话题「{topic.title}」",
+        event="topic.created",
+        event_payload={"id": str(topic.id), "title": topic.title},
+    )
+    return topic_service.topic_summary(db, topic)
+
+
+@topics_router.get("/projects/{project_id}/topics", response_model=list[TopicSummaryRead])
+def list_topics(
+    project_id: uuid.UUID,
+    response: Response,
+    topic_status: TopicStatus | None = Query(default=None, alias="status"),
+    creator_agent_id: uuid.UUID | None = Query(default=None),
+    q: str | None = Query(default=None),
+    page: int = Query(default=1, ge=1),
+    page_size: int = Query(default=100, ge=1, le=100),
+    include_archived: bool = Query(default=False),
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> list[TopicSummaryRead]:
+    resolved_project_id = perm.resolve_project_id_for_agent(agent, project_id)
+    perm.ensure_project_access(agent, resolved_project_id)
+    topics, total = topic_service.list_topics(
+        db,
+        resolved_project_id,
+        status=topic_status,
+        creator_agent_id=creator_agent_id,
+        q=q,
+        page=page,
+        page_size=page_size,
+        include_archived=include_archived,
+        viewer_agent_id=agent.id,
+    )
+    response.headers["X-Total-Count"] = str(total)
+    return topics
+
+
+@topics_router.get("/topics/{topic_id}", response_model=TopicRead)
+def get_topic(
+    topic_id: uuid.UUID,
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> TopicRead:
+    perm.ensure_topic_access(db, agent, topic_id)
+    return topic_service.get_topic_detail(db, topic_id)
+
+
+@topics_router.patch("/topics/{topic_id}", response_model=TopicSummaryRead)
+def update_topic(
+    topic_id: uuid.UUID,
+    payload: TopicUpdate,
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> TopicSummaryRead:
+    # Archive/undo is a project-level operation: any project member may archive
+    # or restore a topic (docs/CLI.md archive spec — mirrors the experiment side
+    # which uses ``ensure_experiment_access``). Other field edits (title /
+    # description / pinned) remain host/admin-only.
+    changed_fields = payload.model_dump(exclude_unset=True)
+    if set(changed_fields) <= {"archived"}:
+        perm.ensure_topic_access(db, agent, topic_id)
+    else:
+        perm.ensure_topic_host_or_admin(db, agent, topic_id)
+    topic = topic_service.update_topic(db, topic_id, payload)
+    return topic_service.topic_summary(db, topic)
+
+
+@topics_router.delete("/topics/{topic_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_topic(
+    topic_id: uuid.UUID,
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> None:
+    perm.ensure_topic_host_or_admin(db, agent, topic_id)
+    topic_service.soft_delete_topic(db, topic_id)
+
+
+@topics_router.post("/topics/{topic_id}/close", response_model=TopicSummaryRead)
+def close_topic(
+    topic_id: uuid.UUID,
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> TopicSummaryRead:
+    perm.ensure_topic_host_or_admin(db, agent, topic_id)
+    topic = topic_service.set_topic_status(db, topic_id, TopicStatus.closed)
+    # Phase 2 D2: kind-directed SSE so the waker can map to ``topic_lifecycle``.
+    notification_service.emit_kind(
+        db,
+        project_id=topic.project_id,
+        actor_id=agent.id,
+        personas=["host", "participant"],
+        event="topic.lifecycle.closed",
+        summary=f"话题已关闭「{topic.title}」",
+        target_type="topic",
+        target_id=topic.id,
+        payload={"topic_id": str(topic.id), "title": topic.title, "status": "closed"},
+    )
+    return topic_service.topic_summary(db, topic)
+
+
+@topics_router.post("/topics/{topic_id}/dismiss", response_model=TopicSummaryRead)
+def dismiss_my_topic(
+    topic_id: uuid.UUID,
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> TopicSummaryRead:
+    """Host-only: hide an open topic from the creator's /todos.
+
+    Auto re-surfaces when the topic gets new activity (e.g. new comments).
+    """
+    topic = topic_service.dismiss_topic(db, agent=agent, topic_id=topic_id)
+    if topic is None:
+        raise HTTPException(status_code=404, detail="Topic not found")
+    return topic_service.topic_summary(db, topic)
+
+
+@topics_router.post("/topics/{topic_id}/reopen", response_model=TopicSummaryRead)
+def reopen_topic(
+    topic_id: uuid.UUID,
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> TopicSummaryRead:
+    perm.ensure_topic_host_or_admin(db, agent, topic_id)
+    topic = topic_service.set_topic_status(db, topic_id, TopicStatus.open)
+    # Phase 2 D2: kind-directed SSE for reopen so the waker can map to
+    # ``topic_lifecycle`` and resume the participant wake loop.
+    notification_service.emit_kind(
+        db,
+        project_id=topic.project_id,
+        actor_id=agent.id,
+        personas=["host", "participant"],
+        event="topic.lifecycle.reopened",
+        summary=f"话题已重开「{topic.title}」",
+        target_type="topic",
+        target_id=topic.id,
+        payload={"topic_id": str(topic.id), "title": topic.title, "status": "open"},
+    )
+    return topic_service.topic_summary(db, topic)
+
+
+@topics_router.post("/topics/{topic_id}/advance-round", response_model=TopicSummaryRead)
+def advance_topic_round(
+    topic_id: uuid.UUID,
+    payload: TopicAdvanceRound | None = None,
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> TopicSummaryRead:
+    topic = perm.ensure_topic_access(db, agent, topic_id)
+    body = payload or TopicAdvanceRound()
+
+    if body.ack is not None:
+        topic = topic_service.record_participant_round_ack(db, topic_id, agent, body.ack)
+        return topic_service.topic_summary(db, topic)
+
+    if topic.creator_agent_id != agent.id and not perm.is_admin(agent):
+        raise ForbiddenError("Only the topic host or admin can advance the discussion round")
+    topic = topic_service.advance_topic_round(
+        db,
+        topic_id,
+        increment_summary=body.increment_summary,
+        acknowledged_by=body.acknowledged_by,
+    )
+    emit(
+        db,
+        agent,
+        action="topic.advance_round",
+        target_type="topic",
+        target_id=topic.id,
+        project_id=topic.project_id,
+        summary=f"推进话题轮次至 {topic.discussion_round.value}",
+        event="topic.advance_round",
+        event_payload={
+            "topic_id": str(topic.id),
+            "discussion_round": topic.discussion_round.value,
+            "round_summary_count": topic.round_summary_count,
+        },
+    )
+    return topic_service.topic_summary(db, topic)
+
+
+@topics_router.post("/topics/{topic_id}/resolve", response_model=TopicDecisionRead)
+def resolve_topic(
+    topic_id: uuid.UUID,
+    payload: TopicResolve,
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> TopicDecisionRead:
+    topic = perm.ensure_topic_access(db, agent, topic_id)
+    if topic.creator_agent_id != agent.id and not perm.is_admin(agent):
+        raise ForbiddenError("Only the topic host or admin can resolve the topic")
+    decision = topic_service.resolve_topic(db, topic_id, agent, payload)
+    emit(
+        db,
+        agent,
+        action="topic.resolved",
+        target_type="topic",
+        target_id=topic.id,
+        project_id=topic.project_id,
+        summary=f"沉淀话题结论「{topic.title}」",
+        event="topic.resolved",
+        event_payload={"topic_id": str(topic.id), "decision_id": str(decision.id)},
+    )
+    return topic_service.topic_decision_read(db, decision)
+
+
+@topics_router.post(
+    "/topics/{topic_id}/comments",
+    response_model=TopicCommentRead,
+    status_code=status.HTTP_201_CREATED,
+)
+def create_topic_comment(
+    topic_id: uuid.UUID,
+    payload: TopicCommentCreate,
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> TopicCommentRead:
+    topic = perm.ensure_topic_access(db, agent, topic_id)
+    comment, unresolved = topic_service.create_topic_comment(db, topic_id, agent, payload)
+    event_payload = {"topic_id": str(topic_id), "comment_id": str(comment.id)}
+    emit(
+        db,
+        agent,
+        action="topic.comment.created",
+        target_type="topic_comment",
+        target_id=comment.id,
+        project_id=topic.project_id,
+        summary="话题新评论",
+        event="topic.comment.created",
+        event_payload=event_payload,
+        notify=False,
+    )
+    notification_service.notify_topic_comment_created(
+        db,
+        project_id=topic.project_id,
+        actor_id=agent.id,
+        creator_agent_id=topic.creator_agent_id,
+        target_id=comment.id,
+        payload=event_payload,
+    )
+    return topic_service.topic_comment_read(db, comment, unresolved_mentions=unresolved)
+
+
+@topics_router.get("/topics/{topic_id}/comments")
+def list_topic_comments(
+    topic_id: uuid.UUID,
+    tree: bool = Query(default=False),
+    limit: int = Query(default=100, ge=1, le=500),
+    db: Session = Depends(get_db),
+    agent: Agent = Depends(get_current_agent),
+) -> list[TopicCommentRead] | list[TopicCommentTreeNode]:
+    perm.ensure_topic_access(db, agent, topic_id)
+    return topic_service.list_topic_comments(db, topic_id, tree=tree, limit=limit)