From 8f144f3a811ab40e26514fe60fafbbdd35bad23d Mon Sep 17 00:00:00 2001
From: soryu <soryu@soryu.co>
Date: Sun, 1 Feb 2026 01:07:13 +0000
Subject: feat: Add Supervisor Status API endpoints (Phase 3 Task 3.5)

Implement REST API endpoints for querying supervisor status:

- GET /api/v1/contracts/{id}/supervisor/status
  Returns current supervisor status including task_id, state, phase,
  current_activity, progress, last_heartbeat, and pending_task_ids

- GET /api/v1/contracts/{id}/supervisor/heartbeats?limit=10
  Returns paginated supervisor activity history from history_events

- POST /api/v1/contracts/{id}/supervisor/sync
  Triggers a sync to refresh the supervisor's last_activity timestamp

New types added:
- SupervisorStatusResponse - Status endpoint response
- SupervisorHeartbeatEntry - Individual heartbeat history entry
- SupervisorHeartbeatHistoryResponse - Heartbeat history with pagination
- SupervisorSyncResponse - Sync endpoint response
- HeartbeatHistoryQuery - Query params for heartbeats endpoint

Repository helpers:
- get_supervisor_status() - Combined info from supervisor_states and tasks
- get_supervisor_activity_history() - Activity timeline from history_events
- count_supervisor_activity_history() - Total count for pagination
- sync_supervisor_state() - Refresh last_activity timestamp

Error handling:
- 404 for contract not found (CONTRACT_NOT_FOUND)
- 404 for no supervisor (SUPERVISOR_NOT_FOUND)
- Proper fallback when supervisor_state record doesn't exist but task does

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 makima/src/db/models.rs | 76 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)

(limited to 'makima/src/db/models.rs')

diff --git a/makima/src/db/models.rs b/makima/src/db/models.rs
index 636d81a..f1e0be0 100644
--- a/makima/src/db/models.rs
+++ b/makima/src/db/models.rs
@@ -2395,3 +2395,79 @@ impl std::str::FromStr for NotificationSeverity {
         }
     }
 }
+
+// ============================================================================
+// Supervisor Status API Types
+// ============================================================================
+
+/// Response for supervisor status endpoint
+#[derive(Debug, Clone, Serialize, ToSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct SupervisorStatusResponse {
+    /// The supervisor task ID
+    pub task_id: Uuid,
+    /// Current supervisor state (from supervisor_states table)
+    pub state: String,
+    /// Current contract phase
+    pub phase: String,
+    /// Description of current activity (from task progress_summary)
+    pub current_activity: Option<String>,
+    /// Progress percentage (0-100)
+    pub progress: Option<u8>,
+    /// When the supervisor last updated its state
+    pub last_heartbeat: DateTime<Utc>,
+    /// Task IDs the supervisor is currently waiting on
+    pub pending_task_ids: Vec<Uuid>,
+    /// Whether the supervisor is currently running
+    pub is_running: bool,
+}
+
+/// Individual heartbeat entry for history
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct SupervisorHeartbeatEntry {
+    /// Timestamp of this heartbeat
+    pub timestamp: DateTime<Utc>,
+    /// Supervisor state at this time
+    pub state: String,
+    /// Activity description at this time
+    pub activity: Option<String>,
+    /// Progress at this time
+    pub progress: Option<u8>,
+    /// Contract phase at this time
+    pub phase: String,
+    /// Pending task IDs at this time
+    pub pending_task_ids: Vec<Uuid>,
+}
+
+/// Response for supervisor heartbeat history endpoint
+#[derive(Debug, Clone, Serialize, ToSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct SupervisorHeartbeatHistoryResponse {
+    /// List of heartbeat entries
+    pub heartbeats: Vec<SupervisorHeartbeatEntry>,
+    /// Total count of heartbeats (for pagination)
+    pub total: i64,
+}
+
+/// Response for supervisor sync endpoint
+#[derive(Debug, Clone, Serialize, ToSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct SupervisorSyncResponse {
+    /// Whether the sync was successful
+    pub synced: bool,
+    /// Current supervisor state after sync
+    pub state: String,
+    /// Optional message about the sync result
+    pub message: Option<String>,
+}
+
+/// Query parameters for heartbeat history endpoint
+#[derive(Debug, Deserialize, ToSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct HeartbeatHistoryQuery {
+    /// Maximum number of heartbeats to return (default: 10)
+    pub limit: Option<i32>,
+    /// Offset for pagination (default: 0)
+    pub offset: Option<i32>,
+}
-- 
cgit v1.2.3