stack/docs/scratchpads/52-active-projects-widget.md

Issue #52: Active Projects & Agent Chains Widget

Objective

Implement a HUD widget that displays all active projects and their agent chains for easy visual tracking.

Approach

Backend (API)

1. Added new widget data response types in widget-data.service.ts:

   • WidgetProjectItem - for active project data
   • WidgetAgentSessionItem - for agent session data

2. Created two new service methods in WidgetDataService:

   • getActiveProjectsData() - fetches projects where status = 'ACTIVE'
   • getAgentChainsData() - fetches agent sessions where isActive = true

3. Added two new controller endpoints in widgets.controller.ts:

   • POST /api/widgets/data/active-projects
   • POST /api/widgets/data/agent-chains

Frontend (Web)

1. Created ActiveProjectsWidget.tsx component with:

   • Active Projects panel showing:
     • Project name with color indicator
     • Last activity timestamp
     • Task and event counts
     • Status indicator
   • Agent Chains panel showing:
     • Agent label/name
     • Status indicator with icon animation
     • Runtime duration (formatted)
     • Message count and channel
     • Expandable context summary
   • Real-time updates (projects: 30s, agents: 10s)
   • PDA-friendly language ("Running" vs "URGENT")

2. Registered widget in WidgetRegistry.tsx:

   • Name: ActiveProjectsWidget
   • Display name: "Active Projects & Agent Chains"
   • Default size: 2x3 grid units
   • Configurable size: 2x2 to 4x4

Testing

Created comprehensive test suite in ActiveProjectsWidget.test.tsx:

• ✅ Loading state rendering
• ✅ Active projects list rendering
• ✅ Agent sessions list rendering
• ✅ Empty state handling
• ✅ Expandable session details
• ✅ Runtime formatting
• ✅ Count badge display

Test Results: 7/7 tests passing

Progress

• Backend API endpoints
• Frontend widget component
• Widget registration
• Tests written and passing
• Lint clean
• Type-check clean

Implementation Details

Status Indicators Used

Following PDA-friendly design principles:

• 🟢 Active (green) - not "CRITICAL" or demanding
• 🔵 Running (blue) - for active agents
• ⚪ Ended (gray) - for completed sessions

Real-time Updates

• Projects: Refresh every 30 seconds
• Agent Chains: Refresh every 10 seconds (more frequent due to dynamic nature)
• Future enhancement: WebSocket support for live updates

Expandable Details

Agent sessions can be clicked to reveal:

• Context summary (if available)
• Provides quick insight without cluttering the view

Notes

• Pre-existing build error in federation/guards/capability.guard.ts (not related to this issue)
• Pre-existing test failures in federation module (not related to this issue)
• All widget-specific tests pass
• No lint errors in changed files
• Type-checking clean for widget files

Files Modified

1. apps/api/src/widgets/widget-data.service.ts - Added new data fetching methods
2. apps/api/src/widgets/widgets.controller.ts - Added new endpoints
3. apps/web/src/components/widgets/ActiveProjectsWidget.tsx - New widget component
4. apps/web/src/components/widgets/WidgetRegistry.tsx - Registered widget
5. apps/web/src/components/widgets/__tests__/ActiveProjectsWidget.test.tsx - New tests

Next Steps

• Create PR for review
• Manual QA testing in browser
• Verify real-time updates work correctly
• Test with various data scenarios (empty, many projects, many agents)