feat(agent): agent review queue, versioning, bundles, archive & draft workflow

[Apoorvgarg-creator]

Purpose / Description

Comprehensive agent platform improvements: review queue with component gating, semver versioning, component bundles, soft-delete (archive), draft save workflow, interactive CLI search, leaderboard enhancements, and creator attribution.

Original PR: Agent CLI commands (interactive wizard, paginated list, name validation, scope options for all IDEs).

Added on top: Review/approval pipeline, versioning, bundles, archive, drafts, leaderboard, interactive search.

What's Done

Database & Models

• Migration 0010: Fix variable shadowing bug in dedup loop
• Migration 0011: Extend AgentStatus (pending, rejected), ListingStatus (archived), create component_bundles table, add bundle_id FK to all 5 listing tables, add rejection_reason to agents
• ComponentBundle model (id, name, description, submitted_by, created_at)
• bundle_id nullable FK on McpListing, SkillListing, HookListing, PromptListing, SandboxListing

Semver Versioning

• services/versioning.py — parse, validate, bump, suggest
• Pydantic validators on AgentCreateRequest.version and AgentUpdateRequest.version
• version_bump_type field on AgentUpdateRequest
• GET /agents/{id}/version-suggestions endpoint
• Auto-bump in update_agent when version_bump_type provided
• 12 unit tests for versioning utilities

Agent Review Queue

• GET /api/v1/review?tab=agents — list pending agents with component readiness
• POST /api/v1/review/agents/{id}/approve — gated: rejects if any component not approved (422 with blocker details)
• POST /api/v1/review/agents/{id}/reject — sets rejected status with reason

Bundle Review (Atomic)

• POST /api/v1/review/bundles/{id}/approve — approves all components in bundle atomically
• POST /api/v1/review/bundles/{id}/reject — rejects all with shared reason
• Bundle name resolution in component review list

Agent Archive (Soft Delete)

• PATCH /api/v1/agents/{id}/archive — admin only, sets status to archived
• CLI agent delete now calls archive endpoint instead of hard delete

Draft Workflow

• POST /api/v1/agents/draft — create agent as draft (relaxed validation)
• PUT /api/v1/agents/{id}/draft — update a draft
• POST /api/v1/agents/{id}/submit — validate components, transition draft to pending
• CLI agent publish --draft and agent publish --submit

Created-By Email & Leaderboard

• created_by_email on AgentSummary, AgentResponse, LeaderboardItem
• Batch-fetch creator emails in list_agents, get_agent, create_agent, update_agent
• GET /overview/leaderboard?user=email — filter by creator
• GET /overview/component-leaderboard — new endpoint for MCP downloads ranked by user
• GitHub issue feat: add username field to user model (unique, alongside email) #339 created for username field

CLI Enhancements

• Interactive search (-i flag) on agent list and registry mcp list using questionary fuzzy select
• Version bump prompt on agent publish --update (patch/minor/major/keep)
• --beta flag on agent init (defaults to 0.1.0)
• client.patch() method added
• Created-by email column in agent list table and agent show detail

What's Left (TODO)

Frontend (not started)

• Review page: Agents tab alongside Components tab
  • Pending agents with component readiness indicator (green/red per component)
  • Approve button disabled when components_ready === false with tooltip
  • Expandable blocker list
  • Bundle grouping with Review Bundle action
• Agent three-dot menu (admin): Archive action with confirmation dialog
• StatusBadge: add archived style (gray, no ping)
• Version bump dialog in agent builder (patch/minor/major radio with live preview)
• Draft save: localStorage auto-save + Save Draft button + My Drafts section
• Leaderboard: user filter input, tabs for agents vs components
• API client hooks for new endpoints

Bulk Upload

• POST /api/v1/bulk/agents — bulk create with inline component auto-create, dedup, dry-run
• schemas/bulk.py — BulkAgentItem, BulkAgentRequest, BulkResult
• CLI agent bulk-create --from-file with dry-run preview and confirmation

Additional Tests

• test_agent_review.py — status transitions, component gating, reject with reason
• test_bundles.py — bundle CRUD, atomic approve/reject
• test_bulk.py — bulk create with dedup, dry_run, inline component auto-create
• test_draft_workflow.py — draft save, update, submit transition

How Has This Been Tested?

• uv run pytest tests/ -x -q — 1138 tests pass (0 failures)
• uv run ruff check . — clean for all changed files
• uv run ruff format --check . — clean for all changed files

Checklist

• All commits are signed off (git commit -s) per the DCO
• Descriptive commit messages
• Self-review completed
• UI changes: N/A for this commit (frontend TODO above)