feat(api, sdk-py, sdk-ts): add message observing status API (#89)

* feat: Add message observing status API (Issue #75)

- Query existing session_task_process_status field from messages table
- Map values: success→observed, running→in_process, pending→pending
- Implement Go API endpoint: GET /session/{id}/observing-status
- Add Python SDK method: messages_observing_status()
- Add TypeScript SDK method: messagesObservingStatus()
- Returns counts of observed, in_process, pending messages

Backend (Go):
- Model layer: MessageObservingStatus response type
- Repository layer: Direct query on messages table
- Service layer: Business logic wrapper
- Handler layer: HTTP endpoint with unit tests
- Router: URL registration
- Dependency injection: Full wiring

Python SDK:
- Type: MessageObservingStatus (Pydantic)
- Method: sessions.messages_observing_status()

TypeScript SDK:
- Schema: MessageObservingStatusSchema (Zod)
- Type: MessageObservingStatus
- Method: sessions.messagesObservingStatus()

Tests:
- Handler tests with mocks (all passing)

Note: Uses existing session_task_process_status field. No database migration needed.

* refactor: Consolidate observing status into session handler

Based on review feedback:
- Moved method to SessionHandler instead of separate handler
- Consolidated into existing session service/repo/model files
- Added async Python client method
- Deleted all separate message_observing_* files

Changes:
- Go: Added GetSessionObservingStatus to SessionHandler/Service/Repo
- Model: Added MessageObservingStatus struct to session.go
- Tests: Added handler tests to session_test.go
- Python: Added async version in async_sessions.py

* fix: Add GetObservingStatus mock method to service tests

* fix: Auto-format code with gofmt

- fixed aligment in main.go and router.go
- updated swagger doc

* fix: Change API path to snake_case

changed /observing-status -> observing_status

- Updated router registration
- Updated swagger doc
- Updated Python SDK (sync + async)
- Updated TS SDK

Author: slyt3

src/client/acontext-py/src/acontext/resources/async_sessions.py

@@ -15,6 +15,7 @@
     LearningStatus,
     ListSessionsOutput,
     Message,
+    MessageObservingStatus,
     Session,
     TokenCounts,
 )
@@ -346,3 +347,21 @@ async def get_token_counts(self, session_id: str) -> TokenCounts:
             "GET", f"/session/{session_id}/token_counts"
         )
         return TokenCounts.model_validate(data)
+
+async def messages_observing_status(self, session_id: str) -> MessageObservingStatus:
+        """Get message observing status counts for a session.
+        
+        Returns the count of messages by their observing status:
+        observed, in_process, and pending.
+        
+        Args:
+            session_id: The UUID of the session.
+        
+        Returns:
+            MessageObservingStatus object containing observed, in_process, 
+            pending counts and updated_at timestamp.
+        """
+        data = await self._requester.request(
+            "GET", f"/session/{session_id}/observing_status"
+        )
+        return MessageObservingStatus.model_validate(data)

src/client/acontext-py/src/acontext/resources/sessions.py

@@ -15,6 +15,7 @@
     LearningStatus,
     ListSessionsOutput,
     Message,
+    MessageObservingStatus,
     Session,
     TokenCounts,
 )
@@ -348,3 +349,20 @@ def get_token_counts(self, session_id: str) -> TokenCounts:
         """
         data = self._requester.request("GET", f"/session/{session_id}/token_counts")
         return TokenCounts.model_validate(data)
+    def messages_observing_status(self, session_id: str) -> MessageObservingStatus:
+        """Get message observing status counts for a session.
+        
+        Returns the count of messages by their observing status:
+        observed, in_process, and pending.
+        
+        Args:
+            session_id: The UUID of the session.
+        
+        Returns:
+            MessageObservingStatus object containing observed, in_process, 
+            pending counts and updated_at timestamp.
+        """
+        data = self._requester.request(
+            "GET", f"/session/{session_id}/observing_status"
+        )
+        return MessageObservingStatus.model_validate(data)

src/client/acontext-py/src/acontext/types/session.py

@@ -253,3 +253,19 @@ class TokenCounts(BaseModel):
         ...,
         description="Total token count for all text and tool-call parts in a session",
     )
+
+class MessageObservingStatus(BaseModel):
+    """Response model for message observing status."""
+    
+    observed: int = Field(
+        ..., description="Number of messages with observed status"
+    )
+    in_process: int = Field(
+        ..., description="Number of messages with in_process status"
+    )
+    pending: int = Field(
+        ..., description="Number of messages with pending status"
+    )
+    updated_at: str = Field(
+        ..., description="Timestamp when the status was retrieved"
+    )

src/client/acontext-ts/package-lock.json

@@ -17,6 +17,8 @@ import {
   ListSessionsOutput,
   ListSessionsOutputSchema,
   Message,
+  MessageObservingStatus,
+  MessageObservingStatusSchema, 
   MessageSchema,
   Session,
   SessionSchema,
@@ -264,5 +266,20 @@ export class SessionsAPI {
     const data = await this.requester.request('GET', `/session/${sessionId}/token_counts`);
     return TokenCountsSchema.parse(data);
   }
+
+  /**
+   * Get message observing status counts for a session.
+   *
+   * Returns the count of messages by their observing status:
+   * observed, in_process, and pending.
+   *
+   * @param sessionId - The UUID of the session.
+   * @returns MessageObservingStatus object containing observed, in_process, 
+   *          pending counts and updated_at timestamp.
+   */
+  async messagesObservingStatus(sessionId: string): Promise<MessageObservingStatus> {
+    const data = await this.requester.request('GET', `/session/${sessionId}/observing_status`);
+    return MessageObservingStatusSchema.parse(data);
+  }
 }
 

src/client/acontext-ts/src/resources/sessions.ts

@@ -127,6 +127,15 @@ export const TokenCountsSchema = z.object({
 
 export type TokenCounts = z.infer<typeof TokenCountsSchema>;
 
+export const MessageObservingStatusSchema = z.object({
+  observed: z.number(),
+  in_process: z.number(),
+  pending: z.number(),
+  updated_at: z.string(),
+});
+
+export type MessageObservingStatus = z.infer<typeof MessageObservingStatusSchema>;
+
 /**
  * Parameters for the remove_tool_result edit strategy.
  */

src/client/acontext-ts/src/types/session.ts

@@ -1245,6 +1245,56 @@ const docTemplate = `{
                 ]
             }
         },
+        "/session/{session_id}/observing_status": {
+            "get": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "description": "Returns the count of observed, in_process, and pending messages",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "session"
+                ],
+                "summary": "Get message observing status for a session",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "format": "uuid",
+                        "description": "Session ID",
+                        "name": "session_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "allOf": [
+                                {
+                                    "$ref": "#/definitions/serializer.Response"
+                                },
+                                {
+                                    "type": "object",
+                                    "properties": {
+                                        "data": {
+                                            "$ref": "#/definitions/model.MessageObservingStatus"
+                                        }
+                                    }
+                                }
+                            ]
+                        }
+                    }
+                }
+            }
+        },
         "/session/{session_id}/task": {
             "get": {
                 "security": [
@@ -3009,6 +3059,23 @@ const docTemplate = `{
                 }
             }
         },
+        "model.MessageObservingStatus": {
+            "type": "object",
+            "properties": {
+                "in_process": {
+                    "type": "integer"
+                },
+                "observed": {
+                    "type": "integer"
+                },
+                "pending": {
+                    "type": "integer"
+                },
+                "updated_at": {
+                    "type": "string"
+                }
+            }
+        },
         "model.Session": {
             "type": "object",
             "properties": {

src/server/api/go/docs/docs.go

@@ -1242,6 +1242,56 @@
                 ]
             }
         },
+        "/session/{session_id}/observing_status": {
+            "get": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "description": "Returns the count of observed, in_process, and pending messages",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "session"
+                ],
+                "summary": "Get message observing status for a session",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "format": "uuid",
+                        "description": "Session ID",
+                        "name": "session_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "allOf": [
+                                {
+                                    "$ref": "#/definitions/serializer.Response"
+                                },
+                                {
+                                    "type": "object",
+                                    "properties": {
+                                        "data": {
+                                            "$ref": "#/definitions/model.MessageObservingStatus"
+                                        }
+                                    }
+                                }
+                            ]
+                        }
+                    }
+                }
+            }
+        },
         "/session/{session_id}/task": {
             "get": {
                 "security": [
@@ -3006,6 +3056,23 @@
                 }
             }
         },
+        "model.MessageObservingStatus": {
+            "type": "object",
+            "properties": {
+                "in_process": {
+                    "type": "integer"
+                },
+                "observed": {
+                    "type": "integer"
+                },
+                "pending": {
+                    "type": "integer"
+                },
+                "updated_at": {
+                    "type": "string"
+                }
+            }
+        },
         "model.Session": {
             "type": "object",
             "properties": {

src/server/api/go/docs/swagger.json

@@ -304,6 +304,17 @@ definitions:
       updated_at:
         type: string
     type: object
+  model.MessageObservingStatus:
+    properties:
+      in_process:
+        type: integer
+      observed:
+        type: integer
+      pending:
+        type: integer
+      updated_at:
+        type: string
+    type: object
   model.Session:
     properties:
       configs:
@@ -1607,6 +1618,35 @@ paths:
             },
             { format: 'openai' }
           );
+  /session/{session_id}/observing_status:
+    get:
+      consumes:
+      - application/json
+      description: Returns the count of observed, in_process, and pending messages
+      parameters:
+      - description: Session ID
+        format: uuid
+        in: path
+        name: session_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            allOf:
+            - $ref: '#/definitions/serializer.Response'
+            - properties:
+                data:
+                  $ref: '#/definitions/model.MessageObservingStatus'
+              type: object
+      security:
+      - BearerAuth: []
+      summary: Get message observing status for a session
+      tags:
+      - session
   /session/{session_id}/task:
     get:
       consumes:

src/server/api/go/docs/swagger.yaml

@@ -240,6 +240,5 @@ func BuildContainer() *do.Injector {
 	do.Provide(inj, func(i *do.Injector) (*handler.ToolHandler, error) {
 		return handler.NewToolHandler(do.MustInvoke[*httpclient.CoreClient](i)), nil
 	})
-
 	return inj
 }