feat: expose calendar agent heartbeat api

app/schemas/calendar.py

@@ -407,3 +407,30 @@ class DateListResponse(BaseModel):
         default_factory=list,
         description="Sorted list of future dates with materialized slots",
     )
+
+
+# ---------------------------------------------------------------------------
+# Agent heartbeat / agent-driven slot updates
+# ---------------------------------------------------------------------------
+
+class AgentHeartbeatResponse(BaseModel):
+    """Slots that are due for a specific agent plus its current runtime status."""
+    slots: list[CalendarSlotItem] = Field(default_factory=list)
+    agent_status: str
+    message: Optional[str] = None
+
+
+class SlotAgentUpdate(BaseModel):
+    """Plugin-driven slot status update payload."""
+    status: SlotStatusEnum
+    started_at: Optional[dt_time] = None
+    actual_duration: Optional[int] = Field(None, ge=0, le=65535)
+
+
+class AgentStatusUpdateRequest(BaseModel):
+    """Plugin-driven agent status report."""
+    agent_id: str
+    claw_identifier: str
+    status: str
+    recovery_at: Optional[dt_datetime] = None
+    exhaust_reason: Optional[str] = None