# 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

- [x] Backend API endpoints
- [x] Frontend widget component
- [x] Widget registration
- [x] Tests written and passing
- [x] Lint clean
- [x] 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)