Summary
SearchCIDsRequest and SearchRecordsRequest already support limit and offset (proto/agntcy/dir/search/v1/search_service.proto), but the responses carry no total match count. Any client that wants to paginate has no way to show "page 1 of N" or a total-results figure without streaming the entire result set just to count it — which defeats the purpose of pagination.
Motivation
The AI Catalog UI gets this right via AIFinderService.ListAgents, which returns total_count from CountCatalogEntries. But that endpoint is a catalog-specific projection (CatalogEntry) and excludes any record without an MCP/A2A/AgentSkills module, so it's not usable by general clients (CLI, TUIs such as lazydir, scripts) that list all records via SearchService.
The counting machinery already exists on the catalog side — it just isn't exposed on the general search API.
Proposal
Add a total count to the search responses. Two shapes to consider:
- A
uint32 total_count on a response header/first message of the stream, or
- A dedicated lightweight
CountRecords(SearchRecordsRequest) returns (CountResponse) RPC.
The count should honor the same queries as the request but ignore limit/offset (i.e. total matches, not page size), mirroring CountCatalogEntries.
References
proto/agntcy/dir/search/v1/search_service.proto — limit/offset already presentserver/database/gorm/catalog.go — CountCatalogEntries (existing count precedent)
Summary
SearchCIDsRequestandSearchRecordsRequestalready supportlimitandoffset(proto/agntcy/dir/search/v1/search_service.proto), but the responses carry no total match count. Any client that wants to paginate has no way to show "page 1 of N" or a total-results figure without streaming the entire result set just to count it — which defeats the purpose of pagination.Motivation
The AI Catalog UI gets this right via
AIFinderService.ListAgents, which returnstotal_countfromCountCatalogEntries. But that endpoint is a catalog-specific projection (CatalogEntry) and excludes any record without an MCP/A2A/AgentSkills module, so it's not usable by general clients (CLI, TUIs such as lazydir, scripts) that list all records viaSearchService.The counting machinery already exists on the catalog side — it just isn't exposed on the general search API.
Proposal
Add a total count to the search responses. Two shapes to consider:
uint32 total_counton a response header/first message of the stream, orCountRecords(SearchRecordsRequest) returns (CountResponse)RPC.The count should honor the same
queriesas the request but ignorelimit/offset(i.e. total matches, not page size), mirroringCountCatalogEntries.References
proto/agntcy/dir/search/v1/search_service.proto—limit/offsetalready presentserver/database/gorm/catalog.go—CountCatalogEntries(existing count precedent)