feat(agents): Add interview agent enhancements and context file uploads

[mathaix]

Summary

• Add context files upload/delete API for interview agents with file type validation
• Add project agents aggregation endpoint (GET /project/{project_id}/agents) to list all agents across sessions
• Fix add_agent flow to create fresh sessions instead of copying blueprint state
• Update ProjectDetailPage to properly display agents from all active sessions for a project
• Add AgentContextFile model for tracking file uploads per agent

Changes

Backend

• context_files.py: New API endpoints for file upload/download/delete
• file_service.py: File handling service with type validation
• design_sessions.py: Added agents aggregation endpoint, simplified add_agent logic
• models.py: Added AgentContextFile database model

Frontend

• context-files.ts: API client for context file operations
• design-sessions.ts: Added getProjectAgents API function
• ProjectDetailPage.tsx: Updated to use aggregated agents from all sessions
• types/design-session.ts: Added ProjectAgentInfo, ProjectAgentsResponse types

Test plan

• Create a project and add multiple agents via "Add Interview Agent"
• Verify all agents display on project detail page
• Upload context files to agents and verify they appear
• Delete context files and verify removal
• Verify simulation links work with correct session/agent references

🤖 Generated with Claude Code

[claude]

Pull Request Review

This is a substantial feature addition that adds context file upload capabilities and project-level agent aggregation. Here is my detailed feedback:

---

Strengths

Security Implementation (Excellent)

The file upload security is well-designed and follows best practices:

• Magic byte validation (not just extension checking) - prevents malicious file masquerading
• Path traversal prevention with proper sanitization at src/backend/clara/services/file_service.py:338-340
• Filename sanitization with regex patterns for dangerous characters
• File size limits and configurable constraints
• Sandboxed storage per project/agent
• SHA-256 checksums for integrity verification
• Restrictive file permissions (0o600 for files, 0o700 for directories)
• Soft delete implementation (preserves audit trail)

Architecture Quality

• Clean separation of concerns (Security, Storage, Extraction, Upload services)
• Proper use of dataclasses for results
• AG-UI event integration for real-time updates
• Database model follows project conventions with proper indexes
• API endpoints are RESTful and well-structured

---

Critical Issues

1. Missing Database Migration

Location: src/backend/clara/db/models.py:296-349

The AgentContextFile model was added but I do not see a corresponding Alembic migration in the PR.

Impact: Database schema will be out of sync, causing runtime errors.

Fix Required: Run alembic revision --autogenerate to create migration

2. No Test Coverage

Impact: Zero tests for significant new functionality increases risk of regressions.

Missing Tests:

• Unit tests for FileSecurityService (filename sanitization, validation logic)
• Unit tests for ContentExtractionService (PDF, DOCX, XLSX extraction)
• Integration tests for file upload/delete API endpoints
• Security tests (path traversal attempts, oversized files, invalid MIME types)

3. Duplicate Database Commits

Location: src/backend/clara/api/context_files.py:138, 155

Two sequential commits in the same transaction creates race condition potential. Combine into single commit for atomicity. Apply same fix at line 257.

---

Medium Priority Issues

4. Missing Dependencies Documentation

The PR adds dependencies (pypdf, python-docx, openpyxl) but they are marked as optional in code with try/except ImportError. Users will not know these are required for full functionality.

Recommendation: Document in README or add proper extras in pyproject.toml

5. Broad Exception Handling

Location: src/backend/clara/services/file_service.py:462-464

Broad except Exception catches everything including KeyboardInterrupt and SystemExit. Use specific exceptions instead.

6. Magic Number

Location: src/backend/clara/services/file_service.py:378

MAX_EXTRACTED_LENGTH = 50000 should be moved to config.py with documentation

7. Unnecessary List Copy

Location: src/backend/clara/api/context_files.py:141

Unnecessary list() conversion copies entire agents array. Modify in place instead.

---

Minor Issues

8. OOXML Detection Robustness

Current approach checks for markers in first 2KB. Consider using proper ZIP parsing with zipfile module.

9. Frontend Loading States

File upload shows loading indicator but lacks individual file progress, success confirmation, or client-side validation.

10. Comment Clarity

Location: src/backend/clara/agents/design_assistant.py:265-269

Add context explaining why get_agent_context was added to this phase.

---

Recommendations

Before Merging:

1. Add Alembic migration for AgentContextFile model
2. Fix double commit in upload_context_file endpoint
3. Add basic unit tests for security service

Post-Merge:

4. Add comprehensive test coverage
5. Add client-side file validation
6. Document file extraction dependencies
7. Add file upload progress indicators

---

Risk Assessment

Category	Risk	Notes
Security	Low	Excellent validation implementation
Database	High	Missing migration will cause errors
Testing	Medium	No tests increases regression risk
Performance	Low	File size limits prevent abuse
Maintainability	Low	Clean, well-structured code

---

Overall Assessment

This is high-quality work with excellent security practices. The main blocker is the missing database migration. Once that is added along with the double-commit fix, this is ready to merge.

The lack of tests is concerning for file uploads (high-risk feature), but can be addressed in follow-up PR.

Recommendation: Request changes for items 1-3, then approve.

Great job on the security implementation!