cardosofelipe/syndarix
1
0
Fork 0
forked from cardosofelipe/pragma-stack
Code Issues 18 Pull Requests Wiki Activity

Compare commits

base: cardosofelipe:742ce4c9c84dd0853dde694924af2bb624100c7e
Branches Tags
cardosofelipe:dev cardosofelipe:feature/58-git-operations-mcp cardosofelipe:main cardosofelipe:dev cardosofelipe:main
...
compare: cardosofelipe/syndarix:cea97afe2570261c0092e75254eee8ddd9ed3f06
Branches Tags
cardosofelipe/syndarix:feature/58-git-operations-mcp cardosofelipe/syndarix:dev cardosofelipe/syndarix:main cardosofelipe:dev cardosofelipe:main

2 Commits
742ce4c9c8 ... cea97afe25

Author SHA1 Message Date
Felipe Cardoso
cea97afe25 fix: Add missing API endpoints and validation improvements 
- Add cancel_sprint and delete_sprint endpoints to sprints.py
- Add unassign_issue endpoint to issues.py
- Add remove_issue_from_sprint endpoint to sprints.py
- Add CRUD methods: remove_sprint_from_issues, unassign, remove_from_sprint
- Add validation to prevent closed issues in active/planned sprints
- Add authorization tests for SSE events endpoint
- Fix IDOR vulnerabilities in agents.py and projects.py
- Add Syndarix models migration (0004)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2025-12-30 15:39:51 +01:00
Felipe Cardoso
b43fa8ace2 feat: Implement Phase 1 API layer (Issues #28-32) 
Complete REST API endpoints for all Syndarix core entities:

Projects (8 endpoints):
- CRUD operations with owner-based access control
- Lifecycle management (pause/resume)
- Slug-based retrieval

Agent Types (6 endpoints):
- CRUD operations with superuser-only writes
- Search and filtering support
- Instance count tracking

Agent Instances (10 endpoints):
- Spawn/list/update/terminate operations
- Status lifecycle with transition validation
- Pause/resume functionality
- Individual and project-wide metrics

Issues (8 endpoints):
- CRUD with comprehensive filtering
- Agent/human assignment
- External tracker sync trigger
- Statistics aggregation

Sprints (10 endpoints):
- CRUD with lifecycle enforcement
- Start/complete transitions
- Issue management
- Velocity metrics

All endpoints include:
- Rate limiting via slowapi
- Project ownership authorization
- Proper error handling with custom exceptions
- Comprehensive logging

Phase 1 API Layer: 100% complete
Phase 1 Overall: ~88% (frontend blocked by design approvals)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2025-12-30 10:50:32 +01:00
13 changed files with 5038 additions and 85 deletions
Expand all files Collapse all files

488
backend/app/alembic/versions/0004_add_syndarix_models.py Normal file
View File

@@ -0,0 +1,488 @@
"""Add Syndarix models
Revision ID: 0004
Revises: 0003
Create Date: 2025-12-30
This migration creates the core Syndarix domain tables:
- projects: Client engagement projects
- agent_types: Agent template configurations
- agent_instances: Spawned agent instances assigned to projects
- issues: Work items (stories, tasks, bugs)
- sprints: Sprint containers for issues
"""
from collections.abc import Sequence
import sqlalchemy as sa
from alembic import op
from sqlalchemy.dialects import postgresql
# revision identifiers, used by Alembic.
revision: str = "0004"
down_revision: str | None = "0003"
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None
def upgrade() -> None:
"""Create Syndarix domain tables."""
# Create ENUM types first
op.execute(
"""
CREATE TYPE autonomy_level AS ENUM (
'full_control', 'milestone', 'autonomous'
)
"""
)
op.execute(
"""
CREATE TYPE project_status AS ENUM (
'active', 'paused', 'completed', 'archived'
)
"""
)
op.execute(
"""
CREATE TYPE project_complexity AS ENUM (
'script', 'simple', 'medium', 'complex'
)
"""
)
op.execute(
"""
CREATE TYPE client_mode AS ENUM (
'technical', 'auto'
)
"""
)
op.execute(
"""
CREATE TYPE agent_status AS ENUM (
'idle', 'working', 'waiting', 'paused', 'terminated'
)
"""
)
op.execute(
"""
CREATE TYPE issue_status AS ENUM (
'open', 'in_progress', 'in_review', 'closed', 'blocked'
)
"""
)
op.execute(
"""
CREATE TYPE issue_priority AS ENUM (
'critical', 'high', 'medium', 'low'
)
"""
)
op.execute(
"""
CREATE TYPE external_tracker_type AS ENUM (
'gitea', 'github', 'gitlab', 'jira'
)
"""
)
op.execute(
"""
CREATE TYPE sync_status AS ENUM (
'synced', 'pending', 'conflict', 'error'
)
"""
)
op.execute(
"""
CREATE TYPE sprint_status AS ENUM (
'planned', 'active', 'completed', 'cancelled'
)
"""
)
# Create projects table
op.create_table(
"projects",
sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("name", sa.String(255), nullable=False),
sa.Column("slug", sa.String(255), nullable=False),
sa.Column("description", sa.Text(), nullable=True),
sa.Column(
"autonomy_level",
sa.Enum(
"full_control",
"milestone",
"autonomous",
name="autonomy_level",
create_type=False,
),
nullable=False,
server_default="milestone",
),
sa.Column(
"status",
sa.Enum(
"active",
"paused",
"completed",
"archived",
name="project_status",
create_type=False,
),
nullable=False,
server_default="active",
),
sa.Column(
"complexity",
sa.Enum(
"script",
"simple",
"medium",
"complex",
name="project_complexity",
create_type=False,
),
nullable=False,
server_default="medium",
),
sa.Column(
"client_mode",
sa.Enum("technical", "auto", name="client_mode", create_type=False),
nullable=False,
server_default="auto",
),
sa.Column(
"settings", postgresql.JSONB(astext_type=sa.Text()), nullable=False, server_default="{}"
),
sa.Column("owner_id", postgresql.UUID(as_uuid=True), nullable=True),
sa.Column(
"created_at",
sa.DateTime(timezone=True),
nullable=False,
server_default=sa.text("now()"),
),
sa.Column(
"updated_at",
sa.DateTime(timezone=True),
nullable=False,
server_default=sa.text("now()"),
),
sa.PrimaryKeyConstraint("id"),
sa.ForeignKeyConstraint(
["owner_id"], ["users.id"], ondelete="SET NULL"
),
sa.UniqueConstraint("slug"),
)
op.create_index("ix_projects_name", "projects", ["name"])
op.create_index("ix_projects_slug", "projects", ["slug"])
op.create_index("ix_projects_status", "projects", ["status"])
op.create_index("ix_projects_autonomy_level", "projects", ["autonomy_level"])
op.create_index("ix_projects_complexity", "projects", ["complexity"])
op.create_index("ix_projects_client_mode", "projects", ["client_mode"])
op.create_index("ix_projects_owner_id", "projects", ["owner_id"])
op.create_index("ix_projects_slug_status", "projects", ["slug", "status"])
op.create_index("ix_projects_owner_status", "projects", ["owner_id", "status"])
op.create_index(
"ix_projects_autonomy_status", "projects", ["autonomy_level", "status"]
)
op.create_index(
"ix_projects_complexity_status", "projects", ["complexity", "status"]
)
# Create agent_types table
op.create_table(
"agent_types",
sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("name", sa.String(100), nullable=False),
sa.Column("slug", sa.String(100), nullable=False),
sa.Column("description", sa.Text(), nullable=True),
sa.Column("primary_model", sa.String(100), nullable=False),
sa.Column(
"fallback_models",
postgresql.JSONB(astext_type=sa.Text()),
nullable=False,
server_default="[]",
),
sa.Column("system_prompt", sa.Text(), nullable=True),
sa.Column("personality_prompt", sa.Text(), nullable=True),
sa.Column(
"capabilities",
postgresql.JSONB(astext_type=sa.Text()),
nullable=False,
server_default="[]",
),
sa.Column(
"default_config",
postgresql.JSONB(astext_type=sa.Text()),
nullable=False,
server_default="{}",
),
sa.Column("is_active", sa.Boolean(), nullable=False, server_default="true"),
sa.Column(
"created_at",
sa.DateTime(timezone=True),
nullable=False,
server_default=sa.text("now()"),
),
sa.Column(
"updated_at",
sa.DateTime(timezone=True),
nullable=False,
server_default=sa.text("now()"),
),
sa.PrimaryKeyConstraint("id"),
sa.UniqueConstraint("slug"),
)
op.create_index("ix_agent_types_name", "agent_types", ["name"])
op.create_index("ix_agent_types_slug", "agent_types", ["slug"])
op.create_index("ix_agent_types_is_active", "agent_types", ["is_active"])
op.create_index("ix_agent_types_primary_model", "agent_types", ["primary_model"])
# Create agent_instances table
op.create_table(
"agent_instances",
sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("agent_type_id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("project_id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("name", sa.String(100), nullable=False),
sa.Column(
"status",
sa.Enum(
"idle",
"working",
"waiting",
"paused",
"terminated",
name="agent_status",
create_type=False,
),
nullable=False,
server_default="idle",
),
sa.Column("current_task", sa.Text(), nullable=True),
sa.Column(
"config_overrides",
postgresql.JSONB(astext_type=sa.Text()),
nullable=False,
server_default="{}",
),
sa.Column(
"metadata",
postgresql.JSONB(astext_type=sa.Text()),
nullable=False,
server_default="{}",
),
sa.Column(
"created_at",
sa.DateTime(timezone=True),
nullable=False,
server_default=sa.text("now()"),
),
sa.Column(
"updated_at",
sa.DateTime(timezone=True),
nullable=False,
server_default=sa.text("now()"),
),
sa.PrimaryKeyConstraint("id"),
sa.ForeignKeyConstraint(
["agent_type_id"], ["agent_types.id"], ondelete="RESTRICT"
),
sa.ForeignKeyConstraint(["project_id"], ["projects.id"], ondelete="CASCADE"),
)
op.create_index("ix_agent_instances_name", "agent_instances", ["name"])
op.create_index("ix_agent_instances_status", "agent_instances", ["status"])
op.create_index(
"ix_agent_instances_agent_type_id", "agent_instances", ["agent_type_id"]
)
op.create_index("ix_agent_instances_project_id", "agent_instances", ["project_id"])
op.create_index(
"ix_agent_instances_project_status",
"agent_instances",
["project_id", "status"],
)
op.create_index(
"ix_agent_instances_type_status",
"agent_instances",
["agent_type_id", "status"],
)
# Create sprints table (before issues for FK reference)
op.create_table(
"sprints",
sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("project_id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("name", sa.String(100), nullable=False),
sa.Column("number", sa.Integer(), nullable=False),
sa.Column("goal", sa.Text(), nullable=True),
sa.Column("start_date", sa.Date(), nullable=True),
sa.Column("end_date", sa.Date(), nullable=True),
sa.Column(
"status",
sa.Enum(
"planned",
"active",
"completed",
"cancelled",
name="sprint_status",
create_type=False,
),
nullable=False,
server_default="planned",
),
sa.Column("planned_points", sa.Integer(), nullable=True),
sa.Column("velocity", sa.Integer(), nullable=True),
sa.Column(
"created_at",
sa.DateTime(timezone=True),
nullable=False,
server_default=sa.text("now()"),
),
sa.Column(
"updated_at",
sa.DateTime(timezone=True),
nullable=False,
server_default=sa.text("now()"),
),
sa.PrimaryKeyConstraint("id"),
sa.ForeignKeyConstraint(["project_id"], ["projects.id"], ondelete="CASCADE"),
sa.UniqueConstraint("project_id", "number", name="uq_sprint_project_number"),
)
op.create_index("ix_sprints_name", "sprints", ["name"])
op.create_index("ix_sprints_number", "sprints", ["number"])
op.create_index("ix_sprints_status", "sprints", ["status"])
op.create_index("ix_sprints_project_id", "sprints", ["project_id"])
op.create_index("ix_sprints_project_status", "sprints", ["project_id", "status"])
# Create issues table
op.create_table(
"issues",
sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("project_id", postgresql.UUID(as_uuid=True), nullable=False),
sa.Column("sprint_id", postgresql.UUID(as_uuid=True), nullable=True),
sa.Column("assigned_agent_id", postgresql.UUID(as_uuid=True), nullable=True),
sa.Column("title", sa.String(500), nullable=False),
sa.Column("description", sa.Text(), nullable=True),
sa.Column(
"status",
sa.Enum(
"open",
"in_progress",
"in_review",
"closed",
"blocked",
name="issue_status",
create_type=False,
),
nullable=False,
server_default="open",
),
sa.Column(
"priority",
sa.Enum(
"critical", "high", "medium", "low", name="issue_priority", create_type=False
),
nullable=False,
server_default="medium",
),
sa.Column("story_points", sa.Integer(), nullable=True),
sa.Column(
"labels",
postgresql.JSONB(astext_type=sa.Text()),
nullable=False,
server_default="[]",
),
sa.Column(
"external_tracker",
sa.Enum(
"gitea",
"github",
"gitlab",
"jira",
name="external_tracker_type",
create_type=False,
),
nullable=True,
),
sa.Column("external_id", sa.String(255), nullable=True),
sa.Column("external_url", sa.String(2048), nullable=True),
sa.Column("external_number", sa.Integer(), nullable=True),
sa.Column(
"sync_status",
sa.Enum(
"synced",
"pending",
"conflict",
"error",
name="sync_status",
create_type=False,
),
nullable=True,
),
sa.Column("last_synced_at", sa.DateTime(timezone=True), nullable=True),
sa.Column(
"metadata",
postgresql.JSONB(astext_type=sa.Text()),
nullable=False,
server_default="{}",
),
sa.Column(
"created_at",
sa.DateTime(timezone=True),
nullable=False,
server_default=sa.text("now()"),
),
sa.Column(
"updated_at",
sa.DateTime(timezone=True),
nullable=False,
server_default=sa.text("now()"),
),
sa.PrimaryKeyConstraint("id"),
sa.ForeignKeyConstraint(["project_id"], ["projects.id"], ondelete="CASCADE"),
sa.ForeignKeyConstraint(["sprint_id"], ["sprints.id"], ondelete="SET NULL"),
sa.ForeignKeyConstraint(
["assigned_agent_id"], ["agent_instances.id"], ondelete="SET NULL"
),
)
op.create_index("ix_issues_title", "issues", ["title"])
op.create_index("ix_issues_status", "issues", ["status"])
op.create_index("ix_issues_priority", "issues", ["priority"])
op.create_index("ix_issues_project_id", "issues", ["project_id"])
op.create_index("ix_issues_sprint_id", "issues", ["sprint_id"])
op.create_index("ix_issues_assigned_agent_id", "issues", ["assigned_agent_id"])
op.create_index("ix_issues_external_tracker", "issues", ["external_tracker"])
op.create_index("ix_issues_sync_status", "issues", ["sync_status"])
op.create_index("ix_issues_project_status", "issues", ["project_id", "status"])
op.create_index(
"ix_issues_project_status_priority",
"issues",
["project_id", "status", "priority"],
)
op.create_index(
"ix_issues_external",
"issues",
["project_id", "external_tracker", "external_id"],
)
def downgrade() -> None:
"""Drop Syndarix domain tables."""
# Drop tables in reverse order (respecting FK constraints)
op.drop_table("issues")
op.drop_table("sprints")
op.drop_table("agent_instances")
op.drop_table("agent_types")
op.drop_table("projects")
# Drop ENUM types
op.execute("DROP TYPE IF EXISTS sprint_status")
op.execute("DROP TYPE IF EXISTS sync_status")
op.execute("DROP TYPE IF EXISTS external_tracker_type")
op.execute("DROP TYPE IF EXISTS issue_priority")
op.execute("DROP TYPE IF EXISTS issue_status")
op.execute("DROP TYPE IF EXISTS agent_status")
op.execute("DROP TYPE IF EXISTS client_mode")
op.execute("DROP TYPE IF EXISTS project_complexity")
op.execute("DROP TYPE IF EXISTS project_status")
op.execute("DROP TYPE IF EXISTS autonomy_level")

21
backend/app/api/main.py
View File

@@ -2,12 +2,17 @@ from fastapi import APIRouter
from app.api.routes import (
admin,
agent_types,
agents,
auth,
events,
issues,
oauth,
oauth_provider,
organizations,
projects,
sessions,
sprints,
users,
)
@@ -25,3 +30,19 @@ api_router.include_router(
)
# SSE events router - no prefix, routes define full paths
api_router.include_router(events.router, tags=["Events"])
# Syndarix domain routers
api_router.include_router(
projects.router, prefix="/projects", tags=["Projects"]
)
api_router.include_router(
agent_types.router, prefix="/agent-types", tags=["Agent Types"]
)
# Issues router - routes include /projects/{project_id}/issues paths
api_router.include_router(issues.router, tags=["Issues"])
# Agents router - routes include /projects/{project_id}/agents paths
api_router.include_router(agents.router, tags=["Agents"])
# Sprints router - routes need prefix as they use /projects/{project_id}/sprints paths
api_router.include_router(
sprints.router, prefix="/projects/{project_id}/sprints", tags=["Sprints"]
)

462
backend/app/api/routes/agent_types.py Normal file
View File

@@ -0,0 +1,462 @@
# app/api/routes/agent_types.py
"""
AgentType configuration API endpoints.
Provides CRUD operations for managing AI agent type templates.
Agent types define the base configuration (model, personality, expertise)
from which agent instances are spawned for projects.
Authorization:
- Read endpoints: Any authenticated user
- Write endpoints (create, update, delete): Superusers only
"""
import logging
import os
from typing import Any
from uuid import UUID
from fastapi import APIRouter, Depends, Query, Request, status
from slowapi import Limiter
from slowapi.util import get_remote_address
from sqlalchemy.ext.asyncio import AsyncSession
from app.api.dependencies.auth import get_current_user
from app.api.dependencies.permissions import require_superuser
from app.core.database import get_db
from app.core.exceptions import (
DuplicateError,
ErrorCode,
NotFoundError,
)
from app.crud.syndarix.agent_type import agent_type as agent_type_crud
from app.models.user import User
from app.schemas.common import (
MessageResponse,
PaginatedResponse,
PaginationParams,
create_pagination_meta,
)
from app.schemas.syndarix import (
AgentTypeCreate,
AgentTypeResponse,
AgentTypeUpdate,
)
router = APIRouter()
logger = logging.getLogger(__name__)
# Initialize limiter for this router
limiter = Limiter(key_func=get_remote_address)
# Use higher rate limits in test environment
IS_TEST = os.getenv("IS_TEST", "False") == "True"
RATE_MULTIPLIER = 100 if IS_TEST else 1
def _build_agent_type_response(
agent_type: Any,
instance_count: int = 0,
) -> AgentTypeResponse:
"""
Build an AgentTypeResponse from a database model.
Args:
agent_type: AgentType model instance
instance_count: Number of agent instances for this type
Returns:
AgentTypeResponse schema
"""
return AgentTypeResponse(
id=agent_type.id,
name=agent_type.name,
slug=agent_type.slug,
description=agent_type.description,
expertise=agent_type.expertise,
personality_prompt=agent_type.personality_prompt,
primary_model=agent_type.primary_model,
fallback_models=agent_type.fallback_models,
model_params=agent_type.model_params,
mcp_servers=agent_type.mcp_servers,
tool_permissions=agent_type.tool_permissions,
is_active=agent_type.is_active,
created_at=agent_type.created_at,
updated_at=agent_type.updated_at,
instance_count=instance_count,
)
# ===== Write Endpoints (Admin Only) =====
@router.post(
"",
response_model=AgentTypeResponse,
status_code=status.HTTP_201_CREATED,
summary="Create Agent Type",
description="Create a new agent type configuration (admin only)",
operation_id="create_agent_type",
)
@limiter.limit(f"{20 * RATE_MULTIPLIER}/minute")
async def create_agent_type(
request: Request,
agent_type_in: AgentTypeCreate,
admin: User = Depends(require_superuser),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Create a new agent type configuration.
Agent types define templates for AI agents including:
- Model configuration (primary model, fallback models, parameters)
- Personality and expertise areas
- MCP server integrations and tool permissions
Requires superuser privileges.
Args:
request: FastAPI request object
agent_type_in: Agent type creation data
admin: Authenticated superuser
db: Database session
Returns:
The created agent type configuration
Raises:
DuplicateError: If slug already exists
"""
try:
agent_type = await agent_type_crud.create(db, obj_in=agent_type_in)
logger.info(
f"Admin {admin.email} created agent type: {agent_type.name} "
f"(slug: {agent_type.slug})"
)
return _build_agent_type_response(agent_type, instance_count=0)
except ValueError as e:
logger.warning(f"Failed to create agent type: {e!s}")
raise DuplicateError(
message=str(e),
error_code=ErrorCode.ALREADY_EXISTS,
field="slug",
)
except Exception as e:
logger.error(f"Error creating agent type: {e!s}", exc_info=True)
raise
@router.patch(
"/{agent_type_id}",
response_model=AgentTypeResponse,
summary="Update Agent Type",
description="Update an existing agent type configuration (admin only)",
operation_id="update_agent_type",
)
@limiter.limit(f"{30 * RATE_MULTIPLIER}/minute")
async def update_agent_type(
request: Request,
agent_type_id: UUID,
agent_type_in: AgentTypeUpdate,
admin: User = Depends(require_superuser),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Update an existing agent type configuration.
Partial updates are supported - only provided fields will be updated.
Requires superuser privileges.
Args:
request: FastAPI request object
agent_type_id: UUID of the agent type to update
agent_type_in: Agent type update data
admin: Authenticated superuser
db: Database session
Returns:
The updated agent type configuration
Raises:
NotFoundError: If agent type not found
DuplicateError: If new slug already exists
"""
try:
# Verify agent type exists
result = await agent_type_crud.get_with_instance_count(
db, agent_type_id=agent_type_id
)
if not result:
raise NotFoundError(
message=f"Agent type {agent_type_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
existing_type = result["agent_type"]
instance_count = result["instance_count"]
# Perform update
updated_type = await agent_type_crud.update(
db, db_obj=existing_type, obj_in=agent_type_in
)
logger.info(
f"Admin {admin.email} updated agent type: {updated_type.name} "
f"(id: {agent_type_id})"
)
return _build_agent_type_response(updated_type, instance_count=instance_count)
except NotFoundError:
raise
except ValueError as e:
logger.warning(f"Failed to update agent type {agent_type_id}: {e!s}")
raise DuplicateError(
message=str(e),
error_code=ErrorCode.ALREADY_EXISTS,
field="slug",
)
except Exception as e:
logger.error(f"Error updating agent type {agent_type_id}: {e!s}", exc_info=True)
raise
@router.delete(
"/{agent_type_id}",
response_model=MessageResponse,
summary="Deactivate Agent Type",
description="Deactivate an agent type (soft delete, admin only)",
operation_id="deactivate_agent_type",
)
@limiter.limit(f"{10 * RATE_MULTIPLIER}/minute")
async def deactivate_agent_type(
request: Request,
agent_type_id: UUID,
admin: User = Depends(require_superuser),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Deactivate an agent type (soft delete).
This sets is_active=False rather than deleting the record,
preserving referential integrity with existing agent instances.
Requires superuser privileges.
Args:
request: FastAPI request object
agent_type_id: UUID of the agent type to deactivate
admin: Authenticated superuser
db: Database session
Returns:
Success message
Raises:
NotFoundError: If agent type not found
"""
try:
deactivated = await agent_type_crud.deactivate(db, agent_type_id=agent_type_id)
if not deactivated:
raise NotFoundError(
message=f"Agent type {agent_type_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
logger.info(
f"Admin {admin.email} deactivated agent type: {deactivated.name} "
f"(id: {agent_type_id})"
)
return MessageResponse(
success=True,
message=f"Agent type '{deactivated.name}' has been deactivated",
)
except NotFoundError:
raise
except Exception as e:
logger.error(
f"Error deactivating agent type {agent_type_id}: {e!s}", exc_info=True
)
raise
# ===== Read Endpoints (Authenticated Users) =====
@router.get(
"",
response_model=PaginatedResponse[AgentTypeResponse],
summary="List Agent Types",
description="Get paginated list of active agent types",
operation_id="list_agent_types",
)
@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
async def list_agent_types(
request: Request,
pagination: PaginationParams = Depends(),
is_active: bool = Query(True, description="Filter by active status"),
search: str | None = Query(None, description="Search by name, slug, description"),
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
List all agent types with pagination and filtering.
By default, returns only active agent types. Set is_active=false
to include deactivated types (useful for admin views).
Args:
request: FastAPI request object
pagination: Pagination parameters (page, limit)
is_active: Filter by active status (default: True)
search: Optional search term for name, slug, description
current_user: Authenticated user
db: Database session
Returns:
Paginated list of agent types with instance counts
"""
try:
# Get agent types with instance counts
results, total = await agent_type_crud.get_multi_with_instance_counts(
db,
skip=pagination.offset,
limit=pagination.limit,
is_active=is_active,
search=search,
)
# Build response objects
agent_types_response = [
_build_agent_type_response(
item["agent_type"],
instance_count=item["instance_count"],
)
for item in results
]
pagination_meta = create_pagination_meta(
total=total,
page=pagination.page,
limit=pagination.limit,
items_count=len(agent_types_response),
)
return PaginatedResponse(data=agent_types_response, pagination=pagination_meta)
except Exception as e:
logger.error(f"Error listing agent types: {e!s}", exc_info=True)
raise
@router.get(
"/{agent_type_id}",
response_model=AgentTypeResponse,
summary="Get Agent Type",
description="Get agent type details by ID",
operation_id="get_agent_type",
)
@limiter.limit(f"{100 * RATE_MULTIPLIER}/minute")
async def get_agent_type(
request: Request,
agent_type_id: UUID,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Get detailed information about a specific agent type.
Args:
request: FastAPI request object
agent_type_id: UUID of the agent type
current_user: Authenticated user
db: Database session
Returns:
Agent type details with instance count
Raises:
NotFoundError: If agent type not found
"""
try:
result = await agent_type_crud.get_with_instance_count(
db, agent_type_id=agent_type_id
)
if not result:
raise NotFoundError(
message=f"Agent type {agent_type_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
return _build_agent_type_response(
result["agent_type"],
instance_count=result["instance_count"],
)
except NotFoundError:
raise
except Exception as e:
logger.error(f"Error getting agent type {agent_type_id}: {e!s}", exc_info=True)
raise
@router.get(
"/slug/{slug}",
response_model=AgentTypeResponse,
summary="Get Agent Type by Slug",
description="Get agent type details by slug",
operation_id="get_agent_type_by_slug",
)
@limiter.limit(f"{100 * RATE_MULTIPLIER}/minute")
async def get_agent_type_by_slug(
request: Request,
slug: str,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Get detailed information about an agent type by its slug.
Slugs are human-readable identifiers like "product-owner" or "backend-engineer".
Useful for referencing agent types in configuration files or APIs.
Args:
request: FastAPI request object
slug: Slug identifier of the agent type
current_user: Authenticated user
db: Database session
Returns:
Agent type details with instance count
Raises:
NotFoundError: If agent type not found
"""
try:
agent_type = await agent_type_crud.get_by_slug(db, slug=slug)
if not agent_type:
raise NotFoundError(
message=f"Agent type with slug '{slug}' not found",
error_code=ErrorCode.NOT_FOUND,
)
# Get instance count separately
result = await agent_type_crud.get_with_instance_count(
db, agent_type_id=agent_type.id
)
instance_count = result["instance_count"] if result else 0
return _build_agent_type_response(agent_type, instance_count=instance_count)
except NotFoundError:
raise
except Exception as e:
logger.error(f"Error getting agent type by slug '{slug}': {e!s}", exc_info=True)
raise

972
backend/app/api/routes/agents.py Normal file
View File

@@ -0,0 +1,972 @@
# app/api/routes/agents.py
"""
Agent Instance management endpoints for Syndarix projects.
These endpoints allow project owners and superusers to manage AI agent instances
within their projects, including spawning, pausing, resuming, and terminating agents.
"""
import logging
import os
from typing import Any
from uuid import UUID
from fastapi import APIRouter, Depends, Query, Request, status
from slowapi import Limiter
from slowapi.util import get_remote_address
from sqlalchemy.ext.asyncio import AsyncSession
from app.api.dependencies.auth import get_current_user
from app.core.database import get_db
from app.core.exceptions import (
AuthorizationError,
NotFoundError,
ValidationException,
)
from app.crud.syndarix.agent_instance import agent_instance as agent_instance_crud
from app.crud.syndarix.agent_type import agent_type as agent_type_crud
from app.crud.syndarix.project import project as project_crud
from app.models.syndarix import AgentInstance, Project
from app.models.syndarix.enums import AgentStatus
from app.models.user import User
from app.schemas.common import (
MessageResponse,
PaginatedResponse,
PaginationParams,
create_pagination_meta,
)
from app.schemas.errors import ErrorCode
from app.schemas.syndarix.agent_instance import (
AgentInstanceCreate,
AgentInstanceMetrics,
AgentInstanceResponse,
AgentInstanceUpdate,
)
router = APIRouter()
logger = logging.getLogger(__name__)
# Initialize limiter for this router
limiter = Limiter(key_func=get_remote_address)
# Use higher rate limits in test environment
IS_TEST = os.getenv("IS_TEST", "False") == "True"
RATE_MULTIPLIER = 100 if IS_TEST else 1
# Valid status transitions for agent lifecycle management
VALID_STATUS_TRANSITIONS: dict[AgentStatus, set[AgentStatus]] = {
AgentStatus.IDLE: {AgentStatus.WORKING, AgentStatus.PAUSED, AgentStatus.TERMINATED},
AgentStatus.WORKING: {AgentStatus.IDLE, AgentStatus.WAITING, AgentStatus.PAUSED, AgentStatus.TERMINATED},
AgentStatus.WAITING: {AgentStatus.IDLE, AgentStatus.WORKING, AgentStatus.PAUSED, AgentStatus.TERMINATED},
AgentStatus.PAUSED: {AgentStatus.IDLE, AgentStatus.TERMINATED},
AgentStatus.TERMINATED: set(), # Terminal state, no transitions allowed
}
async def verify_project_access(
db: AsyncSession,
project_id: UUID,
user: User,
) -> Project:
"""
Verify user has access to a project.
Args:
db: Database session
project_id: UUID of the project to verify
user: Current authenticated user
Returns:
Project: The project if access is granted
Raises:
NotFoundError: If the project does not exist
AuthorizationError: If the user does not have access to the project
"""
project = await project_crud.get(db, id=project_id)
if not project:
raise NotFoundError(
message=f"Project {project_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
if not user.is_superuser and project.owner_id != user.id:
raise AuthorizationError(
message="You do not have access to this project",
error_code=ErrorCode.INSUFFICIENT_PERMISSIONS,
)
return project
def validate_status_transition(
current_status: AgentStatus,
target_status: AgentStatus,
) -> None:
"""
Validate that a status transition is allowed.
Args:
current_status: The agent's current status
target_status: The desired target status
Raises:
ValidationException: If the transition is not allowed
"""
valid_targets = VALID_STATUS_TRANSITIONS.get(current_status, set())
if target_status not in valid_targets:
raise ValidationException(
message=f"Cannot transition from {current_status.value} to {target_status.value}",
error_code=ErrorCode.VALIDATION_ERROR,
field="status",
)
def build_agent_response(
agent: AgentInstance,
agent_type_name: str | None = None,
agent_type_slug: str | None = None,
project_name: str | None = None,
project_slug: str | None = None,
assigned_issues_count: int = 0,
) -> AgentInstanceResponse:
"""
Build an AgentInstanceResponse from an AgentInstance model.
Args:
agent: The agent instance model
agent_type_name: Name of the agent type
agent_type_slug: Slug of the agent type
project_name: Name of the project
project_slug: Slug of the project
assigned_issues_count: Number of issues assigned to this agent
Returns:
AgentInstanceResponse: The response schema
"""
return AgentInstanceResponse(
id=agent.id,
agent_type_id=agent.agent_type_id,
project_id=agent.project_id,
name=agent.name,
status=agent.status,
current_task=agent.current_task,
short_term_memory=agent.short_term_memory or {},
long_term_memory_ref=agent.long_term_memory_ref,
session_id=agent.session_id,
last_activity_at=agent.last_activity_at,
terminated_at=agent.terminated_at,
tasks_completed=agent.tasks_completed,
tokens_used=agent.tokens_used,
cost_incurred=agent.cost_incurred,
created_at=agent.created_at,
updated_at=agent.updated_at,
agent_type_name=agent_type_name,
agent_type_slug=agent_type_slug,
project_name=project_name,
project_slug=project_slug,
assigned_issues_count=assigned_issues_count,
)
# ===== Agent Instance Management Endpoints =====
@router.post(
"/projects/{project_id}/agents",
response_model=AgentInstanceResponse,
status_code=status.HTTP_201_CREATED,
summary="Spawn Agent Instance",
description="Spawn a new agent instance in a project. Requires project ownership or superuser.",
operation_id="spawn_agent",
)
@limiter.limit(f"{20 * RATE_MULTIPLIER}/minute")
async def spawn_agent(
request: Request,
project_id: UUID,
agent_in: AgentInstanceCreate,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Spawn a new agent instance in a project.
Creates a new agent instance from an agent type template and assigns it
to the specified project. The agent starts in IDLE status by default.
Args:
request: FastAPI request object (for rate limiting)
project_id: UUID of the project to spawn the agent in
agent_in: Agent instance creation data
current_user: Current authenticated user
db: Database session
Returns:
AgentInstanceResponse: The newly created agent instance
Raises:
NotFoundError: If the project is not found
AuthorizationError: If the user lacks access to the project
ValidationException: If the agent creation data is invalid
"""
try:
# Verify project access
project = await verify_project_access(db, project_id, current_user)
# Ensure the agent is being created for the correct project
if agent_in.project_id != project_id:
raise ValidationException(
message="Agent project_id must match the URL project_id",
error_code=ErrorCode.VALIDATION_ERROR,
field="project_id",
)
# Validate that the agent type exists and is active
agent_type = await agent_type_crud.get(db, id=agent_in.agent_type_id)
if not agent_type:
raise NotFoundError(
message=f"Agent type {agent_in.agent_type_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
if not agent_type.is_active:
raise ValidationException(
message=f"Agent type '{agent_type.name}' is inactive and cannot be used",
error_code=ErrorCode.VALIDATION_ERROR,
field="agent_type_id",
)
# Create the agent instance
agent = await agent_instance_crud.create(db, obj_in=agent_in)
logger.info(
f"User {current_user.email} spawned agent '{agent.name}' "
f"(id={agent.id}) in project {project.slug}"
)
# Get agent details for response
details = await agent_instance_crud.get_with_details(db, instance_id=agent.id)
if details:
return build_agent_response(
agent=details["instance"],
agent_type_name=details.get("agent_type_name"),
agent_type_slug=details.get("agent_type_slug"),
project_name=details.get("project_name"),
project_slug=details.get("project_slug"),
assigned_issues_count=details.get("assigned_issues_count", 0),
)
return build_agent_response(agent)
except (NotFoundError, AuthorizationError, ValidationException):
raise
except ValueError as e:
logger.warning(f"Failed to spawn agent: {e!s}")
raise ValidationException(
message=str(e),
error_code=ErrorCode.VALIDATION_ERROR,
)
except Exception as e:
logger.error(f"Error spawning agent: {e!s}", exc_info=True)
raise
@router.get(
"/projects/{project_id}/agents",
response_model=PaginatedResponse[AgentInstanceResponse],
summary="List Project Agents",
description="List all agent instances in a project with optional filtering.",
operation_id="list_project_agents",
)
@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
async def list_project_agents(
request: Request,
project_id: UUID,
pagination: PaginationParams = Depends(),
status_filter: AgentStatus | None = Query(
None, alias="status", description="Filter by agent status"
),
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
List all agent instances in a project.
Returns a paginated list of agents with optional status filtering.
Results are ordered by creation date (newest first).
Args:
request: FastAPI request object (for rate limiting)
project_id: UUID of the project
pagination: Pagination parameters
status_filter: Optional filter by agent status
current_user: Current authenticated user
db: Database session
Returns:
PaginatedResponse[AgentInstanceResponse]: Paginated list of agents
Raises:
NotFoundError: If the project is not found
AuthorizationError: If the user lacks access to the project
"""
try:
# Verify project access
project = await verify_project_access(db, project_id, current_user)
# Get agents for the project
agents, total = await agent_instance_crud.get_by_project(
db,
project_id=project_id,
status=status_filter,
skip=pagination.offset,
limit=pagination.limit,
)
# Build response objects
agent_responses = []
for agent in agents:
# Get details for each agent (could be optimized with bulk query)
details = await agent_instance_crud.get_with_details(
db, instance_id=agent.id
)
if details:
agent_responses.append(
build_agent_response(
agent=details["instance"],
agent_type_name=details.get("agent_type_name"),
agent_type_slug=details.get("agent_type_slug"),
project_name=details.get("project_name"),
project_slug=details.get("project_slug"),
assigned_issues_count=details.get("assigned_issues_count", 0),
)
)
else:
agent_responses.append(build_agent_response(agent))
pagination_meta = create_pagination_meta(
total=total,
page=pagination.page,
limit=pagination.limit,
items_count=len(agent_responses),
)
logger.debug(
f"User {current_user.email} listed {len(agent_responses)} agents "
f"in project {project.slug}"
)
return PaginatedResponse(data=agent_responses, pagination=pagination_meta)
except (NotFoundError, AuthorizationError):
raise
except Exception as e:
logger.error(f"Error listing project agents: {e!s}", exc_info=True)
raise
@router.get(
"/projects/{project_id}/agents/{agent_id}",
response_model=AgentInstanceResponse,
summary="Get Agent Details",
description="Get detailed information about a specific agent instance.",
operation_id="get_agent",
)
@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
async def get_agent(
request: Request,
project_id: UUID,
agent_id: UUID,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Get detailed information about a specific agent instance.
Returns full agent details including related entity information
(agent type name, project name) and assigned issues count.
Args:
request: FastAPI request object (for rate limiting)
project_id: UUID of the project
agent_id: UUID of the agent instance
current_user: Current authenticated user
db: Database session
Returns:
AgentInstanceResponse: The agent instance details
Raises:
NotFoundError: If the project or agent is not found
AuthorizationError: If the user lacks access to the project
"""
try:
# Verify project access
await verify_project_access(db, project_id, current_user)
# Get agent with full details
details = await agent_instance_crud.get_with_details(db, instance_id=agent_id)
if not details:
raise NotFoundError(
message=f"Agent {agent_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
agent = details["instance"]
# Verify agent belongs to the specified project
if agent.project_id != project_id:
raise NotFoundError(
message=f"Agent {agent_id} not found in project {project_id}",
error_code=ErrorCode.NOT_FOUND,
)
logger.debug(
f"User {current_user.email} retrieved agent {agent.name} (id={agent_id})"
)
return build_agent_response(
agent=agent,
agent_type_name=details.get("agent_type_name"),
agent_type_slug=details.get("agent_type_slug"),
project_name=details.get("project_name"),
project_slug=details.get("project_slug"),
assigned_issues_count=details.get("assigned_issues_count", 0),
)
except (NotFoundError, AuthorizationError):
raise
except Exception as e:
logger.error(f"Error getting agent details: {e!s}", exc_info=True)
raise
@router.patch(
"/projects/{project_id}/agents/{agent_id}",
response_model=AgentInstanceResponse,
summary="Update Agent",
description="Update an agent instance's configuration and state.",
operation_id="update_agent",
)
@limiter.limit(f"{30 * RATE_MULTIPLIER}/minute")
async def update_agent(
request: Request,
project_id: UUID,
agent_id: UUID,
agent_in: AgentInstanceUpdate,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Update an agent instance's configuration and state.
Allows updating agent status, current task, memory, and other
configurable fields. Status transitions are validated according
to the agent lifecycle state machine.
Args:
request: FastAPI request object (for rate limiting)
project_id: UUID of the project
agent_id: UUID of the agent instance
agent_in: Agent update data
current_user: Current authenticated user
db: Database session
Returns:
AgentInstanceResponse: The updated agent instance
Raises:
NotFoundError: If the project or agent is not found
AuthorizationError: If the user lacks access to the project
ValidationException: If the status transition is invalid
"""
try:
# Verify project access
await verify_project_access(db, project_id, current_user)
# Get current agent
agent = await agent_instance_crud.get(db, id=agent_id)
if not agent:
raise NotFoundError(
message=f"Agent {agent_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
# Verify agent belongs to the specified project
if agent.project_id != project_id:
raise NotFoundError(
message=f"Agent {agent_id} not found in project {project_id}",
error_code=ErrorCode.NOT_FOUND,
)
# Validate status transition if status is being changed
if agent_in.status is not None and agent_in.status != agent.status:
validate_status_transition(agent.status, agent_in.status)
# Update the agent
updated_agent = await agent_instance_crud.update(
db, db_obj=agent, obj_in=agent_in
)
logger.info(
f"User {current_user.email} updated agent {updated_agent.name} "
f"(id={agent_id})"
)
# Get updated details
details = await agent_instance_crud.get_with_details(
db, instance_id=updated_agent.id
)
if details:
return build_agent_response(
agent=details["instance"],
agent_type_name=details.get("agent_type_name"),
agent_type_slug=details.get("agent_type_slug"),
project_name=details.get("project_name"),
project_slug=details.get("project_slug"),
assigned_issues_count=details.get("assigned_issues_count", 0),
)
return build_agent_response(updated_agent)
except (NotFoundError, AuthorizationError, ValidationException):
raise
except Exception as e:
logger.error(f"Error updating agent: {e!s}", exc_info=True)
raise
@router.post(
"/projects/{project_id}/agents/{agent_id}/pause",
response_model=AgentInstanceResponse,
summary="Pause Agent",
description="Pause an agent instance, temporarily stopping its work.",
operation_id="pause_agent",
)
@limiter.limit(f"{20 * RATE_MULTIPLIER}/minute")
async def pause_agent(
request: Request,
project_id: UUID,
agent_id: UUID,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Pause an agent instance.
Transitions the agent to PAUSED status, temporarily stopping
its work. The agent can be resumed later with the resume endpoint.
Args:
request: FastAPI request object (for rate limiting)
project_id: UUID of the project
agent_id: UUID of the agent instance
current_user: Current authenticated user
db: Database session
Returns:
AgentInstanceResponse: The paused agent instance
Raises:
NotFoundError: If the project or agent is not found
AuthorizationError: If the user lacks access to the project
ValidationException: If the agent cannot be paused from its current state
"""
try:
# Verify project access
await verify_project_access(db, project_id, current_user)
# Get current agent
agent = await agent_instance_crud.get(db, id=agent_id)
if not agent:
raise NotFoundError(
message=f"Agent {agent_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
# Verify agent belongs to the specified project
if agent.project_id != project_id:
raise NotFoundError(
message=f"Agent {agent_id} not found in project {project_id}",
error_code=ErrorCode.NOT_FOUND,
)
# Validate the transition to PAUSED
validate_status_transition(agent.status, AgentStatus.PAUSED)
# Update status to PAUSED
paused_agent = await agent_instance_crud.update_status(
db,
instance_id=agent_id,
status=AgentStatus.PAUSED,
)
if not paused_agent:
raise NotFoundError(
message=f"Agent {agent_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
logger.info(
f"User {current_user.email} paused agent {paused_agent.name} "
f"(id={agent_id})"
)
# Get updated details
details = await agent_instance_crud.get_with_details(
db, instance_id=paused_agent.id
)
if details:
return build_agent_response(
agent=details["instance"],
agent_type_name=details.get("agent_type_name"),
agent_type_slug=details.get("agent_type_slug"),
project_name=details.get("project_name"),
project_slug=details.get("project_slug"),
assigned_issues_count=details.get("assigned_issues_count", 0),
)
return build_agent_response(paused_agent)
except (NotFoundError, AuthorizationError, ValidationException):
raise
except Exception as e:
logger.error(f"Error pausing agent: {e!s}", exc_info=True)
raise
@router.post(
"/projects/{project_id}/agents/{agent_id}/resume",
response_model=AgentInstanceResponse,
summary="Resume Agent",
description="Resume a paused agent instance.",
operation_id="resume_agent",
)
@limiter.limit(f"{20 * RATE_MULTIPLIER}/minute")
async def resume_agent(
request: Request,
project_id: UUID,
agent_id: UUID,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Resume a paused agent instance.
Transitions the agent from PAUSED back to IDLE status,
allowing it to accept new work.
Args:
request: FastAPI request object (for rate limiting)
project_id: UUID of the project
agent_id: UUID of the agent instance
current_user: Current authenticated user
db: Database session
Returns:
AgentInstanceResponse: The resumed agent instance
Raises:
NotFoundError: If the project or agent is not found
AuthorizationError: If the user lacks access to the project
ValidationException: If the agent cannot be resumed from its current state
"""
try:
# Verify project access
await verify_project_access(db, project_id, current_user)
# Get current agent
agent = await agent_instance_crud.get(db, id=agent_id)
if not agent:
raise NotFoundError(
message=f"Agent {agent_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
# Verify agent belongs to the specified project
if agent.project_id != project_id:
raise NotFoundError(
message=f"Agent {agent_id} not found in project {project_id}",
error_code=ErrorCode.NOT_FOUND,
)
# Validate the transition to IDLE (resume)
validate_status_transition(agent.status, AgentStatus.IDLE)
# Update status to IDLE
resumed_agent = await agent_instance_crud.update_status(
db,
instance_id=agent_id,
status=AgentStatus.IDLE,
)
if not resumed_agent:
raise NotFoundError(
message=f"Agent {agent_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
logger.info(
f"User {current_user.email} resumed agent {resumed_agent.name} "
f"(id={agent_id})"
)
# Get updated details
details = await agent_instance_crud.get_with_details(
db, instance_id=resumed_agent.id
)
if details:
return build_agent_response(
agent=details["instance"],
agent_type_name=details.get("agent_type_name"),
agent_type_slug=details.get("agent_type_slug"),
project_name=details.get("project_name"),
project_slug=details.get("project_slug"),
assigned_issues_count=details.get("assigned_issues_count", 0),
)
return build_agent_response(resumed_agent)
except (NotFoundError, AuthorizationError, ValidationException):
raise
except Exception as e:
logger.error(f"Error resuming agent: {e!s}", exc_info=True)
raise
@router.delete(
"/projects/{project_id}/agents/{agent_id}",
response_model=MessageResponse,
summary="Terminate Agent",
description="Terminate an agent instance, permanently stopping it.",
operation_id="terminate_agent",
)
@limiter.limit(f"{10 * RATE_MULTIPLIER}/minute")
async def terminate_agent(
request: Request,
project_id: UUID,
agent_id: UUID,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Terminate an agent instance.
Permanently terminates the agent, setting its status to TERMINATED.
This action cannot be undone - a new agent must be spawned if needed.
The agent's session and current task are cleared.
Args:
request: FastAPI request object (for rate limiting)
project_id: UUID of the project
agent_id: UUID of the agent instance
current_user: Current authenticated user
db: Database session
Returns:
MessageResponse: Confirmation message
Raises:
NotFoundError: If the project or agent is not found
AuthorizationError: If the user lacks access to the project
ValidationException: If the agent is already terminated
"""
try:
# Verify project access
await verify_project_access(db, project_id, current_user)
# Get current agent
agent = await agent_instance_crud.get(db, id=agent_id)
if not agent:
raise NotFoundError(
message=f"Agent {agent_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
# Verify agent belongs to the specified project
if agent.project_id != project_id:
raise NotFoundError(
message=f"Agent {agent_id} not found in project {project_id}",
error_code=ErrorCode.NOT_FOUND,
)
# Check if already terminated
if agent.status == AgentStatus.TERMINATED:
raise ValidationException(
message="Agent is already terminated",
error_code=ErrorCode.VALIDATION_ERROR,
field="status",
)
# Validate the transition to TERMINATED
validate_status_transition(agent.status, AgentStatus.TERMINATED)
agent_name = agent.name
# Terminate the agent
terminated_agent = await agent_instance_crud.terminate(
db, instance_id=agent_id
)
if not terminated_agent:
raise NotFoundError(
message=f"Agent {agent_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
logger.info(
f"User {current_user.email} terminated agent {agent_name} "
f"(id={agent_id})"
)
return MessageResponse(
success=True,
message=f"Agent '{agent_name}' has been terminated",
)
except (NotFoundError, AuthorizationError, ValidationException):
raise
except Exception as e:
logger.error(f"Error terminating agent: {e!s}", exc_info=True)
raise
@router.get(
"/projects/{project_id}/agents/{agent_id}/metrics",
response_model=AgentInstanceMetrics,
summary="Get Agent Metrics",
description="Get usage metrics for a specific agent instance.",
operation_id="get_agent_metrics",
)
@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
async def get_agent_metrics(
request: Request,
project_id: UUID,
agent_id: UUID,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Get usage metrics for a specific agent instance.
Returns metrics including tasks completed, tokens used,
and cost incurred for the specified agent.
Args:
request: FastAPI request object (for rate limiting)
project_id: UUID of the project
agent_id: UUID of the agent instance
current_user: Current authenticated user
db: Database session
Returns:
AgentInstanceMetrics: Agent usage metrics
Raises:
NotFoundError: If the project or agent is not found
AuthorizationError: If the user lacks access to the project
"""
try:
# Verify project access
await verify_project_access(db, project_id, current_user)
# Get agent
agent = await agent_instance_crud.get(db, id=agent_id)
if not agent:
raise NotFoundError(
message=f"Agent {agent_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
# Verify agent belongs to the specified project
if agent.project_id != project_id:
raise NotFoundError(
message=f"Agent {agent_id} not found in project {project_id}",
error_code=ErrorCode.NOT_FOUND,
)
# Calculate metrics for this single agent
# For a single agent, we report its individual metrics
is_active = agent.status == AgentStatus.WORKING
is_idle = agent.status == AgentStatus.IDLE
logger.debug(
f"User {current_user.email} retrieved metrics for agent {agent.name} "
f"(id={agent_id})"
)
return AgentInstanceMetrics(
total_instances=1,
active_instances=1 if is_active else 0,
idle_instances=1 if is_idle else 0,
total_tasks_completed=agent.tasks_completed,
total_tokens_used=agent.tokens_used,
total_cost_incurred=agent.cost_incurred,
)
except (NotFoundError, AuthorizationError):
raise
except Exception as e:
logger.error(f"Error getting agent metrics: {e!s}", exc_info=True)
raise
@router.get(
"/projects/{project_id}/agents/metrics",
response_model=AgentInstanceMetrics,
summary="Get Project Agent Metrics",
description="Get aggregated usage metrics for all agents in a project.",
operation_id="get_project_agent_metrics",
)
@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
async def get_project_agent_metrics(
request: Request,
project_id: UUID,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Get aggregated usage metrics for all agents in a project.
Returns aggregated metrics across all agents including total
tasks completed, tokens used, and cost incurred.
Args:
request: FastAPI request object (for rate limiting)
project_id: UUID of the project
current_user: Current authenticated user
db: Database session
Returns:
AgentInstanceMetrics: Aggregated project agent metrics
Raises:
NotFoundError: If the project is not found
AuthorizationError: If the user lacks access to the project
"""
try:
# Verify project access
project = await verify_project_access(db, project_id, current_user)
# Get aggregated metrics for the project
metrics = await agent_instance_crud.get_project_metrics(
db, project_id=project_id
)
logger.debug(
f"User {current_user.email} retrieved project metrics for {project.slug}"
)
return AgentInstanceMetrics(
total_instances=metrics["total_instances"],
active_instances=metrics["active_instances"],
idle_instances=metrics["idle_instances"],
total_tasks_completed=metrics["total_tasks_completed"],
total_tokens_used=metrics["total_tokens_used"],
total_cost_incurred=metrics["total_cost_incurred"],
)
except (NotFoundError, AuthorizationError):
raise
except Exception as e:
logger.error(f"Error getting project agent metrics: {e!s}", exc_info=True)
raise

48
backend/app/api/routes/events.py
View File

@@ -17,6 +17,7 @@ Features:
import asyncio
import json
import logging
from typing import TYPE_CHECKING
from uuid import UUID
from fastapi import APIRouter, Depends, Header, Request
@@ -26,12 +27,16 @@ from sse_starlette.sse import EventSourceResponse
from app.api.dependencies.auth import get_current_user
from app.api.dependencies.event_bus import get_event_bus
from app.core.database import get_db
from app.core.exceptions import AuthorizationError
from app.models.user import User
from app.schemas.errors import ErrorCode
from app.schemas.events import EventType
from app.services.event_bus import EventBus
if TYPE_CHECKING:
from sqlalchemy.ext.asyncio import AsyncSession
logger = logging.getLogger(__name__)
router = APIRouter()
@@ -44,33 +49,44 @@ KEEPALIVE_INTERVAL = 30
async def check_project_access(
project_id: UUID,
user: User,
db: "AsyncSession",
) -> bool:
"""
Check if a user has access to a project's events.
This is a placeholder implementation that will be replaced
with actual project authorization logic once the Project model
is implemented. Currently allows access for all authenticated users.
Authorization rules:
- Superusers can access all projects
- Project owners can access their own projects
Args:
project_id: The project to check access for
user: The authenticated user
db: Database session for project lookup
Returns:
bool: True if user has access, False otherwise
TODO: Implement actual project authorization
- Check if user owns the project
- Check if user is a member of the project
- Check project visibility settings
"""
# Placeholder: Allow all authenticated users for now
# This will be replaced with actual project ownership/membership check
# Superusers can access all projects
if user.is_superuser:
logger.debug(
f"Project access granted for superuser {user.id} on project {project_id}"
)
return True
# Check if user owns the project
from app.crud.syndarix import project as project_crud
project = await project_crud.get(db, id=project_id)
if not project:
logger.debug(f"Project {project_id} not found for access check")
return False
has_access = bool(project.owner_id == user.id)
logger.debug(
f"Project access check for user {user.id} on project {project_id} "
"(placeholder: allowing all authenticated users)"
f"Project access {'granted' if has_access else 'denied'} "
f"for user {user.id} on project {project_id} (owner: {project.owner_id})"
)
return True
return has_access
async def event_generator(
@@ -176,6 +192,7 @@ async def stream_project_events(
project_id: UUID,
current_user: User = Depends(get_current_user),
event_bus: EventBus = Depends(get_event_bus),
db: "AsyncSession" = Depends(get_db),
last_event_id: str | None = Header(None, alias="Last-Event-ID"),
):
"""
@@ -197,7 +214,7 @@ async def stream_project_events(
)
# Check project access
has_access = await check_project_access(project_id, current_user)
has_access = await check_project_access(project_id, current_user, db)
if not has_access:
raise AuthorizationError(
message=f"You don't have access to project {project_id}",
@@ -244,6 +261,7 @@ async def send_test_event(
project_id: UUID,
current_user: User = Depends(get_current_user),
event_bus: EventBus = Depends(get_event_bus),
db: "AsyncSession" = Depends(get_db),
):
"""
Send a test event to the project's event stream.
@@ -251,7 +269,7 @@ async def send_test_event(
This is useful for testing SSE connections during development.
"""
# Check project access
has_access = await check_project_access(project_id, current_user)
has_access = await check_project_access(project_id, current_user, db)
if not has_access:
raise AuthorizationError(
message=f"You don't have access to project {project_id}",

939
backend/app/api/routes/issues.py Normal file
View File

@@ -0,0 +1,939 @@
# app/api/routes/issues.py
"""
Issue CRUD API endpoints for Syndarix projects.
Provides endpoints for managing issues within projects, including:
- Create, read, update, delete operations
- Filtering by status, priority, labels, sprint, assigned agent
- Search across title and body
- Assignment to agents
- External issue tracker sync triggers
"""
import logging
import os
from typing import Any
from uuid import UUID
from fastapi import APIRouter, Depends, Query, Request, status
from slowapi import Limiter
from slowapi.util import get_remote_address
from sqlalchemy.ext.asyncio import AsyncSession
from app.api.dependencies.auth import get_current_user
from app.core.database import get_db
from app.core.exceptions import (
AuthorizationError,
NotFoundError,
ValidationException,
)
from app.crud.syndarix.agent_instance import agent_instance as agent_instance_crud
from app.crud.syndarix.issue import issue as issue_crud
from app.crud.syndarix.project import project as project_crud
from app.crud.syndarix.sprint import sprint as sprint_crud
from app.models.syndarix.enums import IssuePriority, IssueStatus, SyncStatus
from app.models.user import User
from app.schemas.common import (
MessageResponse,
PaginatedResponse,
PaginationParams,
SortOrder,
create_pagination_meta,
)
from app.schemas.errors import ErrorCode
from app.schemas.syndarix.issue import (
IssueAssign,
IssueCreate,
IssueResponse,
IssueStats,
IssueUpdate,
)
router = APIRouter()
logger = logging.getLogger(__name__)
# Initialize limiter for this router
limiter = Limiter(key_func=get_remote_address)
# Use higher rate limits in test environment
IS_TEST = os.getenv("IS_TEST", "False") == "True"
RATE_MULTIPLIER = 100 if IS_TEST else 1
async def verify_project_ownership(
db: AsyncSession,
project_id: UUID,
user: User,
) -> None:
"""
Verify that the user owns the project or is a superuser.
Args:
db: Database session
project_id: Project UUID to verify
user: Current authenticated user
Raises:
NotFoundError: If project does not exist
AuthorizationError: If user does not own the project
"""
project = await project_crud.get(db, id=project_id)
if not project:
raise NotFoundError(
message=f"Project {project_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
if not user.is_superuser and project.owner_id != user.id:
raise AuthorizationError(
message="You do not have access to this project",
error_code=ErrorCode.INSUFFICIENT_PERMISSIONS,
)
def _build_issue_response(
issue: Any,
project_name: str | None = None,
project_slug: str | None = None,
sprint_name: str | None = None,
assigned_agent_type_name: str | None = None,
) -> IssueResponse:
"""
Build an IssueResponse from an Issue model instance.
Args:
issue: Issue model instance
project_name: Optional project name from relationship
project_slug: Optional project slug from relationship
sprint_name: Optional sprint name from relationship
assigned_agent_type_name: Optional agent type name from relationship
Returns:
IssueResponse schema instance
"""
return IssueResponse(
id=issue.id,
project_id=issue.project_id,
title=issue.title,
body=issue.body,
status=issue.status,
priority=issue.priority,
labels=issue.labels or [],
assigned_agent_id=issue.assigned_agent_id,
human_assignee=issue.human_assignee,
sprint_id=issue.sprint_id,
story_points=issue.story_points,
external_tracker_type=issue.external_tracker_type,
external_issue_id=issue.external_issue_id,
remote_url=issue.remote_url,
external_issue_number=issue.external_issue_number,
sync_status=issue.sync_status,
last_synced_at=issue.last_synced_at,
external_updated_at=issue.external_updated_at,
closed_at=issue.closed_at,
created_at=issue.created_at,
updated_at=issue.updated_at,
project_name=project_name,
project_slug=project_slug,
sprint_name=sprint_name,
assigned_agent_type_name=assigned_agent_type_name,
)
# ===== Issue CRUD Endpoints =====
@router.post(
"/projects/{project_id}/issues",
response_model=IssueResponse,
status_code=status.HTTP_201_CREATED,
summary="Create Issue",
description="Create a new issue in a project",
operation_id="create_issue",
)
@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
async def create_issue(
request: Request,
project_id: UUID,
issue_in: IssueCreate,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Create a new issue within a project.
The user must own the project or be a superuser.
The project_id in the path takes precedence over any project_id in the body.
Args:
request: FastAPI request object (for rate limiting)
project_id: UUID of the project to create the issue in
issue_in: Issue creation data
current_user: Authenticated user
db: Database session
Returns:
Created issue with full details
Raises:
NotFoundError: If project not found
AuthorizationError: If user lacks access
ValidationException: If assigned agent not in project
"""
# Verify project access
await verify_project_ownership(db, project_id, current_user)
# Override project_id from path
issue_in.project_id = project_id
# Validate assigned agent if provided
if issue_in.assigned_agent_id:
agent = await agent_instance_crud.get(db, id=issue_in.assigned_agent_id)
if not agent:
raise NotFoundError(
message=f"Agent instance {issue_in.assigned_agent_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
if agent.project_id != project_id:
raise ValidationException(
message="Agent instance does not belong to this project",
error_code=ErrorCode.VALIDATION_ERROR,
field="assigned_agent_id",
)
# Validate sprint if provided (IDOR prevention)
if issue_in.sprint_id:
sprint = await sprint_crud.get(db, id=issue_in.sprint_id)
if not sprint:
raise NotFoundError(
message=f"Sprint {issue_in.sprint_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
if sprint.project_id != project_id:
raise ValidationException(
message="Sprint does not belong to this project",
error_code=ErrorCode.VALIDATION_ERROR,
field="sprint_id",
)
try:
issue = await issue_crud.create(db, obj_in=issue_in)
logger.info(
f"User {current_user.email} created issue '{issue.title}' "
f"in project {project_id}"
)
# Get project details for response
project = await project_crud.get(db, id=project_id)
return _build_issue_response(
issue,
project_name=project.name if project else None,
project_slug=project.slug if project else None,
)
except ValueError as e:
logger.warning(f"Failed to create issue: {e!s}")
raise ValidationException(
message=str(e),
error_code=ErrorCode.VALIDATION_ERROR,
)
except Exception as e:
logger.error(f"Error creating issue: {e!s}", exc_info=True)
raise
@router.get(
"/projects/{project_id}/issues",
response_model=PaginatedResponse[IssueResponse],
summary="List Issues",
description="Get paginated list of issues in a project with filtering",
operation_id="list_issues",
)
@limiter.limit(f"{120 * RATE_MULTIPLIER}/minute")
async def list_issues(
request: Request,
project_id: UUID,
pagination: PaginationParams = Depends(),
status_filter: IssueStatus | None = Query(
None, alias="status", description="Filter by issue status"
),
priority: IssuePriority | None = Query(None, description="Filter by priority"),
labels: list[str] | None = Query(
None, description="Filter by labels (comma-separated)"
),
sprint_id: UUID | None = Query(None, description="Filter by sprint ID"),
assigned_agent_id: UUID | None = Query(
None, description="Filter by assigned agent ID"
),
sync_status: SyncStatus | None = Query(
None, description="Filter by sync status"
),
search: str | None = Query(
None, min_length=1, max_length=100, description="Search in title and body"
),
sort_by: str = Query(
"created_at",
description="Field to sort by (created_at, updated_at, priority, status, title)",
),
sort_order: SortOrder = Query(SortOrder.DESC, description="Sort order"),
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
List issues in a project with comprehensive filtering options.
Supports filtering by:
- status: Issue status (open, in_progress, in_review, blocked, closed)
- priority: Issue priority (low, medium, high, critical)
- labels: Match issues containing any of the provided labels
- sprint_id: Issues in a specific sprint
- assigned_agent_id: Issues assigned to a specific agent
- sync_status: External tracker sync status
- search: Full-text search in title and body
Args:
request: FastAPI request object
project_id: Project UUID
pagination: Pagination parameters
status_filter: Optional status filter
priority: Optional priority filter
labels: Optional labels filter
sprint_id: Optional sprint filter
assigned_agent_id: Optional agent assignment filter
sync_status: Optional sync status filter
search: Optional search query
sort_by: Field to sort by
sort_order: Sort direction
current_user: Authenticated user
db: Database session
Returns:
Paginated list of issues matching filters
"""
# Verify project access
await verify_project_ownership(db, project_id, current_user)
try:
# Get filtered issues
issues, total = await issue_crud.get_by_project(
db,
project_id=project_id,
status=status_filter,
priority=priority,
sprint_id=sprint_id,
assigned_agent_id=assigned_agent_id,
labels=labels,
search=search,
skip=pagination.offset,
limit=pagination.limit,
sort_by=sort_by,
sort_order=sort_order.value,
)
# Build response objects
issue_responses = [_build_issue_response(issue) for issue in issues]
pagination_meta = create_pagination_meta(
total=total,
page=pagination.page,
limit=pagination.limit,
items_count=len(issue_responses),
)
return PaginatedResponse(data=issue_responses, pagination=pagination_meta)
except Exception as e:
logger.error(
f"Error listing issues for project {project_id}: {e!s}", exc_info=True
)
raise
@router.get(
"/projects/{project_id}/issues/{issue_id}",
response_model=IssueResponse,
summary="Get Issue",
description="Get detailed information about a specific issue",
operation_id="get_issue",
)
@limiter.limit(f"{120 * RATE_MULTIPLIER}/minute")
async def get_issue(
request: Request,
project_id: UUID,
issue_id: UUID,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Get detailed information about a specific issue.
Returns the issue with expanded relationship data including
project name, sprint name, and assigned agent type name.
Args:
request: FastAPI request object
project_id: Project UUID
issue_id: Issue UUID
current_user: Authenticated user
db: Database session
Returns:
Issue details with relationship data
Raises:
NotFoundError: If project or issue not found
AuthorizationError: If user lacks access
"""
# Verify project access
await verify_project_ownership(db, project_id, current_user)
# Get issue with details
issue_data = await issue_crud.get_with_details(db, issue_id=issue_id)
if not issue_data:
raise NotFoundError(
message=f"Issue {issue_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
issue = issue_data["issue"]
# Verify issue belongs to the project
if issue.project_id != project_id:
raise NotFoundError(
message=f"Issue {issue_id} not found in project {project_id}",
error_code=ErrorCode.NOT_FOUND,
)
return _build_issue_response(
issue,
project_name=issue_data.get("project_name"),
project_slug=issue_data.get("project_slug"),
sprint_name=issue_data.get("sprint_name"),
assigned_agent_type_name=issue_data.get("assigned_agent_type_name"),
)
@router.patch(
"/projects/{project_id}/issues/{issue_id}",
response_model=IssueResponse,
summary="Update Issue",
description="Update an existing issue",
operation_id="update_issue",
)
@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
async def update_issue(
request: Request,
project_id: UUID,
issue_id: UUID,
issue_in: IssueUpdate,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Update an existing issue.
All fields are optional - only provided fields will be updated.
Validates that assigned agent belongs to the same project.
Args:
request: FastAPI request object
project_id: Project UUID
issue_id: Issue UUID
issue_in: Fields to update
current_user: Authenticated user
db: Database session
Returns:
Updated issue details
Raises:
NotFoundError: If project or issue not found
AuthorizationError: If user lacks access
ValidationException: If validation fails
"""
# Verify project access
await verify_project_ownership(db, project_id, current_user)
# Get existing issue
issue = await issue_crud.get(db, id=issue_id)
if not issue:
raise NotFoundError(
message=f"Issue {issue_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
# Verify issue belongs to the project
if issue.project_id != project_id:
raise NotFoundError(
message=f"Issue {issue_id} not found in project {project_id}",
error_code=ErrorCode.NOT_FOUND,
)
# Validate assigned agent if being updated
if issue_in.assigned_agent_id is not None:
agent = await agent_instance_crud.get(db, id=issue_in.assigned_agent_id)
if not agent:
raise NotFoundError(
message=f"Agent instance {issue_in.assigned_agent_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
if agent.project_id != project_id:
raise ValidationException(
message="Agent instance does not belong to this project",
error_code=ErrorCode.VALIDATION_ERROR,
field="assigned_agent_id",
)
# Validate sprint if being updated (IDOR prevention)
if issue_in.sprint_id is not None:
sprint = await sprint_crud.get(db, id=issue_in.sprint_id)
if not sprint:
raise NotFoundError(
message=f"Sprint {issue_in.sprint_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
if sprint.project_id != project_id:
raise ValidationException(
message="Sprint does not belong to this project",
error_code=ErrorCode.VALIDATION_ERROR,
field="sprint_id",
)
try:
updated_issue = await issue_crud.update(db, db_obj=issue, obj_in=issue_in)
logger.info(
f"User {current_user.email} updated issue {issue_id} in project {project_id}"
)
# Get full details for response
issue_data = await issue_crud.get_with_details(db, issue_id=issue_id)
return _build_issue_response(
updated_issue,
project_name=issue_data.get("project_name") if issue_data else None,
project_slug=issue_data.get("project_slug") if issue_data else None,
sprint_name=issue_data.get("sprint_name") if issue_data else None,
assigned_agent_type_name=issue_data.get("assigned_agent_type_name")
if issue_data
else None,
)
except ValueError as e:
logger.warning(f"Failed to update issue {issue_id}: {e!s}")
raise ValidationException(
message=str(e),
error_code=ErrorCode.VALIDATION_ERROR,
)
except Exception as e:
logger.error(f"Error updating issue {issue_id}: {e!s}", exc_info=True)
raise
@router.delete(
"/projects/{project_id}/issues/{issue_id}",
response_model=MessageResponse,
summary="Delete Issue",
description="Soft delete an issue",
operation_id="delete_issue",
)
@limiter.limit(f"{30 * RATE_MULTIPLIER}/minute")
async def delete_issue(
request: Request,
project_id: UUID,
issue_id: UUID,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Soft delete an issue.
The issue will be marked as deleted but retained in the database.
This preserves historical data and allows potential recovery.
Args:
request: FastAPI request object
project_id: Project UUID
issue_id: Issue UUID
current_user: Authenticated user
db: Database session
Returns:
Success message
Raises:
NotFoundError: If project or issue not found
AuthorizationError: If user lacks access
"""
# Verify project access
await verify_project_ownership(db, project_id, current_user)
# Get existing issue
issue = await issue_crud.get(db, id=issue_id)
if not issue:
raise NotFoundError(
message=f"Issue {issue_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
# Verify issue belongs to the project
if issue.project_id != project_id:
raise NotFoundError(
message=f"Issue {issue_id} not found in project {project_id}",
error_code=ErrorCode.NOT_FOUND,
)
try:
await issue_crud.soft_delete(db, id=issue_id)
logger.info(
f"User {current_user.email} deleted issue {issue_id} "
f"('{issue.title}') from project {project_id}"
)
return MessageResponse(
success=True,
message=f"Issue '{issue.title}' has been deleted",
)
except Exception as e:
logger.error(f"Error deleting issue {issue_id}: {e!s}", exc_info=True)
raise
# ===== Issue Assignment Endpoint =====
@router.post(
"/projects/{project_id}/issues/{issue_id}/assign",
response_model=IssueResponse,
summary="Assign Issue",
description="Assign an issue to an agent or human",
operation_id="assign_issue",
)
@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
async def assign_issue(
request: Request,
project_id: UUID,
issue_id: UUID,
assignment: IssueAssign,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Assign an issue to an agent or human.
Only one type of assignment is allowed at a time:
- assigned_agent_id: Assign to an AI agent instance
- human_assignee: Assign to a human (name/email string)
To unassign, pass both as null/None.
Args:
request: FastAPI request object
project_id: Project UUID
issue_id: Issue UUID
assignment: Assignment data
current_user: Authenticated user
db: Database session
Returns:
Updated issue with assignment
Raises:
NotFoundError: If project, issue, or agent not found
AuthorizationError: If user lacks access
ValidationException: If agent not in project
"""
# Verify project access
await verify_project_ownership(db, project_id, current_user)
# Get existing issue
issue = await issue_crud.get(db, id=issue_id)
if not issue:
raise NotFoundError(
message=f"Issue {issue_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
# Verify issue belongs to the project
if issue.project_id != project_id:
raise NotFoundError(
message=f"Issue {issue_id} not found in project {project_id}",
error_code=ErrorCode.NOT_FOUND,
)
# Process assignment based on type
if assignment.assigned_agent_id:
# Validate agent exists and belongs to project
agent = await agent_instance_crud.get(db, id=assignment.assigned_agent_id)
if not agent:
raise NotFoundError(
message=f"Agent instance {assignment.assigned_agent_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
if agent.project_id != project_id:
raise ValidationException(
message="Agent instance does not belong to this project",
error_code=ErrorCode.VALIDATION_ERROR,
field="assigned_agent_id",
)
updated_issue = await issue_crud.assign_to_agent(
db, issue_id=issue_id, agent_id=assignment.assigned_agent_id
)
logger.info(
f"User {current_user.email} assigned issue {issue_id} to agent {agent.name}"
)
elif assignment.human_assignee:
updated_issue = await issue_crud.assign_to_human(
db, issue_id=issue_id, human_assignee=assignment.human_assignee
)
logger.info(
f"User {current_user.email} assigned issue {issue_id} "
f"to human '{assignment.human_assignee}'"
)
else:
# Unassign - clear both agent and human
updated_issue = await issue_crud.assign_to_agent(
db, issue_id=issue_id, agent_id=None
)
logger.info(
f"User {current_user.email} unassigned issue {issue_id}"
)
if not updated_issue:
raise NotFoundError(
message=f"Issue {issue_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
# Get full details for response
issue_data = await issue_crud.get_with_details(db, issue_id=issue_id)
return _build_issue_response(
updated_issue,
project_name=issue_data.get("project_name") if issue_data else None,
project_slug=issue_data.get("project_slug") if issue_data else None,
sprint_name=issue_data.get("sprint_name") if issue_data else None,
assigned_agent_type_name=issue_data.get("assigned_agent_type_name")
if issue_data
else None,
)
@router.delete(
"/projects/{project_id}/issues/{issue_id}/assignment",
response_model=IssueResponse,
summary="Unassign Issue",
description="""
Remove agent/human assignment from an issue.
**Authentication**: Required (Bearer token)
**Authorization**: Project owner or superuser
This clears both agent and human assignee fields.
**Rate Limit**: 60 requests/minute
""",
operation_id="unassign_issue",
)
@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
async def unassign_issue(
request: Request,
project_id: UUID,
issue_id: UUID,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Remove assignment from an issue.
Clears both assigned_agent_id and human_assignee fields.
"""
# Verify project access
await verify_project_ownership(db, project_id, current_user)
# Get existing issue
issue = await issue_crud.get(db, id=issue_id)
if not issue:
raise NotFoundError(
message=f"Issue {issue_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
# Verify issue belongs to project (IDOR prevention)
if issue.project_id != project_id:
raise NotFoundError(
message=f"Issue {issue_id} not found in project {project_id}",
error_code=ErrorCode.NOT_FOUND,
)
# Unassign the issue
updated_issue = await issue_crud.unassign(db, issue_id=issue_id)
if not updated_issue:
raise NotFoundError(
message=f"Issue {issue_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
logger.info(f"User {current_user.email} unassigned issue {issue_id}")
# Get full details for response
issue_data = await issue_crud.get_with_details(db, issue_id=issue_id)
return _build_issue_response(
updated_issue,
project_name=issue_data.get("project_name") if issue_data else None,
project_slug=issue_data.get("project_slug") if issue_data else None,
sprint_name=issue_data.get("sprint_name") if issue_data else None,
assigned_agent_type_name=issue_data.get("assigned_agent_type_name")
if issue_data
else None,
)
# ===== Issue Sync Endpoint =====
@router.post(
"/projects/{project_id}/issues/{issue_id}/sync",
response_model=MessageResponse,
summary="Trigger Issue Sync",
description="Trigger synchronization with external issue tracker",
operation_id="sync_issue",
)
@limiter.limit(f"{30 * RATE_MULTIPLIER}/minute")
async def sync_issue(
request: Request,
project_id: UUID,
issue_id: UUID,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Trigger synchronization of an issue with its external tracker.
This endpoint queues a sync task for the issue. The actual synchronization
happens asynchronously via Celery.
Prerequisites:
- Issue must have external_tracker_type configured
- Project must have integration settings for the tracker
Args:
request: FastAPI request object
project_id: Project UUID
issue_id: Issue UUID
current_user: Authenticated user
db: Database session
Returns:
Message indicating sync has been triggered
Raises:
NotFoundError: If project or issue not found
AuthorizationError: If user lacks access
ValidationException: If issue has no external tracker
"""
# Verify project access
await verify_project_ownership(db, project_id, current_user)
# Get existing issue
issue = await issue_crud.get(db, id=issue_id)
if not issue:
raise NotFoundError(
message=f"Issue {issue_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
# Verify issue belongs to the project
if issue.project_id != project_id:
raise NotFoundError(
message=f"Issue {issue_id} not found in project {project_id}",
error_code=ErrorCode.NOT_FOUND,
)
# Check if issue has external tracker configured
if not issue.external_tracker_type:
raise ValidationException(
message="Issue does not have an external tracker configured",
error_code=ErrorCode.VALIDATION_ERROR,
field="external_tracker_type",
)
# Update sync status to pending
await issue_crud.update_sync_status(
db,
issue_id=issue_id,
sync_status=SyncStatus.PENDING,
)
# TODO: Queue Celery task for actual sync
# When Celery is set up, this will be:
# from app.tasks.sync import sync_issue_task
# sync_issue_task.delay(str(issue_id))
logger.info(
f"User {current_user.email} triggered sync for issue {issue_id} "
f"(tracker: {issue.external_tracker_type})"
)
return MessageResponse(
success=True,
message=f"Sync triggered for issue '{issue.title}'. "
f"Status will update when complete.",
)
# ===== Issue Statistics Endpoint =====
@router.get(
"/projects/{project_id}/issues/stats",
response_model=IssueStats,
summary="Get Issue Statistics",
description="Get aggregated issue statistics for a project",
operation_id="get_issue_stats",
)
@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
async def get_issue_stats(
request: Request,
project_id: UUID,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Get aggregated statistics for issues in a project.
Returns counts by status and priority, along with story point totals.
Args:
request: FastAPI request object
project_id: Project UUID
current_user: Authenticated user
db: Database session
Returns:
Issue statistics including counts by status/priority and story points
Raises:
NotFoundError: If project not found
AuthorizationError: If user lacks access
"""
# Verify project access
await verify_project_ownership(db, project_id, current_user)
try:
stats = await issue_crud.get_project_stats(db, project_id=project_id)
return IssueStats(**stats)
except Exception as e:
logger.error(
f"Error getting issue stats for project {project_id}: {e!s}",
exc_info=True,
)
raise

651
backend/app/api/routes/projects.py Normal file
View File

@@ -0,0 +1,651 @@
# app/api/routes/projects.py
"""
Project management API endpoints for Syndarix.
These endpoints allow users to manage their AI-powered software consulting projects.
Users can create, read, update, and manage the lifecycle of their projects.
"""
import logging
import os
from typing import Any
from uuid import UUID
from fastapi import APIRouter, Depends, Query, Request, status
from slowapi import Limiter
from slowapi.util import get_remote_address
from sqlalchemy.ext.asyncio import AsyncSession
from app.api.dependencies.auth import get_current_user
from app.core.database import get_db
from app.core.exceptions import (
AuthorizationError,
DuplicateError,
ErrorCode,
NotFoundError,
ValidationException,
)
from app.crud.syndarix.project import project as project_crud
from app.models.syndarix.enums import ProjectStatus
from app.models.user import User
from app.schemas.common import (
MessageResponse,
PaginatedResponse,
PaginationParams,
create_pagination_meta,
)
from app.schemas.syndarix.project import (
ProjectCreate,
ProjectResponse,
ProjectUpdate,
)
router = APIRouter()
logger = logging.getLogger(__name__)
# Initialize rate limiter
limiter = Limiter(key_func=get_remote_address)
# Use higher rate limits in test environment
IS_TEST = os.getenv("IS_TEST", "False") == "True"
RATE_MULTIPLIER = 100 if IS_TEST else 1
def _build_project_response(project_data: dict[str, Any]) -> ProjectResponse:
"""
Build a ProjectResponse from project data dictionary.
Args:
project_data: Dictionary containing project and related counts
Returns:
ProjectResponse with all fields populated
"""
project = project_data["project"]
return ProjectResponse(
id=project.id,
name=project.name,
slug=project.slug,
description=project.description,
autonomy_level=project.autonomy_level,
status=project.status,
settings=project.settings,
owner_id=project.owner_id,
created_at=project.created_at,
updated_at=project.updated_at,
agent_count=project_data.get("agent_count", 0),
issue_count=project_data.get("issue_count", 0),
active_sprint_name=project_data.get("active_sprint_name"),
)
def _check_project_ownership(project: Any, current_user: User) -> None:
"""
Check if the current user owns the project or is a superuser.
Args:
project: The project to check ownership of
current_user: The authenticated user
Raises:
AuthorizationError: If user doesn't own the project and isn't a superuser
"""
if not current_user.is_superuser and project.owner_id != current_user.id:
raise AuthorizationError(
message="You do not have permission to access this project",
error_code=ErrorCode.INSUFFICIENT_PERMISSIONS,
)
# =============================================================================
# Project CRUD Endpoints
# =============================================================================
@router.post(
"",
response_model=ProjectResponse,
status_code=status.HTTP_201_CREATED,
summary="Create Project",
description="""
Create a new project for the current user.
The project will be owned by the authenticated user.
A unique slug is required for URL-friendly project identification.
**Rate Limit**: 10 requests/minute
""",
operation_id="create_project",
)
@limiter.limit(f"{10 * RATE_MULTIPLIER}/minute")
async def create_project(
request: Request,
project_in: ProjectCreate,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Create a new project.
The authenticated user becomes the owner of the project.
"""
try:
# Set the owner to the current user
project_data = ProjectCreate(
name=project_in.name,
slug=project_in.slug,
description=project_in.description,
autonomy_level=project_in.autonomy_level,
status=project_in.status,
settings=project_in.settings,
owner_id=current_user.id,
)
project = await project_crud.create(db, obj_in=project_data)
logger.info(f"User {current_user.email} created project {project.slug}")
return ProjectResponse(
id=project.id,
name=project.name,
slug=project.slug,
description=project.description,
autonomy_level=project.autonomy_level,
status=project.status,
settings=project.settings,
owner_id=project.owner_id,
created_at=project.created_at,
updated_at=project.updated_at,
agent_count=0,
issue_count=0,
active_sprint_name=None,
)
except ValueError as e:
error_msg = str(e)
if "already exists" in error_msg.lower():
logger.warning(f"Duplicate project slug attempted: {project_in.slug}")
raise DuplicateError(
message=error_msg,
error_code=ErrorCode.DUPLICATE_ENTRY,
field="slug",
)
logger.error(f"Error creating project: {error_msg}", exc_info=True)
raise
except Exception as e:
logger.error(f"Unexpected error creating project: {e!s}", exc_info=True)
raise
@router.get(
"",
response_model=PaginatedResponse[ProjectResponse],
summary="List Projects",
description="""
List projects for the current user with filtering and pagination.
Regular users see only their own projects.
Superusers can see all projects by setting `all_projects=true`.
**Rate Limit**: 30 requests/minute
""",
operation_id="list_projects",
)
@limiter.limit(f"{30 * RATE_MULTIPLIER}/minute")
async def list_projects(
request: Request,
pagination: PaginationParams = Depends(),
status_filter: ProjectStatus | None = Query(
None, alias="status", description="Filter by project status"
),
search: str | None = Query(None, description="Search by name, slug, or description"),
all_projects: bool = Query(
False, description="Show all projects (superuser only)"
),
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
List projects with filtering, search, and pagination.
Regular users only see their own projects.
Superusers can view all projects if all_projects is true.
"""
try:
# Determine owner filter based on user role and request
owner_id = None if (current_user.is_superuser and all_projects) else current_user.id
projects_data, total = await project_crud.get_multi_with_counts(
db,
skip=pagination.offset,
limit=pagination.limit,
status=status_filter,
owner_id=owner_id,
search=search,
)
# Build response objects
project_responses = [_build_project_response(data) for data in projects_data]
pagination_meta = create_pagination_meta(
total=total,
page=pagination.page,
limit=pagination.limit,
items_count=len(project_responses),
)
return PaginatedResponse(data=project_responses, pagination=pagination_meta)
except Exception as e:
logger.error(f"Error listing projects: {e!s}", exc_info=True)
raise
@router.get(
"/{project_id}",
response_model=ProjectResponse,
summary="Get Project",
description="""
Get detailed information about a specific project.
Users can only access their own projects unless they are superusers.
**Rate Limit**: 60 requests/minute
""",
operation_id="get_project",
)
@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
async def get_project(
request: Request,
project_id: UUID,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Get detailed information about a project by ID.
Includes agent count, issue count, and active sprint name.
"""
try:
project_data = await project_crud.get_with_counts(db, project_id=project_id)
if not project_data:
raise NotFoundError(
message=f"Project {project_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
project = project_data["project"]
_check_project_ownership(project, current_user)
return _build_project_response(project_data)
except (NotFoundError, AuthorizationError):
raise
except Exception as e:
logger.error(f"Error getting project {project_id}: {e!s}", exc_info=True)
raise
@router.get(
"/slug/{slug}",
response_model=ProjectResponse,
summary="Get Project by Slug",
description="""
Get detailed information about a project by its slug.
Users can only access their own projects unless they are superusers.
**Rate Limit**: 60 requests/minute
""",
operation_id="get_project_by_slug",
)
@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
async def get_project_by_slug(
request: Request,
slug: str,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Get detailed information about a project by slug.
Includes agent count, issue count, and active sprint name.
"""
try:
project = await project_crud.get_by_slug(db, slug=slug)
if not project:
raise NotFoundError(
message=f"Project with slug '{slug}' not found",
error_code=ErrorCode.NOT_FOUND,
)
_check_project_ownership(project, current_user)
# Get project with counts
project_data = await project_crud.get_with_counts(db, project_id=project.id)
if not project_data:
raise NotFoundError(
message=f"Project with slug '{slug}' not found",
error_code=ErrorCode.NOT_FOUND,
)
return _build_project_response(project_data)
except (NotFoundError, AuthorizationError):
raise
except Exception as e:
logger.error(f"Error getting project by slug {slug}: {e!s}", exc_info=True)
raise
@router.patch(
"/{project_id}",
response_model=ProjectResponse,
summary="Update Project",
description="""
Update an existing project.
Only the project owner or a superuser can update a project.
Only provided fields will be updated.
**Rate Limit**: 20 requests/minute
""",
operation_id="update_project",
)
@limiter.limit(f"{20 * RATE_MULTIPLIER}/minute")
async def update_project(
request: Request,
project_id: UUID,
project_in: ProjectUpdate,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Update a project's information.
Only the project owner or superusers can perform updates.
"""
try:
project = await project_crud.get(db, id=project_id)
if not project:
raise NotFoundError(
message=f"Project {project_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
_check_project_ownership(project, current_user)
# Update the project
updated_project = await project_crud.update(db, db_obj=project, obj_in=project_in)
logger.info(
f"User {current_user.email} updated project {updated_project.slug}"
)
# Get updated project with counts
project_data = await project_crud.get_with_counts(db, project_id=updated_project.id)
if not project_data:
# This shouldn't happen, but handle gracefully
raise NotFoundError(
message=f"Project {project_id} not found after update",
error_code=ErrorCode.NOT_FOUND,
)
return _build_project_response(project_data)
except (NotFoundError, AuthorizationError):
raise
except ValueError as e:
error_msg = str(e)
if "already exists" in error_msg.lower():
logger.warning(f"Duplicate project slug attempted: {project_in.slug}")
raise DuplicateError(
message=error_msg,
error_code=ErrorCode.DUPLICATE_ENTRY,
field="slug",
)
logger.error(f"Error updating project: {error_msg}", exc_info=True)
raise
except Exception as e:
logger.error(f"Error updating project {project_id}: {e!s}", exc_info=True)
raise
@router.delete(
"/{project_id}",
response_model=MessageResponse,
summary="Archive Project",
description="""
Archive a project (soft delete).
Only the project owner or a superuser can archive a project.
Archived projects are not deleted but are no longer accessible for active work.
**Rate Limit**: 10 requests/minute
""",
operation_id="archive_project",
)
@limiter.limit(f"{10 * RATE_MULTIPLIER}/minute")
async def archive_project(
request: Request,
project_id: UUID,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Archive a project by setting its status to ARCHIVED.
This is a soft delete operation. The project data is preserved.
"""
try:
project = await project_crud.get(db, id=project_id)
if not project:
raise NotFoundError(
message=f"Project {project_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
_check_project_ownership(project, current_user)
# Check if project is already archived
if project.status == ProjectStatus.ARCHIVED:
return MessageResponse(
success=True,
message=f"Project '{project.name}' is already archived",
)
archived_project = await project_crud.archive_project(db, project_id=project_id)
if not archived_project:
raise NotFoundError(
message=f"Failed to archive project {project_id}",
error_code=ErrorCode.NOT_FOUND,
)
logger.info(f"User {current_user.email} archived project {project.slug}")
return MessageResponse(
success=True,
message=f"Project '{archived_project.name}' has been archived",
)
except (NotFoundError, AuthorizationError):
raise
except Exception as e:
logger.error(f"Error archiving project {project_id}: {e!s}", exc_info=True)
raise
# =============================================================================
# Project Lifecycle Endpoints
# =============================================================================
@router.post(
"/{project_id}/pause",
response_model=ProjectResponse,
summary="Pause Project",
description="""
Pause an active project.
Only ACTIVE projects can be paused.
Only the project owner or a superuser can pause a project.
**Rate Limit**: 10 requests/minute
""",
operation_id="pause_project",
)
@limiter.limit(f"{10 * RATE_MULTIPLIER}/minute")
async def pause_project(
request: Request,
project_id: UUID,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Pause an active project.
Sets the project status to PAUSED. Only ACTIVE projects can be paused.
"""
try:
project = await project_crud.get(db, id=project_id)
if not project:
raise NotFoundError(
message=f"Project {project_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
_check_project_ownership(project, current_user)
# Validate current status (business logic validation, not authorization)
if project.status == ProjectStatus.PAUSED:
raise ValidationException(
message="Project is already paused",
error_code=ErrorCode.VALIDATION_ERROR,
field="status",
)
if project.status == ProjectStatus.ARCHIVED:
raise ValidationException(
message="Cannot pause an archived project",
error_code=ErrorCode.VALIDATION_ERROR,
field="status",
)
if project.status == ProjectStatus.COMPLETED:
raise ValidationException(
message="Cannot pause a completed project",
error_code=ErrorCode.VALIDATION_ERROR,
field="status",
)
# Update status to PAUSED
updated_project = await project_crud.update(
db, db_obj=project, obj_in=ProjectUpdate(status=ProjectStatus.PAUSED)
)
logger.info(f"User {current_user.email} paused project {project.slug}")
# Get project with counts
project_data = await project_crud.get_with_counts(db, project_id=updated_project.id)
if not project_data:
raise NotFoundError(
message=f"Project {project_id} not found after update",
error_code=ErrorCode.NOT_FOUND,
)
return _build_project_response(project_data)
except (NotFoundError, AuthorizationError, ValidationException):
raise
except Exception as e:
logger.error(f"Error pausing project {project_id}: {e!s}", exc_info=True)
raise
@router.post(
"/{project_id}/resume",
response_model=ProjectResponse,
summary="Resume Project",
description="""
Resume a paused project.
Only PAUSED projects can be resumed.
Only the project owner or a superuser can resume a project.
**Rate Limit**: 10 requests/minute
""",
operation_id="resume_project",
)
@limiter.limit(f"{10 * RATE_MULTIPLIER}/minute")
async def resume_project(
request: Request,
project_id: UUID,
current_user: User = Depends(get_current_user),
db: AsyncSession = Depends(get_db),
) -> Any:
"""
Resume a paused project.
Sets the project status back to ACTIVE. Only PAUSED projects can be resumed.
"""
try:
project = await project_crud.get(db, id=project_id)
if not project:
raise NotFoundError(
message=f"Project {project_id} not found",
error_code=ErrorCode.NOT_FOUND,
)
_check_project_ownership(project, current_user)
# Validate current status (business logic validation, not authorization)
if project.status == ProjectStatus.ACTIVE:
raise ValidationException(
message="Project is already active",
error_code=ErrorCode.VALIDATION_ERROR,
field="status",
)
if project.status == ProjectStatus.ARCHIVED:
raise ValidationException(
message="Cannot resume an archived project",
error_code=ErrorCode.VALIDATION_ERROR,
field="status",
)
if project.status == ProjectStatus.COMPLETED:
raise ValidationException(
message="Cannot resume a completed project",
error_code=ErrorCode.VALIDATION_ERROR,
field="status",
)
# Update status to ACTIVE
updated_project = await project_crud.update(
db, db_obj=project, obj_in=ProjectUpdate(status=ProjectStatus.ACTIVE)
)
logger.info(f"User {current_user.email} resumed project {project.slug}")
# Get project with counts
project_data = await project_crud.get_with_counts(db, project_id=updated_project.id)
if not project_data:
raise NotFoundError(
message=f"Project {project_id} not found after update",
error_code=ErrorCode.NOT_FOUND,
)
return _build_project_response(project_data)
except (NotFoundError, AuthorizationError, ValidationException):
raise
except Exception as e:
logger.error(f"Error resuming project {project_id}: {e!s}", exc_info=True)
raise

1185
backend/app/api/routes/sprints.py Normal file
View File

File diff suppressed because it is too large Load Diff

88
backend/app/crud/syndarix/issue.py
View File

@@ -432,6 +432,94 @@ class CRUDIssue(CRUDBase[Issue, IssueCreate, IssueUpdate]):
logger.error(f"Error getting pending sync issues: {e!s}", exc_info=True)
raise
async def remove_sprint_from_issues(
self,
db: AsyncSession,
*,
sprint_id: UUID,
) -> int:
"""Remove sprint assignment from all issues in a sprint.
Used when deleting a sprint to clean up references.
Returns:
Number of issues updated
"""
try:
from sqlalchemy import update
result = await db.execute(
update(Issue)
.where(Issue.sprint_id == sprint_id)
.values(sprint_id=None)
)
await db.commit()
return result.rowcount
except Exception as e:
await db.rollback()
logger.error(
f"Error removing sprint {sprint_id} from issues: {e!s}",
exc_info=True,
)
raise
async def unassign(
self,
db: AsyncSession,
*,
issue_id: UUID,
) -> Issue | None:
"""Remove agent assignment from an issue.
Returns:
Updated issue or None if not found
"""
try:
result = await db.execute(select(Issue).where(Issue.id == issue_id))
issue = result.scalar_one_or_none()
if not issue:
return None
issue.assigned_agent_id = None
await db.commit()
await db.refresh(issue)
return issue
except Exception as e:
await db.rollback()
logger.error(f"Error unassigning issue {issue_id}: {e!s}", exc_info=True)
raise
async def remove_from_sprint(
self,
db: AsyncSession,
*,
issue_id: UUID,
) -> Issue | None:
"""Remove an issue from its current sprint.
Returns:
Updated issue or None if not found
"""
try:
result = await db.execute(select(Issue).where(Issue.id == issue_id))
issue = result.scalar_one_or_none()
if not issue:
return None
issue.sprint_id = None
await db.commit()
await db.refresh(issue)
return issue
except Exception as e:
await db.rollback()
logger.error(
f"Error removing issue {issue_id} from sprint: {e!s}",
exc_info=True,
)
raise
# Create a singleton instance for use across the application
issue = CRUDIssue(Issue)

26
backend/app/crud/syndarix/sprint.py
View File

@@ -185,9 +185,18 @@ class CRUDSprint(CRUDBase[Sprint, SprintCreate, SprintUpdate]):
sprint_id: UUID,
start_date: date | None = None,
) -> Sprint | None:
"""Start a planned sprint."""
"""Start a planned sprint.
Uses row-level locking (SELECT FOR UPDATE) to prevent race conditions
when multiple requests try to start sprints concurrently.
"""
try:
result = await db.execute(select(Sprint).where(Sprint.id == sprint_id))
# Lock the sprint row to prevent concurrent modifications
result = await db.execute(
select(Sprint)
.where(Sprint.id == sprint_id)
.with_for_update()
)
sprint = result.scalar_one_or_none()
if not sprint:
@@ -198,8 +207,17 @@ class CRUDSprint(CRUDBase[Sprint, SprintCreate, SprintUpdate]):
f"Cannot start sprint with status {sprint.status.value}"
)
# Check for existing active sprint in project
active_sprint = await self.get_active_sprint(db, project_id=sprint.project_id)
# Check for existing active sprint with lock to prevent race condition
# Lock all sprints for this project to ensure atomic check-and-update
active_check = await db.execute(
select(Sprint)
.where(
Sprint.project_id == sprint.project_id,
Sprint.status == SprintStatus.ACTIVE,
)
.with_for_update()
)
active_sprint = active_check.scalar_one_or_none()
if active_sprint:
raise ValueError(
f"Project already has an active sprint: {active_sprint.name}"

8
backend/app/schemas/syndarix/project.py
View File

@@ -57,7 +57,12 @@ class ProjectCreate(ProjectBase):
class ProjectUpdate(BaseModel):
"""Schema for updating a project."""
"""Schema for updating a project.
Note: owner_id is intentionally excluded to prevent IDOR vulnerabilities.
Project ownership transfer should be done via a dedicated endpoint with
proper authorization checks.
"""
name: str | None = Field(None, min_length=1, max_length=255)
slug: str | None = Field(None, min_length=1, max_length=255)
@@ -65,7 +70,6 @@ class ProjectUpdate(BaseModel):
autonomy_level: AutonomyLevel | None = None
status: ProjectStatus | None = None
settings: dict[str, Any] | None = None
owner_id: UUID | None = None
@field_validator("slug")
@classmethod

97
backend/tests/api/routes/test_events.py
View File

@@ -23,8 +23,10 @@ from httpx import ASGITransport, AsyncClient
from app.api.dependencies.event_bus import get_event_bus
from app.core.database import get_db
from app.crud.syndarix.project import project as project_crud
from app.main import app
from app.schemas.events import Event, EventType
from app.schemas.syndarix.project import ProjectCreate
from app.services.event_bus import EventBus
@@ -147,6 +149,21 @@ async def user_token_with_mock_bus(client_with_mock_bus, async_test_user):
return tokens["access_token"]
@pytest_asyncio.fixture
async def test_project_for_events(async_test_db, async_test_user):
"""Create a test project owned by the test user for events testing."""
_test_engine, AsyncTestingSessionLocal = async_test_db
async with AsyncTestingSessionLocal() as session:
project_in = ProjectCreate(
name="Test Events Project",
slug="test-events-project",
owner_id=async_test_user.id,
)
project = await project_crud.create(session, obj_in=project_in)
return project
class TestSSEEndpointAuthentication:
"""Tests for SSE endpoint authentication."""
@@ -174,15 +191,75 @@ class TestSSEEndpointAuthentication:
assert response.status_code == status.HTTP_401_UNAUTHORIZED
class TestSSEEndpointAuthorization:
"""Tests for SSE endpoint authorization."""
@pytest.mark.asyncio
async def test_stream_events_nonexistent_project_returns_403(
self, client_with_mock_bus, user_token_with_mock_bus
):
"""Test that accessing a non-existent project returns 403."""
nonexistent_project_id = uuid.uuid4()
response = await client_with_mock_bus.get(
f"/api/v1/projects/{nonexistent_project_id}/events/stream",
headers={"Authorization": f"Bearer {user_token_with_mock_bus}"},
timeout=5.0,
)
# Should return 403 because project doesn't exist (auth check fails)
assert response.status_code == status.HTTP_403_FORBIDDEN
@pytest.mark.asyncio
async def test_stream_events_other_users_project_returns_403(
self, client_with_mock_bus, user_token_with_mock_bus, async_test_db
):
"""Test that accessing another user's project returns 403."""
_test_engine, AsyncTestingSessionLocal = async_test_db
# Create a project owned by a different user
async with AsyncTestingSessionLocal() as session:
other_user_id = uuid.uuid4() # Simulated other user
project_in = ProjectCreate(
name="Other User's Project",
slug="other-users-project",
owner_id=other_user_id,
)
other_project = await project_crud.create(session, obj_in=project_in)
response = await client_with_mock_bus.get(
f"/api/v1/projects/{other_project.id}/events/stream",
headers={"Authorization": f"Bearer {user_token_with_mock_bus}"},
timeout=5.0,
)
# Should return 403 because user doesn't own the project
assert response.status_code == status.HTTP_403_FORBIDDEN
@pytest.mark.asyncio
async def test_send_test_event_nonexistent_project_returns_403(
self, client_with_mock_bus, user_token_with_mock_bus
):
"""Test that sending event to non-existent project returns 403."""
nonexistent_project_id = uuid.uuid4()
response = await client_with_mock_bus.post(
f"/api/v1/projects/{nonexistent_project_id}/events/test",
headers={"Authorization": f"Bearer {user_token_with_mock_bus}"},
)
assert response.status_code == status.HTTP_403_FORBIDDEN
class TestSSEEndpointStream:
"""Tests for SSE stream functionality."""
@pytest.mark.asyncio
async def test_stream_events_returns_sse_response(
self, client_with_mock_bus, user_token_with_mock_bus
self, client_with_mock_bus, user_token_with_mock_bus, test_project_for_events
):
"""Test that SSE endpoint returns proper SSE response."""
project_id = uuid.uuid4()
project_id = test_project_for_events.id
# Make request with a timeout to avoid hanging
response = await client_with_mock_bus.get(
@@ -197,10 +274,10 @@ class TestSSEEndpointStream:
@pytest.mark.asyncio
async def test_stream_events_with_events(
self, client_with_mock_bus, user_token_with_mock_bus, mock_event_bus
self, client_with_mock_bus, user_token_with_mock_bus, mock_event_bus, test_project_for_events
):
"""Test that SSE endpoint yields events."""
project_id = uuid.uuid4()
project_id = test_project_for_events.id
# Create a test event and add it to the mock bus
test_event = Event(
@@ -228,10 +305,10 @@ class TestSSEEndpointStream:
@pytest.mark.asyncio
async def test_stream_events_with_last_event_id(
self, client_with_mock_bus, user_token_with_mock_bus
self, client_with_mock_bus, user_token_with_mock_bus, test_project_for_events
):
"""Test that Last-Event-ID header is accepted."""
project_id = uuid.uuid4()
project_id = test_project_for_events.id
last_event_id = str(uuid.uuid4())
response = await client_with_mock_bus.get(
@@ -252,10 +329,10 @@ class TestSSEEndpointHeaders:
@pytest.mark.asyncio
async def test_stream_events_cache_control_header(
self, client_with_mock_bus, user_token_with_mock_bus
self, client_with_mock_bus, user_token_with_mock_bus, test_project_for_events
):
"""Test that SSE response has no-cache header."""
project_id = uuid.uuid4()
project_id = test_project_for_events.id
response = await client_with_mock_bus.get(
f"/api/v1/projects/{project_id}/events/stream",
@@ -284,10 +361,10 @@ class TestTestEventEndpoint:
@pytest.mark.asyncio
async def test_send_test_event_success(
self, client_with_mock_bus, user_token_with_mock_bus, mock_event_bus
self, client_with_mock_bus, user_token_with_mock_bus, mock_event_bus, test_project_for_events
):
"""Test sending a test event."""
project_id = uuid.uuid4()
project_id = test_project_for_events.id
response = await client_with_mock_bus.post(
f"/api/v1/projects/{project_id}/events/test",

138
docs/architecture/IMPLEMENTATION_ROADMAP.md
View File

@@ -1,8 +1,8 @@
# Syndarix Implementation Roadmap
**Version:** 1.0
**Date:** 2025-12-29
**Status:** Draft
**Version:** 1.2
**Date:** 2025-12-30
**Status:** Active Development
---
@@ -12,7 +12,7 @@ This roadmap outlines the phased implementation approach for Syndarix, prioritiz
---
## Phase 0: Foundation (Weeks 1-2)
## Phase 0: Foundation ✅ COMPLETE
**Goal:** Establish development infrastructure and basic platform
### 0.1 Repository Setup
@@ -22,62 +22,67 @@ This roadmap outlines the phased implementation approach for Syndarix, prioritiz
- [x] Complete all spike research (SPIKE-001 through SPIKE-012)
- [x] Create all ADRs (ADR-001 through ADR-014)
- [x] Rebrand codebase (all URLs, names, configs updated)
- [ ] Configure CI/CD pipelines
- [ ] Set up development environment documentation
- [x] Configure CI/CD pipelines (`.gitea/workflows/ci.yaml`)
- [x] Set up development environment documentation
### 0.2 Core Infrastructure
- [ ] Configure Redis for cache + pub/sub
- [ ] Set up Celery worker infrastructure
- [ ] Configure pgvector extension
- [ ] Create MCP server directory structure
- [ ] Set up Docker Compose for local development
- [x] Configure Redis for cache + pub/sub (`app/core/redis.py`)
- [x] Set up Celery worker infrastructure (4 queues: agent, git, sync, cicd)
- [x] Configure pgvector extension (migration 0003)
- [x] Create MCP server directory structure (`mcp-servers/`)
- [x] Set up Docker Compose for local development (3 compose files)
### Deliverables
- [x] Fully branded Syndarix repository
- [x] Complete architecture documentation (ARCHITECTURE.md)
- [x] All spike research completed (12 spikes)
- [x] All ADRs documented (14 ADRs)
- [ ] Working local development environment (Docker Compose)
- [ ] CI/CD pipeline running tests
- [x] Working local development environment (Docker Compose)
- [x] CI/CD pipeline running tests
---
## Phase 1: Core Platform (Weeks 3-6)
## Phase 1: Core Platform 🔄 IN PROGRESS (~85%)
**Goal:** Basic project and agent management without LLM integration
### 1.1 Data Model
- [ ] Create Project entity and CRUD
- [ ] Create AgentType entity and CRUD
- [ ] Create AgentInstance entity and CRUD
- [ ] Create Issue entity with external tracker fields
- [ ] Create Sprint entity and CRUD
- [ ] Database migrations with Alembic
### 1.1 Data Model ✅ COMPLETE
- [x] Create Project entity and CRUD (`models/syndarix/project.py`)
- [x] Create AgentType entity and CRUD (`models/syndarix/agent_type.py`)
- [x] Create AgentInstance entity and CRUD (`models/syndarix/agent_instance.py`)
- [x] Create Issue entity with external tracker fields (`models/syndarix/issue.py`)
- [x] Create Sprint entity and CRUD (`models/syndarix/sprint.py`)
- [x] Database migrations with Alembic (3 migrations)
### 1.2 API Layer
- [ ] Project management endpoints
- [ ] Agent type configuration endpoints
- [ ] Agent instance management endpoints
- [ ] Issue CRUD endpoints
- [ ] Sprint management endpoints
### 1.2 API Layer ✅ COMPLETE
- [x] Project management endpoints (`api/routes/projects.py`) - Issue #28
- [x] Agent type configuration endpoints (`api/routes/agent_types.py`) - Issue #29
- [x] Agent instance management endpoints (`api/routes/agents.py`) - Issue #30
- [x] Issue CRUD endpoints (`api/routes/issues.py`) - Issue #31
- [x] Sprint management endpoints (`api/routes/sprints.py`) - Issue #32
### 1.3 Real-time Infrastructure
- [ ] Implement EventBus with Redis Pub/Sub
- [ ] Create SSE endpoint for project events
- [ ] Implement event types enum
- [ ] Add keepalive mechanism
- [ ] Client-side SSE handling
### 1.3 Real-time Infrastructure ✅ COMPLETE
- [x] Implement EventBus with Redis Pub/Sub (`services/event_bus.py`)
- [x] Create SSE endpoint for project events (`api/routes/events.py`)
- [x] Implement event types enum (`schemas/events.py`)
- [x] Add keepalive mechanism
- [x] Client-side SSE handling (`hooks/useProjectEvents.ts`)
### 1.4 Frontend Foundation
- [ ] Project dashboard page
- [ ] Agent configuration UI
- [ ] Issue list and detail views
- [ ] Real-time activity feed component
- [ ] Basic navigation and layout
- [x] Project dashboard page (prototype) - Awaiting approval #36
- [x] Agent configuration UI (prototype) - Awaiting approval #37
- [x] Issue list and detail views (prototype) - Awaiting approval #38
- [x] Real-time activity feed component (prototype) - Awaiting approval #39
- [x] Basic navigation and layout (implemented)
- [ ] Production implementations (#40-43) - Blocked by design approvals
### Deliverables
- CRUD operations for all core entities
- Real-time event streaming working
- Basic admin UI for configuration
- [x] CRUD operations for all core entities
- [x] Real-time event streaming working
- [ ] Basic admin UI for configuration (blocked by design approvals)
### Blocking Items
- Issues #36-39: UI prototypes awaiting user approval
- Issues #40-43: Frontend implementations blocked by #36-39
---
@@ -91,7 +96,7 @@ This roadmap outlines the phased implementation approach for Syndarix, prioritiz
- [ ] Create tool call routing
### 2.2 LLM Gateway MCP (Priority 1)
- [ ] Create FastMCP server structure
- [x] Create FastMCP server structure (`mcp-servers/llm-gateway/`)
- [ ] Implement LiteLLM integration
- [ ] Add model group routing
- [ ] Implement failover chain
@@ -99,6 +104,7 @@ This roadmap outlines the phased implementation approach for Syndarix, prioritiz
- [ ] Create token usage logging
### 2.3 Knowledge Base MCP (Priority 2)
- [x] Create server directory (`mcp-servers/knowledge-base/`)
- [ ] Create pgvector schema for embeddings
- [ ] Implement document ingestion pipeline
- [ ] Create chunking strategies (code, markdown, text)
@@ -107,6 +113,7 @@ This roadmap outlines the phased implementation approach for Syndarix, prioritiz
- [ ] Per-project collection isolation
### 2.4 Git MCP (Priority 3)
- [x] Create server directory (`mcp-servers/git-ops/`)
- [ ] Create Git operations wrapper
- [ ] Implement clone, commit, push operations
- [ ] Add branch management
@@ -115,6 +122,7 @@ This roadmap outlines the phased implementation approach for Syndarix, prioritiz
- [ ] Implement GitHub/GitLab adapters
### 2.5 Issues MCP (Priority 4)
- [x] Create server directory (`mcp-servers/issues/`)
- [ ] Create issue sync service
- [ ] Implement Gitea issue operations
- [ ] Add GitHub issue adapter
@@ -159,11 +167,11 @@ This roadmap outlines the phased implementation approach for Syndarix, prioritiz
- [ ] Add conversation threading
### 3.4 Background Task Integration
- [ ] Create Celery task wrappers
- [x] Create Celery task wrappers (`app/tasks/`)
- [x] Implement retry logic with exponential backoff
- [ ] Implement progress reporting
- [ ] Add task chaining for workflows
- [ ] Create agent queue routing
- [ ] Implement task retry logic
### Deliverables
- Agents can be spawned and communicate
@@ -237,9 +245,12 @@ This roadmap outlines the phased implementation approach for Syndarix, prioritiz
- [ ] Decision explainer
### 5.4 Additional MCP Servers
- [ ] File System MCP
- [ ] Code Analysis MCP
- [ ] CI/CD MCP
- [x] File System MCP directory (`mcp-servers/file-system/`)
- [x] Code Analysis MCP directory (`mcp-servers/code-analysis/`)
- [x] CI/CD MCP directory (`mcp-servers/cicd/`)
- [ ] Implement File System MCP
- [ ] Implement Code Analysis MCP
- [ ] Implement CI/CD MCP
### Deliverables
- Production-ready system
@@ -278,6 +289,30 @@ This roadmap outlines the phased implementation approach for Syndarix, prioritiz
---
## Current Progress Summary
| Phase | Status | Completion |
|-------|--------|------------|
| Phase 0: Foundation | ✅ Complete | 100% |
| Phase 1: Core Platform | 🔄 In Progress | ~88% |
| Phase 2: MCP Integration | 📋 Not Started | 0% |
| Phase 3: Agent Orchestration | 📋 Not Started | 0% |
| Phase 4: Workflow Engine | 📋 Not Started | 0% |
| Phase 5: Advanced Features | 📋 Not Started | 0% |
| Phase 6: Polish & Launch | 📋 Not Started | 0% |
### Phase 1 Breakdown
- Data Model: ✅ 100% (all entities, CRUD, migrations)
- API Layer: ✅ 100% (all endpoints implemented)
- Real-time: ✅ 100% (EventBus, SSE, client hooks)
- Frontend: 🔄 50% (prototypes done, implementations blocked)
### Blocking Items
1. **UI Design Approvals (#36-39)**: Prototypes complete, awaiting user review
2. **Frontend Implementations (#40-43)**: Blocked by design approvals
---
## Risk Register
| Risk | Impact | Probability | Mitigation |
@@ -310,12 +345,7 @@ This roadmap outlines the phased implementation approach for Syndarix, prioritiz
```
Phase 0 ─────▶ Phase 1 ─────▶ Phase 2 ─────▶ Phase 3 ─────▶ Phase 4 ─────▶ Phase 5 ─────▶ Phase 6
Foundation Core Platform MCP Integration Agent Orch Workflows Advanced Launch
│
│
Depends on:
- LLM Gateway
- Knowledge Base
- Real-time events
✅ 🔄 88% 📋 📋 📋 📋 📋
```
---
@@ -346,4 +376,4 @@ Foundation Core Platform MCP Integration Agent Orch Workflows Advan
---
*This roadmap will be refined as spikes complete and requirements evolve.*
*Last updated: 2025-12-30*