list_components

List components with pagination, projection, and filters.

list_components

List components (agents, skills, hooks, plugins) registered in VantagePeers, with pagination, projection (lite|full), and optional filters.

Args

Returns

{
  items: Component[] | ComponentLite[],
  nextCursor: string | null
}

nextCursor is null when the current page is the last one; non-null when more rows exist.

Examples

Compact list (fields=lite)

// call
{ "limit": 20, "fields": "lite" }

// response (~3KB for 100 components)
{
  "items": [
    {
      "_id": "j5xxx...",
      "_creationTime": 1782050000000,
      "name": "dev-convex-expert",
      "type": "agent",
      "team": "development"
    }
  ],
  "nextCursor": "eyJjcmVhdGlvblRpbWUiOjE3ODIwNDk5MDAwMDAsImlkIjoiajV5eXkifQ=="
}

Paginate through all skill components

// page 1
{ "type": "skill", "limit": 20 }
// → { items: [...], nextCursor: "..." }

// page 2 (use nextCursor)
{ "type": "skill", "limit": 20, "cursor": "<nextCursor from page 1>" }

Pagination + envelope safety

list_components follows the standard VantagePeers envelope safety pattern (PR-B):

• Default limit: 20. Keeps payloads small (~2-3KB) for typical interactive calls.
• Cap: 200. Requests with limit > 200 are clamped server-side.
• fields=lite: projects to 5 stable keys (_id, _creationTime, name, type, team). Payload stays under 25KB even for 100 components.
• Cursor: opaque token encoding {creationTime, id} to survive same-millisecond inserts. Treat as opaque — do not parse client-side.
• Hybrid cursor decode: old-format {createdBefore} cursors (S3.3 B8 callers) are decoded and forwarded as createdBefore for back-compat. New-format opaque cursors pass through directly.

Same pattern applies to list_bus (PR-A) and list_repo_mappings (PR-C).

Why this matters