feat: add msglib bounded message listing

internal/msglib/sidecar_client.go

@@ -22,6 +22,9 @@ const (
 
 	DefaultDisplayEntityLimit = 25
 	MaxDisplayEntityLimit     = 100
+
+	DefaultListMessagesLimit = 20
+	MaxListMessagesLimit     = 50
 )
 
 var requestCounter uint64
@@ -97,6 +100,54 @@ type MessageSource struct {
 	RowCount        string   `json:"row_count"`
 }
 
+type ListMessagesOptions struct {
+	ConversationID            string
+	ConversationType          string
+	Query                     string
+	Since                     string
+	Cursor                    string
+	Limit                     int
+	IncludeBody               bool
+	IncludeAttachmentMetadata bool
+}
+
+type ListMessagesResult struct {
+	ReadOnly                  bool          `json:"read_only"`
+	MessageBodyValuesReturned bool          `json:"message_body_values_returned"`
+	RawRowsReturned           bool          `json:"raw_rows_returned"`
+	FilePathsReturned         bool          `json:"file_paths_returned"`
+	SourceTables              []string      `json:"source_tables"`
+	Messages                  []ListMessage `json:"messages"`
+	NextCursor                string        `json:"next_cursor"`
+}
+
+type ListMessage struct {
+	MessageID        string                  `json:"message_id"`
+	ID               string                  `json:"id"`
+	ConversationID   string                  `json:"conversation_id"`
+	ConversationType string                  `json:"conversation_type"`
+	SenderID         string                  `json:"sender_id"`
+	SenderName       string                  `json:"sender_name"`
+	ReceiverID       string                  `json:"receiver_id"`
+	Text             string                  `json:"text"`
+	ContentText      string                  `json:"content_text"`
+	ContentType      string                  `json:"content_type"`
+	Timestamp        string                  `json:"timestamp"`
+	CreatedAt        string                  `json:"created_at"`
+	Subject          string                  `json:"subject"`
+	Read             bool                    `json:"read"`
+	Source           string                  `json:"source"`
+	RawRef           string                  `json:"raw_ref"`
+	Attachments      []ListMessageAttachment `json:"attachments"`
+}
+
+type ListMessageAttachment struct {
+	FileID      string `json:"file_id"`
+	FileName    string `json:"file_name"`
+	SizeBytes   int64  `json:"size_bytes"`
+	DownloadRef string `json:"download_ref"`
+}
+
 type DisplayEntitiesOptions struct {
 	EntityType string
 	Query      string
@@ -162,6 +213,46 @@ func (c *Client) MessageSources(ctx context.Context) ([]MessageSource, error) {
 	return out.MessageSources, nil
 }
 
+func (c *Client) ListMessages(ctx context.Context, opts ListMessagesOptions) (ListMessagesResult, error) {
+	if strings.TrimSpace(opts.Cursor) != "" {
+		return ListMessagesResult{}, errors.New("msglib list_messages cursor pagination is not available yet")
+	}
+	limit := opts.Limit
+	if limit <= 0 {
+		limit = DefaultListMessagesLimit
+	}
+	if limit > MaxListMessagesLimit {
+		limit = MaxListMessagesLimit
+	}
+
+	args := map[string]any{
+		"sqlite_dll_path":             c.config.SQLiteDLLPath,
+		"db_path":                     c.config.DBPath,
+		"password":                    c.config.Password,
+		"limit":                       limit,
+		"include_body":                opts.IncludeBody,
+		"include_attachment_metadata": opts.IncludeAttachmentMetadata,
+	}
+	if strings.TrimSpace(opts.ConversationID) != "" {
+		args["conversation_id"] = strings.TrimSpace(opts.ConversationID)
+	}
+	if strings.TrimSpace(opts.ConversationType) != "" {
+		args["conversation_type"] = strings.TrimSpace(opts.ConversationType)
+	}
+	if strings.TrimSpace(opts.Query) != "" {
+		args["query"] = strings.TrimSpace(opts.Query)
+	}
+	if strings.TrimSpace(opts.Since) != "" {
+		args["since"] = strings.TrimSpace(opts.Since)
+	}
+
+	var out ListMessagesResult
+	if err := c.call(ctx, "list_messages", args, &out); err != nil {
+		return ListMessagesResult{}, err
+	}
+	return out, nil
+}
+
 func (c *Client) DisplayEntities(ctx context.Context, opts DisplayEntitiesOptions) ([]DisplayEntity, error) {
 	entityType := strings.TrimSpace(opts.EntityType)
 	if entityType != EntityTypeContacts && entityType != EntityTypeGroups {