push both

src/docs/swagger.ts

@@ -139,6 +139,65 @@ export const swaggerSpec = swaggerJSDoc({
             },
           },
         },
+        ChatMessage: {
+          type: 'object',
+          properties: {
+            id: {
+              type: 'string',
+              format: 'uuid',
+            },
+            role: {
+              type: 'string',
+              enum: ['user', 'assistant', 'system'],
+              description: 'Message role (user = user message, assistant = agent response, system = system message)',
+            },
+            content: {
+              type: 'string',
+              description: 'Message content',
+            },
+            agentId: {
+              type: 'string',
+              format: 'uuid',
+            },
+            userId: {
+              type: 'string',
+              format: 'uuid',
+              nullable: true,
+            },
+            conversationId: {
+              type: 'string',
+              nullable: true,
+              description: 'Conversation ID this message belongs to',
+            },
+            metadata: {
+              type: 'object',
+              description: 'Additional message metadata (files, IPFS hashes, etc.)',
+              additionalProperties: true,
+            },
+            createdAt: {
+              type: 'string',
+              format: 'date-time',
+            },
+          },
+        },
+        ChatResponse: {
+          type: 'object',
+          properties: {
+            response: {
+              type: 'string',
+              description: 'Agent\'s response message',
+            },
+            conversationId: {
+              type: 'string',
+              description: 'Conversation ID for this chat session',
+            },
+            metadata: {
+              type: 'object',
+              description: 'Additional response metadata from agent',
+              additionalProperties: true,
+            },
+          },
+        },
       },
     },
     security: [{ bearerAuth: [] }],

src/routes/chatRoutes.ts

@@ -6,6 +6,13 @@ import { authenticate, optionalAuth } from '../middlewares/auth';
 const router = Router();
 const chatController = new ChatController();
 
+/**
+ * @swagger
+ * tags:
+ *   name: Chat
+ *   description: Chat protocol endpoints for communicating with agents
+ */
+
 // Configure multer for file uploads
 // Accept all file types (documents, images, code files, etc.)
 const upload = multer({
@@ -25,8 +32,131 @@ const upload = multer({
   },
 });
 
-// Chat endpoints - authentication optional for some agents (free tier)
-// Accepts multipart/form-data for file uploads
+/**
+ * @swagger
+ * /chat/{id}/message:
+ *   post:
+ *     summary: Send a message to an agent
+ *     tags: [Chat]
+ *     description: |
+ *       Send a text message and/or files to an agent. The system handles communication with any agent endpoint format.
+ *       
+ *       **Agent Communication Protocol:**
+ *       - Files are uploaded to IPFS first, then URLs are sent to the agent endpoint
+ *       - For text-only messages: Sends JSON payload to agent endpoint
+ *       - For messages with files: Sends multipart/form-data with file URLs (IPFS hashes)
+ *       - Supports custom headers via agent metadata (agent.metadata.headers)
+ *       - Works with any agent endpoint format (REST, GraphQL, custom APIs)
+ *       
+ *       **Payment:**
+ *       - First 2 tasks per user are free
+ *       - Admins can test unapproved agents without payment
+ *       - Regular users need sufficient wallet balance for approved agents
+ *     security:
+ *       - bearerAuth: []
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: string
+ *           format: uuid
+ *         description: Agent ID
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         multipart/form-data:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               message:
+ *                 type: string
+ *                 description: Text message (optional if files provided)
+ *                 example: "Hello, can you help me analyze this code?"
+ *               conversationId:
+ *                 type: string
+ *                 description: Conversation ID for continuing a conversation (optional)
+ *                 example: "conv_1234567890_abc123"
+ *               metadata:
+ *                 type: string
+ *                 description: JSON string of additional metadata (optional)
+ *                 example: '{"context": "code review", "language": "typescript"}'
+ *               files:
+ *                 type: array
+ *                 items:
+ *                   type: string
+ *                   format: binary
+ *                 description: Files to upload (images, documents, code files, etc.). Max 10 files, 10MB each.
+ *     responses:
+ *       200:
+ *         description: Message sent successfully, agent response returned
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 response:
+ *                   type: string
+ *                   description: Agent's response message
+ *                   example: "I'd be happy to help you analyze the code!"
+ *                 conversationId:
+ *                   type: string
+ *                   description: Conversation ID for this chat session
+ *                   example: "conv_1234567890_abc123"
+ *                 metadata:
+ *                   type: object
+ *                   description: Additional response metadata from agent
+ *                   additionalProperties: true
+ *       400:
+ *         description: Invalid request (missing message and files)
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 error:
+ *                   type: string
+ *                   example: "Message or files are required"
+ *       401:
+ *         description: Unauthorized (for agents requiring authentication)
+ *       402:
+ *         description: Insufficient wallet balance
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 error:
+ *                   type: string
+ *                   example: "Insufficient wallet balance"
+ *                 details:
+ *                   type: object
+ *                   properties:
+ *                     balance:
+ *                       type: number
+ *                       description: Current wallet balance in points
+ *                     required:
+ *                       type: number
+ *                       description: Required points for this task
+ *                     freeTasksRemaining:
+ *                       type: number
+ *                       description: Number of free tasks remaining
+ *                     message:
+ *                       type: string
+ *                       description: Human-readable message
+ *       404:
+ *         description: Agent not found
+ *       500:
+ *         description: Server error or agent endpoint error
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 error:
+ *                   type: string
+ *                   example: "Failed to send message to agent"
+ */
 router.post(
   '/:id/message',
   optionalAuth,
@@ -34,6 +164,85 @@ router.post(
   chatController.sendMessage.bind(chatController)
 );
 
+/**
+ * @swagger
+ * /chat/{id}/history:
+ *   get:
+ *     summary: Get conversation history with an agent
+ *     tags: [Chat]
+ *     description: |
+ *       Retrieve conversation history between the authenticated user and an agent.
+ *       Admins can view history for any agent (including pending/rejected), while regular users can only view history for approved agents.
+ *     security:
+ *       - bearerAuth: []
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: string
+ *           format: uuid
+ *         description: Agent ID
+ *       - in: query
+ *         name: conversationId
+ *         schema:
+ *           type: string
+ *         description: Filter by specific conversation ID
+ *         example: "conv_1234567890_abc123"
+ *       - in: query
+ *         name: limit
+ *         schema:
+ *           type: integer
+ *           default: 50
+ *           minimum: 1
+ *           maximum: 100
+ *         description: Maximum number of messages to return
+ *     responses:
+ *       200:
+ *         description: Conversation history retrieved successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 messages:
+ *                   type: array
+ *                   items:
+ *                     type: object
+ *                     properties:
+ *                       id:
+ *                         type: string
+ *                         format: uuid
+ *                       role:
+ *                         type: string
+ *                         enum: [user, assistant, system]
+ *                         description: Message role (user = user message, assistant = agent response)
+ *                       content:
+ *                         type: string
+ *                         description: Message content
+ *                       agentId:
+ *                         type: string
+ *                         format: uuid
+ *                       userId:
+ *                         type: string
+ *                         format: uuid
+ *                       conversationId:
+ *                         type: string
+ *                         description: Conversation ID this message belongs to
+ *                       metadata:
+ *                         type: object
+ *                         description: Additional message metadata (files, etc.)
+ *                         additionalProperties: true
+ *                       createdAt:
+ *                         type: string
+ *                         format: date-time
+ *       401:
+ *         description: Unauthorized - authentication required
+ *       404:
+ *         description: Agent not found
+ *       500:
+ *         description: Server error
+ */
 router.get(
   '/:id/history',
   authenticate,