ref(backend): Centralize deps and add mypy

Extract reusable API dependencies and activity logging helpers.\nAdd mypy configuration and dev dependency for type checking.\n\nCo-Authored-By: Claude <noreply@anthropic.com>

backend/app/api/activity.py

@@ -1,13 +1,14 @@
 from __future__ import annotations
 
 from fastapi import APIRouter, Depends, Query
-from sqlmodel import Session, select
+from sqlalchemy import desc
+from sqlmodel import Session, col, select
 
-from app.core.auth import get_auth_context
+from app.api.deps import require_admin_auth
+from app.core.auth import AuthContext
 from app.db.session import get_session
 from app.models.activity_events import ActivityEvent
 from app.schemas.activity_events import ActivityEventRead
-from app.services.admin_access import require_admin
 
 router = APIRouter(prefix="/activity", tags=["activity"])
 
@@ -17,10 +18,12 @@ def list_activity(
     limit: int = Query(50, ge=1, le=200),
     offset: int = Query(0, ge=0),
     session: Session = Depends(get_session),
-    auth=Depends(get_auth_context),
+    auth: AuthContext = Depends(require_admin_auth),
 ) -> list[ActivityEvent]:
-    require_admin(auth)
     statement = (
-        select(ActivityEvent).order_by(ActivityEvent.created_at.desc()).offset(offset).limit(limit)
+        select(ActivityEvent)
+        .order_by(desc(col(ActivityEvent.created_at)))
+        .offset(offset)
+        .limit(limit)
     )
     return list(session.exec(statement))

backend/app/api/agents.py

@@ -7,10 +7,10 @@ from uuid import uuid4
 from fastapi import APIRouter, Depends, HTTPException, status
 from sqlmodel import Session, select
 
-from app.core.auth import get_auth_context
+from app.api.deps import require_admin_auth
+from app.core.auth import AuthContext
 from app.db.session import get_session
 from app.integrations.openclaw_gateway import OpenClawGatewayError, openclaw_call
-from app.models.activity_events import ActivityEvent
 from app.models.agents import Agent
 from app.schemas.agents import (
     AgentCreate,
@@ -19,7 +19,7 @@ from app.schemas.agents import (
     AgentRead,
     AgentUpdate,
 )
-from app.services.admin_access import require_admin
+from app.services.activity_log import record_activity
 from app.services.agent_provisioning import send_provisioning_message
 
 router = APIRouter(prefix="/agents", tags=["agents"])
@@ -54,20 +54,28 @@ def _with_computed_status(agent: Agent) -> Agent:
 
 
 def _record_heartbeat(session: Session, agent: Agent) -> None:
-    event = ActivityEvent(
+    record_activity(
+        session,
         event_type="agent.heartbeat",
         message=f"Heartbeat received from {agent.name}.",
         agent_id=agent.id,
     )
-    session.add(event)
+
+
+def _record_provisioning_failure(session: Session, agent: Agent, error: str) -> None:
+    record_activity(
+        session,
+        event_type="agent.provision.failed",
+        message=f"Provisioning message failed: {error}",
+        agent_id=agent.id,
+    )
 
 
 @router.get("", response_model=list[AgentRead])
 def list_agents(
     session: Session = Depends(get_session),
-    auth=Depends(get_auth_context),
+    auth: AuthContext = Depends(require_admin_auth),
 ) -> list[Agent]:
-    require_admin(auth)
     agents = list(session.exec(select(Agent)))
     return [_with_computed_status(agent) for agent in agents]
 
@@ -76,9 +84,8 @@ def list_agents(
 async def create_agent(
     payload: AgentCreate,
     session: Session = Depends(get_session),
-    auth=Depends(get_auth_context),
+    auth: AuthContext = Depends(require_admin_auth),
 ) -> Agent:
-    require_admin(auth)
     agent = Agent.model_validate(payload)
     session_key, session_error = await _ensure_gateway_session(agent.name)
     agent.openclaw_session_id = session_key
@@ -86,41 +93,27 @@ async def create_agent(
     session.commit()
     session.refresh(agent)
     if session_error:
-        session.add(
-            ActivityEvent(
-                event_type="agent.session.failed",
-                message=f"Session sync failed for {agent.name}: {session_error}",
-                agent_id=agent.id,
-            )
+        record_activity(
+            session,
+            event_type="agent.session.failed",
+            message=f"Session sync failed for {agent.name}: {session_error}",
+            agent_id=agent.id,
         )
     else:
-        session.add(
-            ActivityEvent(
-                event_type="agent.session.created",
-                message=f"Session created for {agent.name}.",
-                agent_id=agent.id,
-            )
+        record_activity(
+            session,
+            event_type="agent.session.created",
+            message=f"Session created for {agent.name}.",
+            agent_id=agent.id,
         )
     session.commit()
     try:
         await send_provisioning_message(agent)
     except OpenClawGatewayError as exc:
-        session.add(
-            ActivityEvent(
-                event_type="agent.provision.failed",
-                message=f"Provisioning message failed: {exc}",
-                agent_id=agent.id,
-            )
-        )
+        _record_provisioning_failure(session, agent, str(exc))
         session.commit()
     except Exception as exc:  # pragma: no cover - unexpected provisioning errors
-        session.add(
-            ActivityEvent(
-                event_type="agent.provision.failed",
-                message=f"Provisioning message failed: {exc}",
-                agent_id=agent.id,
-            )
-        )
+        _record_provisioning_failure(session, agent, str(exc))
         session.commit()
     return agent
 
@@ -129,9 +122,8 @@ async def create_agent(
 def get_agent(
     agent_id: str,
     session: Session = Depends(get_session),
-    auth=Depends(get_auth_context),
+    auth: AuthContext = Depends(require_admin_auth),
 ) -> Agent:
-    require_admin(auth)
     agent = session.get(Agent, agent_id)
     if agent is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
@@ -143,9 +135,8 @@ def update_agent(
     agent_id: str,
     payload: AgentUpdate,
     session: Session = Depends(get_session),
-    auth=Depends(get_auth_context),
+    auth: AuthContext = Depends(require_admin_auth),
 ) -> Agent:
-    require_admin(auth)
     agent = session.get(Agent, agent_id)
     if agent is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
@@ -164,9 +155,8 @@ def heartbeat_agent(
     agent_id: str,
     payload: AgentHeartbeat,
     session: Session = Depends(get_session),
-    auth=Depends(get_auth_context),
+    auth: AuthContext = Depends(require_admin_auth),
 ) -> Agent:
-    require_admin(auth)
     agent = session.get(Agent, agent_id)
     if agent is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
@@ -185,9 +175,8 @@ def heartbeat_agent(
 async def heartbeat_or_create_agent(
     payload: AgentHeartbeatCreate,
     session: Session = Depends(get_session),
-    auth=Depends(get_auth_context),
+    auth: AuthContext = Depends(require_admin_auth),
 ) -> Agent:
-    require_admin(auth)
     agent = session.exec(select(Agent).where(Agent.name == payload.name)).first()
     if agent is None:
         agent = Agent(name=payload.name, status=payload.status or "online")
@@ -197,81 +186,53 @@ async def heartbeat_or_create_agent(
         session.commit()
         session.refresh(agent)
         if session_error:
-            session.add(
-                ActivityEvent(
-                    event_type="agent.session.failed",
-                    message=f"Session sync failed for {agent.name}: {session_error}",
-                    agent_id=agent.id,
-                )
+            record_activity(
+                session,
+                event_type="agent.session.failed",
+                message=f"Session sync failed for {agent.name}: {session_error}",
+                agent_id=agent.id,
             )
         else:
-            session.add(
-                ActivityEvent(
-                    event_type="agent.session.created",
-                    message=f"Session created for {agent.name}.",
-                    agent_id=agent.id,
-                )
+            record_activity(
+                session,
+                event_type="agent.session.created",
+                message=f"Session created for {agent.name}.",
+                agent_id=agent.id,
             )
         session.commit()
         try:
             await send_provisioning_message(agent)
         except OpenClawGatewayError as exc:
-            session.add(
-                ActivityEvent(
-                    event_type="agent.provision.failed",
-                    message=f"Provisioning message failed: {exc}",
-                    agent_id=agent.id,
-                )
-            )
+            _record_provisioning_failure(session, agent, str(exc))
             session.commit()
         except Exception as exc:  # pragma: no cover - unexpected provisioning errors
-            session.add(
-                ActivityEvent(
-                    event_type="agent.provision.failed",
-                    message=f"Provisioning message failed: {exc}",
-                    agent_id=agent.id,
-                )
-            )
+            _record_provisioning_failure(session, agent, str(exc))
             session.commit()
     elif not agent.openclaw_session_id:
         session_key, session_error = await _ensure_gateway_session(agent.name)
         agent.openclaw_session_id = session_key
         if session_error:
-            session.add(
-                ActivityEvent(
-                    event_type="agent.session.failed",
-                    message=f"Session sync failed for {agent.name}: {session_error}",
-                    agent_id=agent.id,
-                )
+            record_activity(
+                session,
+                event_type="agent.session.failed",
+                message=f"Session sync failed for {agent.name}: {session_error}",
+                agent_id=agent.id,
             )
         else:
-            session.add(
-                ActivityEvent(
-                    event_type="agent.session.created",
-                    message=f"Session created for {agent.name}.",
-                    agent_id=agent.id,
-                )
+            record_activity(
+                session,
+                event_type="agent.session.created",
+                message=f"Session created for {agent.name}.",
+                agent_id=agent.id,
             )
         session.commit()
         try:
             await send_provisioning_message(agent)
         except OpenClawGatewayError as exc:
-            session.add(
-                ActivityEvent(
-                    event_type="agent.provision.failed",
-                    message=f"Provisioning message failed: {exc}",
-                    agent_id=agent.id,
-                )
-            )
+            _record_provisioning_failure(session, agent, str(exc))
             session.commit()
         except Exception as exc:  # pragma: no cover - unexpected provisioning errors
-            session.add(
-                ActivityEvent(
-                    event_type="agent.provision.failed",
-                    message=f"Provisioning message failed: {exc}",
-                    agent_id=agent.id,
-                )
-            )
+            _record_provisioning_failure(session, agent, str(exc))
             session.commit()
     if payload.status:
         agent.status = payload.status
@@ -288,9 +249,8 @@ async def heartbeat_or_create_agent(
 def delete_agent(
     agent_id: str,
     session: Session = Depends(get_session),
-    auth=Depends(get_auth_context),
+    auth: AuthContext = Depends(require_admin_auth),
 ) -> dict[str, bool]:
-    require_admin(auth)
     agent = session.get(Agent, agent_id)
     if agent:
         session.delete(agent)

backend/app/api/auth.py

@@ -2,14 +2,14 @@ from __future__ import annotations
 
 from fastapi import APIRouter, Depends, HTTPException, status
 
-from app.core.auth import get_auth_context
+from app.core.auth import AuthContext, get_auth_context
 from app.schemas.users import UserRead
 
 router = APIRouter(prefix="/auth", tags=["auth"])
 
 
 @router.post("/bootstrap", response_model=UserRead)
-async def bootstrap_user(auth=Depends(get_auth_context)) -> UserRead:
+async def bootstrap_user(auth: AuthContext = Depends(get_auth_context)) -> UserRead:
     if auth.actor_type != "user" or auth.user is None:
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED)
-    return auth.user
+    return UserRead.model_validate(auth.user)

backend/app/api/boards.py

@@ -1,13 +1,13 @@
 from __future__ import annotations
 
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends
 from sqlmodel import Session, select
 
-from app.core.auth import get_auth_context
+from app.api.deps import get_board_or_404, require_admin_auth
+from app.core.auth import AuthContext
 from app.db.session import get_session
 from app.models.boards import Board
 from app.schemas.boards import BoardCreate, BoardRead, BoardUpdate
-from app.services.admin_access import require_admin
 
 router = APIRouter(prefix="/boards", tags=["boards"])
 
@@ -15,9 +15,8 @@ router = APIRouter(prefix="/boards", tags=["boards"])
 @router.get("", response_model=list[BoardRead])
 def list_boards(
     session: Session = Depends(get_session),
-    auth=Depends(get_auth_context),
+    auth: AuthContext = Depends(require_admin_auth),
 ) -> list[Board]:
-    require_admin(auth)
     return list(session.exec(select(Board)))
 
 
@@ -25,9 +24,8 @@ def list_boards(
 def create_board(
     payload: BoardCreate,
     session: Session = Depends(get_session),
-    auth=Depends(get_auth_context),
+    auth: AuthContext = Depends(require_admin_auth),
 ) -> Board:
-    require_admin(auth)
     board = Board.model_validate(payload)
     session.add(board)
     session.commit()
@@ -37,28 +35,19 @@ def create_board(
 
 @router.get("/{board_id}", response_model=BoardRead)
 def get_board(
-    board_id: str,
-    session: Session = Depends(get_session),
-    auth=Depends(get_auth_context),
+    board: Board = Depends(get_board_or_404),
+    auth: AuthContext = Depends(require_admin_auth),
 ) -> Board:
-    require_admin(auth)
-    board = session.get(Board, board_id)
-    if board is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
     return board
 
 
 @router.patch("/{board_id}", response_model=BoardRead)
 def update_board(
-    board_id: str,
     payload: BoardUpdate,
     session: Session = Depends(get_session),
-    auth=Depends(get_auth_context),
+    board: Board = Depends(get_board_or_404),
+    auth: AuthContext = Depends(require_admin_auth),
 ) -> Board:
-    require_admin(auth)
-    board = session.get(Board, board_id)
-    if board is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
     updates = payload.model_dump(exclude_unset=True)
     for key, value in updates.items():
         setattr(board, key, value)
@@ -70,13 +59,10 @@ def update_board(
 
 @router.delete("/{board_id}")
 def delete_board(
-    board_id: str,
     session: Session = Depends(get_session),
-    auth=Depends(get_auth_context),
+    board: Board = Depends(get_board_or_404),
+    auth: AuthContext = Depends(require_admin_auth),
 ) -> dict[str, bool]:
-    require_admin(auth)
-    board = session.get(Board, board_id)
-    if board:
-        session.delete(board)
-        session.commit()
+    session.delete(board)
+    session.commit()
     return {"ok": True}

backend/app/api/deps.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from fastapi import Depends, HTTPException, status
+from sqlmodel import Session
+
+from app.core.auth import AuthContext, get_auth_context
+from app.db.session import get_session
+from app.models.boards import Board
+from app.models.tasks import Task
+from app.services.admin_access import require_admin
+
+
+def require_admin_auth(auth: AuthContext = Depends(get_auth_context)) -> AuthContext:
+    require_admin(auth)
+    return auth
+
+
+def get_board_or_404(
+    board_id: str,
+    session: Session = Depends(get_session),
+) -> Board:
+    board = session.get(Board, board_id)
+    if board is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
+    return board
+
+
+def get_task_or_404(
+    task_id: str,
+    board: Board = Depends(get_board_or_404),
+    session: Session = Depends(get_session),
+) -> Task:
+    task = session.get(Task, task_id)
+    if task is None or task.board_id != board.id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
+    return task

backend/app/api/gateway.py

@@ -2,7 +2,8 @@ from __future__ import annotations
 
 from fastapi import APIRouter, Body, Depends, HTTPException, status
 
-from app.core.auth import get_auth_context
+from app.api.deps import require_admin_auth
+from app.core.auth import AuthContext
 from app.core.config import settings
 from app.integrations.openclaw_gateway import (
     OpenClawGatewayError,
@@ -10,14 +11,12 @@ from app.integrations.openclaw_gateway import (
     openclaw_call,
     send_message,
 )
-from app.services.admin_access import require_admin
 
 router = APIRouter(prefix="/gateway", tags=["gateway"])
 
 
 @router.get("/status")
-async def gateway_status(auth=Depends(get_auth_context)) -> dict[str, object]:
-    require_admin(auth)
+async def gateway_status(auth: AuthContext = Depends(require_admin_auth)) -> dict[str, object]:
     gateway_url = settings.openclaw_gateway_url or "ws://127.0.0.1:18789"
     try:
         sessions = await openclaw_call("sessions.list")
@@ -40,8 +39,7 @@ async def gateway_status(auth=Depends(get_auth_context)) -> dict[str, object]:
 
 
 @router.get("/sessions")
-async def list_sessions(auth=Depends(get_auth_context)) -> dict[str, object]:
-    require_admin(auth)
+async def list_sessions(auth: AuthContext = Depends(require_admin_auth)) -> dict[str, object]:
     try:
         sessions = await openclaw_call("sessions.list")
     except OpenClawGatewayError as exc:
@@ -52,8 +50,9 @@ async def list_sessions(auth=Depends(get_auth_context)) -> dict[str, object]:
 
 
 @router.get("/sessions/{session_id}")
-async def get_session(session_id: str, auth=Depends(get_auth_context)) -> dict[str, object]:
-    require_admin(auth)
+async def get_session(
+    session_id: str, auth: AuthContext = Depends(require_admin_auth)
+) -> dict[str, object]:
     try:
         sessions = await openclaw_call("sessions.list")
     except OpenClawGatewayError as exc:
@@ -69,8 +68,9 @@ async def get_session(session_id: str, auth=Depends(get_auth_context)) -> dict[s
 
 
 @router.get("/sessions/{session_id}/history")
-async def get_session_history(session_id: str, auth=Depends(get_auth_context)) -> dict[str, object]:
-    require_admin(auth)
+async def get_session_history(
+    session_id: str, auth: AuthContext = Depends(require_admin_auth)
+) -> dict[str, object]:
     try:
         history = await get_chat_history(session_id)
     except OpenClawGatewayError as exc:
@@ -84,9 +84,8 @@ async def get_session_history(session_id: str, auth=Depends(get_auth_context)) -
 async def send_session_message(
     session_id: str,
     payload: dict = Body(...),
-    auth=Depends(get_auth_context),
+    auth: AuthContext = Depends(require_admin_auth),
 ) -> dict[str, bool]:
-    require_admin(auth)
     content = payload.get("content")
     if not content:
         raise HTTPException(

backend/app/api/tasks.py

@@ -2,45 +2,36 @@ from __future__ import annotations
 
 from datetime import datetime
 
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends
 from sqlmodel import Session, select
 
-from app.core.auth import get_auth_context
+from app.api.deps import get_board_or_404, get_task_or_404, require_admin_auth
+from app.core.auth import AuthContext
 from app.db.session import get_session
-from app.models.activity_events import ActivityEvent
 from app.models.boards import Board
 from app.models.tasks import Task
 from app.schemas.tasks import TaskCreate, TaskRead, TaskUpdate
-from app.services.admin_access import require_admin
+from app.services.activity_log import record_activity
 
 router = APIRouter(prefix="/boards/{board_id}/tasks", tags=["tasks"])
 
 
 @router.get("", response_model=list[TaskRead])
 def list_tasks(
-    board_id: str,
+    board: Board = Depends(get_board_or_404),
     session: Session = Depends(get_session),
-    auth=Depends(get_auth_context),
+    auth: AuthContext = Depends(require_admin_auth),
 ) -> list[Task]:
-    require_admin(auth)
-    board = session.get(Board, board_id)
-    if board is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
     return list(session.exec(select(Task).where(Task.board_id == board.id)))
 
 
 @router.post("", response_model=TaskRead)
 def create_task(
-    board_id: str,
     payload: TaskCreate,
+    board: Board = Depends(get_board_or_404),
     session: Session = Depends(get_session),
-    auth=Depends(get_auth_context),
+    auth: AuthContext = Depends(require_admin_auth),
 ) -> Task:
-    require_admin(auth)
-    board = session.get(Board, board_id)
-    if board is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
-
     task = Task.model_validate(payload)
     task.board_id = board.id
     if task.created_by_user_id is None and auth.user is not None:
@@ -49,32 +40,23 @@ def create_task(
     session.commit()
     session.refresh(task)
 
-    event = ActivityEvent(
+    record_activity(
+        session,
         event_type="task.created",
         task_id=task.id,
         message=f"Task created: {task.title}.",
     )
-    session.add(event)
     session.commit()
     return task
 
 
 @router.patch("/{task_id}", response_model=TaskRead)
 def update_task(
-    board_id: str,
-    task_id: str,
     payload: TaskUpdate,
+    task: Task = Depends(get_task_or_404),
     session: Session = Depends(get_session),
-    auth=Depends(get_auth_context),
+    auth: AuthContext = Depends(require_admin_auth),
 ) -> Task:
-    require_admin(auth)
-    board = session.get(Board, board_id)
-    if board is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
-    task = session.get(Task, task_id)
-    if task is None or task.board_id != board.id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
-
     previous_status = task.status
     updates = payload.model_dump(exclude_unset=True)
     for key, value in updates.items():
@@ -91,25 +73,17 @@ def update_task(
     else:
         event_type = "task.updated"
         message = f"Task updated: {task.title}."
-    event = ActivityEvent(event_type=event_type, task_id=task.id, message=message)
-    session.add(event)
+    record_activity(session, event_type=event_type, task_id=task.id, message=message)
     session.commit()
     return task
 
 
 @router.delete("/{task_id}")
 def delete_task(
-    board_id: str,
-    task_id: str,
     session: Session = Depends(get_session),
-    auth=Depends(get_auth_context),
+    task: Task = Depends(get_task_or_404),
+    auth: AuthContext = Depends(require_admin_auth),
 ) -> dict[str, bool]:
-    require_admin(auth)
-    board = session.get(Board, board_id)
-    if board is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
-    task = session.get(Task, task_id)
-    if task and task.board_id == board.id:
-        session.delete(task)
-        session.commit()
+    session.delete(task)
+    session.commit()
     return {"ok": True}