feat: add safe miner control foundation

backend/app/agent_commands/router.py

@@ -0,0 +1,57 @@
+"""HTTP boundary for authenticated Agent command transport."""
+
+import logging
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+
+from app.agent_commands.dependencies import get_agent_command_service, require_agent_identity
+from app.agent_commands.exceptions import (
+    AgentCommandConflict,
+    AgentCommandNotFound,
+    AgentResultValidationError,
+)
+from app.agent_commands.models import (
+    AgentCommandListResponse,
+    AgentCommandResultRequest,
+    AgentCommandResultResponse,
+)
+from app.agent_commands.service import AgentCommandService
+
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/agent/commands", tags=["agent-commands"])
+AgentIdentity = Annotated[str, Depends(require_agent_identity)]
+AgentService = Annotated[AgentCommandService, Depends(get_agent_command_service)]
+
+
+@router.get("/pending", response_model=AgentCommandListResponse)
+def claim_pending_commands(
+    request: Request, agent_id: AgentIdentity, service: AgentService
+) -> AgentCommandListResponse:
+    before_claim = getattr(
+        request.app.state, "agent_command_before_claim", None
+    )
+    if callable(before_claim):
+        try:
+            before_claim()
+        except Exception:
+            logger.exception("Scheduled command materialization failed before Agent claim")
+    return AgentCommandListResponse(commands=service.claim(agent_id))
+
+
+@router.post("/result", response_model=AgentCommandResultResponse)
+def submit_command_result(
+    request: AgentCommandResultRequest,
+    agent_id: AgentIdentity,
+    service: AgentService,
+) -> AgentCommandResultResponse:
+    try:
+        service.submit_result(agent_id, request)
+    except AgentCommandNotFound as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except AgentCommandConflict as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    except AgentResultValidationError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return AgentCommandResultResponse(command_id=request.command_id, status=request.status)