feat: agent coordination system (workflows, locks, components, messages)

Adds /api/coord/* endpoints for real-time cross-session coordination: - coord_workflows: named units of work per project - coord_work_items: tasks within workflows with dependency chains - coord_session_locks: exclusive resource locks with auto-expiry (TTL) - coord_component_states: live component state per project (upsert) - coord_messages: cross-session messaging and broadcasts - /api/coord/status: cross-project snapshot endpoint Replaces PROJECT_STATE.md as the coordination layer for Claude sessions. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-12 08:25:33 -07:00
parent bd88398297
commit 63975284f4
24 changed files with 1565 additions and 0 deletions
--- a/api/routers/coord_components.py
+++ b/api/routers/coord_components.py
@@ -0,0 +1,38 @@
+"""Coordination component states router."""
+
+from fastapi import APIRouter, Depends, Query, status
+from sqlalchemy.orm import Session
+
+from api.database import get_db
+from api.middleware.auth import get_current_user
+from api.schemas.coord_component_state import CoordComponentStateUpsert, CoordComponentStateResponse
+from api.services import coord_component_service
+
+router = APIRouter()
+
+
+@router.get("", response_model=dict, status_code=status.HTTP_200_OK)
+def list_component_states(
+    project_key: str | None = Query(default=None),
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """List all component states, optionally filtered by project."""
+    states = coord_component_service.get_component_states(db, project_key=project_key)
+    return {
+        "total": len(states),
+        "states": [CoordComponentStateResponse.model_validate(s) for s in states],
+    }
+
+
+@router.put("/{project_key}/{component}", response_model=CoordComponentStateResponse, status_code=status.HTTP_200_OK)
+def upsert_component_state(
+    project_key: str,
+    component: str,
+    data: CoordComponentStateUpsert,
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Create or update the state of a component within a project."""
+    state = coord_component_service.upsert_component_state(db, project_key, component, data)
+    return CoordComponentStateResponse.model_validate(state)
--- a/api/routers/coord_locks.py
+++ b/api/routers/coord_locks.py
@@ -0,0 +1,81 @@
+"""Coordination session locks router."""
+
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Query, status
+from sqlalchemy.orm import Session
+
+from api.database import get_db
+from api.middleware.auth import get_current_user
+from api.schemas.coord_session_lock import CoordSessionLockCreate, CoordSessionLockResponse
+from api.services import coord_lock_service
+
+router = APIRouter()
+
+
+@router.get("", response_model=dict, status_code=status.HTTP_200_OK)
+def list_active_locks(
+    project_key: str | None = Query(default=None),
+    session_id: str | None = Query(default=None),
+    skip: int = Query(default=0, ge=0),
+    limit: int = Query(default=100, ge=1, le=1000),
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """List currently active locks with optional filters."""
+    locks, total = coord_lock_service.get_active_locks(
+        db, project_key=project_key, session_id=session_id, skip=skip, limit=limit
+    )
+    return {
+        "total": total,
+        "skip": skip,
+        "limit": limit,
+        "locks": [CoordSessionLockResponse.model_validate(l) for l in locks],
+    }
+
+
+@router.get("/check", response_model=dict, status_code=status.HTTP_200_OK)
+def check_resource_locked(
+    project_key: str = Query(...),
+    resource: str = Query(...),
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Check whether a resource is currently locked."""
+    lock = coord_lock_service.check_resource_locked(db, project_key, resource)
+    if lock:
+        return {"locked": True, "lock": CoordSessionLockResponse.model_validate(lock)}
+    return {"locked": False}
+
+
+@router.post("", response_model=CoordSessionLockResponse, status_code=status.HTTP_201_CREATED)
+def claim_lock(
+    data: CoordSessionLockCreate,
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Claim a resource lock for a session."""
+    lock = coord_lock_service.claim_lock(db, data)
+    return CoordSessionLockResponse.model_validate(lock)
+
+
+@router.delete("", response_model=dict, status_code=status.HTTP_200_OK)
+def release_all_session_locks(
+    session_id: str = Query(..., description="Release all active locks held by this session"),
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Release all active locks for a session (call on session end)."""
+    return coord_lock_service.release_all_session_locks(db, session_id)
+
+
+@router.delete("/{lock_id}", response_model=CoordSessionLockResponse, status_code=status.HTTP_200_OK)
+def release_lock(
+    lock_id: UUID,
+    session_id: str = Query(..., description="Must match the session that claimed the lock"),
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Release a specific lock by ID."""
+    lock = coord_lock_service.release_lock(db, lock_id, session_id)
+    return CoordSessionLockResponse.model_validate(lock)
--- a/api/routers/coord_messages.py
+++ b/api/routers/coord_messages.py
@@ -0,0 +1,77 @@
+"""Coordination inter-session messages router."""
+
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Query, status
+from sqlalchemy.orm import Session
+
+from api.database import get_db
+from api.middleware.auth import get_current_user
+from api.schemas.coord_message import CoordMessageCreate, CoordMessageResponse
+from api.services import coord_message_service
+
+router = APIRouter()
+
+
+@router.get("", response_model=dict, status_code=status.HTTP_200_OK)
+def list_messages(
+    to_session: str | None = Query(default=None),
+    unread_only: bool = Query(default=False),
+    skip: int = Query(default=0, ge=0),
+    limit: int = Query(default=100, ge=1, le=1000),
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """List messages with optional filters."""
+    messages, total = coord_message_service.get_messages(
+        db, to_session=to_session, unread_only=unread_only, skip=skip, limit=limit
+    )
+    return {
+        "total": total,
+        "skip": skip,
+        "limit": limit,
+        "messages": [CoordMessageResponse.model_validate(m) for m in messages],
+    }
+
+
+@router.get("/unread-count", response_model=dict, status_code=status.HTTP_200_OK)
+def get_unread_count(
+    session_id: str = Query(...),
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Return the count of unread messages for a session."""
+    count = coord_message_service.get_unread_count(db, session_id)
+    return {"count": count}
+
+
+@router.post("", response_model=CoordMessageResponse, status_code=status.HTTP_201_CREATED)
+def send_message(
+    data: CoordMessageCreate,
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Send a message to a session or broadcast."""
+    msg = coord_message_service.send_message(db, data)
+    return CoordMessageResponse.model_validate(msg)
+
+
+@router.put("/{message_id}/read", response_model=CoordMessageResponse, status_code=status.HTTP_200_OK)
+def mark_message_read(
+    message_id: UUID,
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Mark a message as read."""
+    msg = coord_message_service.mark_read(db, message_id)
+    return CoordMessageResponse.model_validate(msg)
+
+
+@router.delete("/{message_id}", response_model=dict, status_code=status.HTTP_200_OK)
+def delete_message(
+    message_id: UUID,
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Delete a message."""
+    return coord_message_service.delete_message(db, message_id)
--- a/api/routers/coord_status.py
+++ b/api/routers/coord_status.py
@@ -0,0 +1,46 @@
+"""Coordination status overview router."""
+
+from fastapi import APIRouter, Depends, status
+from sqlalchemy.orm import Session
+
+from api.database import get_db
+from api.middleware.auth import get_current_user
+from api.schemas.coord_session_lock import CoordSessionLockResponse
+from api.schemas.coord_workflow import CoordWorkflowResponse
+from api.schemas.coord_component_state import CoordComponentStateResponse
+from api.services import coord_lock_service, coord_workflow_service, coord_component_service, coord_message_service
+
+router = APIRouter()
+
+
+@router.get("", response_model=dict, status_code=status.HTTP_200_OK)
+def get_coordination_status(
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Return a cross-project snapshot: active locks, in-progress workflows, component states, unread message counts."""
+    active_locks, lock_total = coord_lock_service.get_active_locks(db, limit=200)
+    active_workflows, wf_total = coord_workflow_service.get_workflows(db, status_filter="active", limit=200)
+    component_states = coord_component_service.get_component_states(db)
+
+    # Group active locks by project
+    locks_by_project: dict = {}
+    for lock in active_locks:
+        locks_by_project.setdefault(lock.project_key, []).append(
+            CoordSessionLockResponse.model_validate(lock)
+        )
+
+    # Group component states by project
+    components_by_project: dict = {}
+    for state in component_states:
+        components_by_project.setdefault(state.project_key, []).append(
+            CoordComponentStateResponse.model_validate(state)
+        )
+
+    return {
+        "active_lock_count": lock_total,
+        "active_workflow_count": wf_total,
+        "locks_by_project": {k: v for k, v in locks_by_project.items()},
+        "active_workflows": [CoordWorkflowResponse.model_validate(w) for w in active_workflows],
+        "components_by_project": {k: v for k, v in components_by_project.items()},
+    }
--- a/api/routers/coord_work_items.py
+++ b/api/routers/coord_work_items.py
@@ -0,0 +1,86 @@
+"""Coordination work items router."""
+
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Query, status
+from sqlalchemy.orm import Session
+
+from api.database import get_db
+from api.middleware.auth import get_current_user
+from api.schemas.coord_work_item import CoordWorkItemCreate, CoordWorkItemResponse, CoordWorkItemUpdate
+from api.services import coord_work_item_service
+
+router = APIRouter()
+
+
+@router.get("", response_model=dict, status_code=status.HTTP_200_OK)
+def list_work_items(
+    workflow_id: str | None = Query(default=None),
+    project_key: str | None = Query(default=None),
+    status_filter: str | None = Query(default=None),
+    assigned_session: str | None = Query(default=None),
+    skip: int = Query(default=0, ge=0),
+    limit: int = Query(default=100, ge=1, le=1000),
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """List work items with optional filters."""
+    items, total = coord_work_item_service.get_work_items(
+        db,
+        workflow_id=workflow_id,
+        project_key=project_key,
+        status_filter=status_filter,
+        assigned_session=assigned_session,
+        skip=skip,
+        limit=limit,
+    )
+    return {
+        "total": total,
+        "skip": skip,
+        "limit": limit,
+        "work_items": [CoordWorkItemResponse.model_validate(i) for i in items],
+    }
+
+
+@router.post("", response_model=CoordWorkItemResponse, status_code=status.HTTP_201_CREATED)
+def create_work_item(
+    data: CoordWorkItemCreate,
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Create a new work item within a workflow."""
+    item = coord_work_item_service.create_work_item(db, data)
+    return CoordWorkItemResponse.model_validate(item)
+
+
+@router.get("/{item_id}", response_model=CoordWorkItemResponse, status_code=status.HTTP_200_OK)
+def get_work_item(
+    item_id: UUID,
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Get a work item by ID."""
+    item = coord_work_item_service.get_work_item_by_id(db, item_id)
+    return CoordWorkItemResponse.model_validate(item)
+
+
+@router.put("/{item_id}", response_model=CoordWorkItemResponse, status_code=status.HTTP_200_OK)
+def update_work_item(
+    item_id: UUID,
+    data: CoordWorkItemUpdate,
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Update a work item."""
+    item = coord_work_item_service.update_work_item(db, item_id, data)
+    return CoordWorkItemResponse.model_validate(item)
+
+
+@router.delete("/{item_id}", response_model=dict, status_code=status.HTTP_200_OK)
+def delete_work_item(
+    item_id: UUID,
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Delete a work item."""
+    return coord_work_item_service.delete_work_item(db, item_id)
--- a/api/routers/coord_workflows.py
+++ b/api/routers/coord_workflows.py
@@ -0,0 +1,83 @@
+"""Coordination workflows router."""
+
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Query, status
+from sqlalchemy.orm import Session
+
+from api.database import get_db
+from api.middleware.auth import get_current_user
+from api.schemas.coord_workflow import CoordWorkflowCreate, CoordWorkflowResponse, CoordWorkflowUpdate
+from api.schemas.coord_work_item import CoordWorkItemResponse
+from api.services import coord_workflow_service, coord_work_item_service
+
+router = APIRouter()
+
+
+@router.get("", response_model=dict, status_code=status.HTTP_200_OK)
+def list_workflows(
+    project_key: str | None = Query(default=None),
+    status_filter: str | None = Query(default=None),
+    skip: int = Query(default=0, ge=0),
+    limit: int = Query(default=100, ge=1, le=1000),
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """List workflows with optional filters."""
+    workflows, total = coord_workflow_service.get_workflows(
+        db, project_key=project_key, status_filter=status_filter, skip=skip, limit=limit
+    )
+    return {
+        "total": total,
+        "skip": skip,
+        "limit": limit,
+        "workflows": [CoordWorkflowResponse.model_validate(w) for w in workflows],
+    }
+
+
+@router.post("", response_model=CoordWorkflowResponse, status_code=status.HTTP_201_CREATED)
+def create_workflow(
+    data: CoordWorkflowCreate,
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Create a new coordination workflow."""
+    workflow = coord_workflow_service.create_workflow(db, data)
+    return CoordWorkflowResponse.model_validate(workflow)
+
+
+@router.get("/{workflow_id}", response_model=dict, status_code=status.HTTP_200_OK)
+def get_workflow(
+    workflow_id: UUID,
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Get a workflow by ID including its work items."""
+    workflow = coord_workflow_service.get_workflow_by_id(db, workflow_id)
+    items, _ = coord_work_item_service.get_work_items(db, workflow_id=str(workflow_id))
+    return {
+        "workflow": CoordWorkflowResponse.model_validate(workflow),
+        "work_items": [CoordWorkItemResponse.model_validate(i) for i in items],
+    }
+
+
+@router.put("/{workflow_id}", response_model=CoordWorkflowResponse, status_code=status.HTTP_200_OK)
+def update_workflow(
+    workflow_id: UUID,
+    data: CoordWorkflowUpdate,
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Update a workflow."""
+    workflow = coord_workflow_service.update_workflow(db, workflow_id, data)
+    return CoordWorkflowResponse.model_validate(workflow)
+
+
+@router.delete("/{workflow_id}", response_model=dict, status_code=status.HTTP_200_OK)
+def delete_workflow(
+    workflow_id: UUID,
+    db: Session = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Delete a workflow and its work items (cascade)."""
+    return coord_workflow_service.delete_workflow(db, workflow_id)