feat: add agent zones

backend/app/agent_zones/router.py

@@ -0,0 +1,75 @@
+"""HTTP mapping for Agent Zones and Agent check-in."""
+
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+
+from app.agent_commands.dependencies import require_agent_identity
+from app.agent_zones.dependencies import get_agent_zone_service
+from app.agent_zones.exceptions import (
+    AgentZoneConflict,
+    AgentZoneNotFound,
+    AgentZoneValidationError,
+)
+from app.agent_zones.models import (
+    AgentCheckinRequest,
+    AgentCheckinResponse,
+    AgentZoneCreateRequest,
+    AgentZoneCreateResponse,
+    AgentZoneListResponse,
+)
+from app.agent_zones.service import AgentZoneService
+from app.identity import require_permission
+
+
+router = APIRouter(tags=["agent-zones"])
+ZoneService = Annotated[AgentZoneService, Depends(get_agent_zone_service)]
+AgentIdentity = Annotated[str, Depends(require_agent_identity)]
+ZoneViewer = Annotated[dict, Depends(require_permission("agents.view"))]
+ZoneManager = Annotated[dict, Depends(require_permission("agents.manage"))]
+
+
+@router.get("/api/agent-zones", response_model=AgentZoneListResponse)
+def list_agent_zones(
+    current_user: ZoneViewer,
+    service: ZoneService,
+    site_id: UUID | None = Query(default=None),
+) -> AgentZoneListResponse:
+    del current_user
+    return AgentZoneListResponse(data=service.list_zones(site_id))
+
+
+@router.post(
+    "/api/agent-zones",
+    response_model=AgentZoneCreateResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+def create_agent_zone(
+    request: AgentZoneCreateRequest,
+    current_user: ZoneManager,
+    service: ZoneService,
+) -> AgentZoneCreateResponse:
+    del current_user
+    try:
+        return AgentZoneCreateResponse(data=service.create_zone(request))
+    except AgentZoneNotFound as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except AgentZoneConflict as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+
+
+@router.post("/api/agent/checkin", response_model=AgentCheckinResponse)
+def agent_checkin(
+    request: AgentCheckinRequest,
+    agent_id: AgentIdentity,
+    service: ZoneService,
+) -> AgentCheckinResponse:
+    try:
+        return service.checkin(agent_id, request)
+    except AgentZoneNotFound as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except AgentZoneConflict as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    except AgentZoneValidationError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc