Phase 3 Step 4: Agent Management & Cross-Component Integration#

🎯 Integration Step - This step completes agent management functionality and implements comprehensive cross-component integration workflows.

Table of Contents#

Phase 3 Step 4: Agent Management & Cross-Component Integration

Overview#

With advanced features implemented, this step focuses on completing agent management capabilities and ensuring all components work together seamlessly through comprehensive integration testing and workflow validation.

Critical Context Notes#

Agent Architecture: Agents report via DeviceStatus, TaskStatus, and HashcatGuess objects from contracts/v1_api_swagger.json specification
Agent Details Modal: 5-tab interface (Settings, Hardware, Performance, Log, Capabilities) with admin-only access controls
Hardware Management: Backend devices from --backend-info, stored as Agent.devices list and backend_device comma-separated integers
Performance Monitoring: Real-time charts using DeviceStatus.speed over 8-hour windows, donut charts for utilization
Benchmark System: HashcatBenchmark model with hash_type_id, runtime, hash_speed, device fields; supports --benchmark-all vs --benchmark
Integration Workflows: End-to-end campaign creation to execution, resource upload to attack usage, agent registration to task assignment
Error Recovery: Network failure handling, large file upload resumption, concurrent user modification resolution
Cross-Component Testing: Full workflows must work across campaigns, attacks, resources, agents, and users with proper permissions
Testing Strategy: All user-facing functionality must have both E2E tests (mocked and full E2E). Follow the full testing architecture document and refer to .cursor/rules/testing/e2e-docker-infrastructure.mdc and .cursor/rules/testing/testing-patterns.mdc for detailed guidelines.
E2E Testing Structure: frontend/e2e/ contains mocked E2E tests (fast, no backend), frontend/tests/e2e/ contains full E2E tests (slower, real backend). Configs: playwright.config.ts (mocked) vs playwright.config.e2e.ts (full backend)

Complete Agent Management Implementation#

Agent Registration Enhancement#

🔧 Technical Context: Agent registration modal requires label (custom_label) and project toggles. After creation, displays agent token once for copy/paste. Token format: csa_<agent_id>_<random_string>. Modal must use idiomatic Shadcn-Svelte dialog and form components.

AGENT-REG-001: Complete agent registration workflow
- New agent registration form (modal interface with label and project toggles) (AGT-002a)
  - Modal Interface: Shadcn-Svelte dialog with agent registration form
  - Form Fields: Agent label (custom_label) and project assignment toggles
  - Validation: Real-time form validation with clear error messaging
- Agent token generation and display (immediate token display, shown only once) (AGT-002b)
  - Token Display: One-time display of generated agent token for copy/paste
  - Token Format: csa_<agent_id>_<random_string> with copy button
  - Security Notice: Clear warning that token won't be shown again
- Agent project assignment (multi-toggle interface for project membership) (AGT-002c)
  - Project Toggles: Multi-select interface for project membership
  - Permission Context: Clear indication of what project access means
  - Validation: Ensure at least one project is selected
- Agent configuration validation (AGT-002d)
  - Form Validation: Client-side and server-side validation
  - Error Feedback: Clear error messages for invalid configurations
- Agent registration confirmation (AGT-002e)
  - Success Feedback: Clear confirmation of successful agent registration
  - Next Steps: Guidance on how to configure the agent with the token
- Quick registration workflow (streamlined for immediate setup) (AGT-002f)
  - Streamlined Flow: Minimal steps for quick agent setup
  - Default Values: Sensible defaults for common configurations

🔧 Technical Context: Agent details modal has 5 tabs (Settings, Hardware, Performance, Log, Capabilities). Display name uses agent.custom_label or agent.host_name fallback pattern. Hardware devices from --backend-info stored as list and comma-separated integers. Modal must use idiomatic Shadcn-Svelte tabs, forms, and data display components.

Agent Administration (Admin Only)#

AGENT-ADMIN-001: Agent administrative functions
- Agent restart command (AGT-004a)
- Agent deactivation with confirmation (AGT-004b)
- Device toggle (GPU enable/disable) (AGT-004c)
- Agent benchmark trigger (AGT-004d)
- Agent deletion with impact assessment (AGT-004e)

Cross-Component Integration Implementation#

End-to-End Campaign Workflows#

Cross-Component Integration Workflows#

Error Recovery & Edge Cases#

Error Page Implementation#

ERROR-PAGES-001: Error page implementation
- Resource error page display and recovery options (INT-004a)
- Campaign error page with helpful guidance (INT-004b)
- Error page navigation and back functionality (INT-004c)
- Error state persistence and refresh behavior (INT-004d)
- Error reporting and feedback mechanisms (INT-004e)

Agent Management Testing#

Testing Guidelines & Requirements#

🧪 Critical Testing Context:

Test Structure: All user-facing functionality must have both E2E tests (mocked and full E2E). Strictly follow existing test structure and naming conventions as described in the full testing architecture document.
Test Execution:
- Run just test-frontend for mocked E2E tests (fast, no backend required)
- Run just test-e2e for full E2E tests (requires Docker setup, slower but complete integration testing)
- Important: Do not run full E2E tests directly - they require setup code and must run via the just test-e2e command
Test Utilities: Use or reuse existing test utils and helpers in frontend/tests/test-utils.ts for consistency and maintainability
API Integration: The OpenAPI spec for the current backend is in contracts/current_api_openapi.json and should be used for all backend API calls, with Zod objects generated from the spec in frontend/src/lib/schemas/
Test Notation: When tasks include notations like (E2E) or (Mock), tests must be created or updated to cover that specific functionality and confirm it works as expected

UI/UX Requirements & Standards#

Responsive Design: Ensure the interface is polished and follows project standards. While mobile support is not a priority, it should be functional and usable on modern desktop browsers and tablets from 1080x720 resolution on up. It is reasonable to develop for support of mobile resolutions.
Offline Capability: Ability to operate entirely without internet connectivity is a priority. No functionality should depend on public CDNs or other internet-based services.
API Integration: The OpenAPI spec for the current backend is in contracts/current_api_openapi.json and should be used for all backend API calls, with Zod objects having been generated from the spec in frontend/src/lib/schemas/.
Testing Coverage: All forms must be validated using the OpenAPI spec and the Zod objects. All forms must be validated on both server side and client side.

Agent List & Monitoring Testing#

TEST-AGT-001: Agent List & Monitoring Tests
- AGT-001a: Agent list page loads with real-time status (E2E + Mock)
- AGT-001b: Agent filtering by status (online, offline, error) (Mock)
- AGT-001c: Agent search and sorting functionality (Mock)
- AGT-001d: Agent performance metrics display (Mock)
- AGT-001e: Agent health monitoring and alerts (E2E + Mock)
- AGT-001f: Information density optimization (Mock)
- AGT-001g: Role-based gear menu visibility (Mock)

Agent Registration Testing#

TEST-AGT-002: Agent Registration Tests
- AGT-002a: New agent registration form (E2E + Mock)
- AGT-002b: Agent token generation and display (E2E + Mock)
- AGT-002c: Agent project assignment (E2E + Mock)
- AGT-002d: Agent configuration validation (Mock)
- AGT-002e: Agent registration confirmation (E2E + Mock)
- AGT-002f: Quick registration workflow (Mock)

TEST-AGT-003: Agent Details Modal Tests
- AGT-003a: Agent settings tab functionality (E2E + Mock)
- AGT-003b: Agent hardware tab with device management (Mock)
- AGT-003c: Agent performance tab with live data (E2E + Mock)
- AGT-003d: Agent logs tab with timeline interface (Mock)
- AGT-003e: Agent capabilities tab with benchmarks (Mock)
- AGT-003f: Hardware graceful degradation (Mock)
- AGT-003g: Benchmark management functionality (E2E + Mock)

Agent Administration Testing#

TEST-AGT-004: Agent Administration Tests (Admin Only)
- AGT-004a: Agent restart command (E2E + Mock)
- AGT-004b: Agent deactivation with confirmation (E2E + Mock)
- AGT-004c: Device toggle (GPU enable/disable) (E2E + Mock)
- AGT-004d: Agent benchmark trigger (E2E + Mock)
- AGT-004e: Agent deletion with impact assessment (E2E + Mock)

Integration & Workflow Testing#

End-to-End Campaign Workflow Testing#

TEST-INT-001: End-to-End Campaign Workflow Tests
- INT-001a: Complete campaign creation to execution flow (E2E)
- INT-001b: Multi-attack campaign with DAG sequencing (E2E)
- INT-001c: Campaign with resource upload and usage (E2E)
- INT-001d: Campaign monitoring through completion (E2E)
- INT-001e: Campaign results export and analysis (E2E + Mock)

Cross-Component Integration Testing#

TEST-INT-002: Cross-Component Integration Tests
- INT-002a: Resource creation and immediate use in attack (E2E)
- INT-002b: Agent registration and task assignment (E2E)
- INT-002c: User creation and project assignment workflow (E2E)
- INT-002d: Project switching with data context updates (E2E)
- INT-002e: Multi-user collaboration scenarios (E2E)

Error Recovery & Edge Case Testing#

TEST-INT-003: Error Recovery & Edge Case Tests
- INT-003a: Network failure recovery (Mock)
- INT-003b: Large file upload handling (E2E + Mock)
- INT-003c: Concurrent user modifications (E2E)
- INT-003d: Browser refresh during operations (Mock)
- INT-003e: Session expiry during long operations (E2E)

Error Page Testing#

TEST-INT-004: Error Page Tests
- INT-004a: Resource error page display and recovery options (Mock)
- INT-004b: Campaign error page with helpful guidance (Mock)
- INT-004c: Error page navigation and back functionality (Mock)
- INT-004d: Error state persistence and refresh behavior (Mock)
- INT-004e: Error reporting and feedback mechanisms (Mock)

Advanced UI/UX Features#

Data Display Components Enhancement#

UIX-DISPLAY-001: Advanced data display components
- Table sorting and pagination (consistent interaction models) (UIX-003a)
- Progress bar accuracy and animation (UIX-003b)
- Chart and metrics visualization (Catppuccin Macchiato theme) (UIX-003c)
- Empty state handling (UIX-003d)
- Error state display and recovery (UIX-003e)
- Progressive disclosure (complex features revealed progressively) (UIX-003f)
- Accessibility compliance (keyboard navigation, screen reader support) (UIX-003g)
- Responsive design with appropriate touch targets (UIX-003h)

Theme and Appearance Completion#

UIX-THEME-001: Complete theme system implementation
- Dark mode toggle functionality and persistence (UIX-004a)
- Theme switching without page refresh (UIX-004b)
- Theme preference persistence across sessions (UIX-004c)
- Catppuccin Macchiato theme consistency (UIX-004d)
- Theme-aware component rendering (UIX-004e)
- System theme detection and auto-switching (UIX-004f)

UI/UX Testing#

Data Display Component Testing#

TEST-UIX-003: Data Display Component Tests
- UIX-003a: Table sorting and pagination (Mock)
- UIX-003b: Progress bar accuracy and animation (Mock)
- UIX-003c: Chart and metrics visualization (Mock)
- UIX-003d: Empty state handling (Mock)
- UIX-003e: Error state display and recovery (Mock)
- UIX-003f: Progressive disclosure (Mock)
- UIX-003g: Accessibility compliance (Mock)
- UIX-003h: Responsive design with touch targets (Mock)

Theme and Appearance Testing#

TEST-UIX-004: Theme and Appearance Tests
- UIX-004a: Dark mode toggle functionality and persistence (E2E + Mock)
- UIX-004b: Theme switching without page refresh (Mock)
- UIX-004c: Theme preference persistence across sessions (E2E)
- UIX-004d: Catppuccin Macchiato theme consistency (Mock)
- UIX-004e: Theme-aware component rendering (Mock)
- UIX-004f: System theme detection and auto-switching (Mock)

Enhanced Security Testing#

Security Validations Enhancement#

SECURITY-001: Enhanced security validation implementation
- Sensitive resource access control (ACS-001e)
- CSRF protection on forms (ACS-002a)
- Input validation and sanitization (ACS-002b)
- File upload security checks (ACS-002c)
- API endpoint authorization (ACS-002d)
- Session security and timeout handling (ACS-002e)

Security Testing Implementation#

TEST-ACS-002: Security Validation Tests
- ACS-002a: CSRF protection on forms (E2E + Mock)
- ACS-002b: Input validation and sanitization (Mock)
- ACS-002c: File upload security checks (E2E + Mock)
- ACS-002d: API endpoint authorization (E2E)
- ACS-002e: Session security and timeout handling (E2E)

Validation & Success Criteria#

Agent Management Validation#

VALIDATE-001: Agent management is fully functional
- Agent registration workflow is complete and intuitive
- Agent details modal provides comprehensive information and controls
- Agent administration functions work properly for admins
- Real-time performance monitoring displays accurate data
- Agent status updates work correctly across all components

Integration Workflow Validation#

VALIDATE-002: Cross-component integration works seamlessly
- End-to-end campaign workflows complete successfully
- Resource integration with attacks functions properly
- Agent task assignment and monitoring works correctly
- Project switching maintains proper data context
- Multi-user scenarios handle permissions correctly

Error Handling Validation#

VALIDATE-003: Error handling and recovery work properly
- Network failures are handled gracefully with user feedback
- File upload errors provide clear recovery guidance
- Concurrent modifications are resolved appropriately
- Session expiry handling maintains user context
- Error pages provide helpful information and recovery options

UI/UX Validation#

VALIDATE-004: UI/UX enhancements are complete and accessible
- Data display components work consistently across the application
- Theme system functions properly with preference persistence
- Accessibility compliance is maintained throughout
- Responsive design works on all target device sizes
- Progressive disclosure enhances rather than complicates user experience

Security Validation#

VALIDATE-005: Security measures are comprehensive and effective
- All forms are protected against CSRF attacks
- Input validation prevents injection attacks
- File upload security prevents malicious file execution
- API endpoints properly validate authorization
- Session management maintains security while providing good UX

Implementation Notes#

Key Agent System References#

Component Architecture: Use idiomatic Shadcn-Svelte components for agent management interfaces with proper data tables, modals, and forms
SvelteKit Patterns: Follow idiomatic SvelteKit 5 patterns for agent data loading, real-time updates, and form submissions
Agent Display Logic: display_name = agent.custom_label or agent.host_name fallback pattern
Hardware Storage: Devices as Agent.devices list (descriptive names), enabled as backend_device comma-separated integers
Data Sources: DeviceStatus, TaskStatus, HashcatGuess from contracts/v1_api_swagger.json for real-time metrics
Benchmark Model: HashcatBenchmark with hash_type_id, runtime, hash_speed, device fields
Agent Lifecycle: pending → active → stopped → error states with proper transition handling
Integration Testing: Complete workflows from campaign creation → agent assignment → task execution → results

Agent Management Context#

Complete agent management addresses the identified gap in agent administrative capabilities:

Registration workflow provides streamlined agent onboarding
Details modal gives administrators comprehensive control and visibility
Performance monitoring enables effective resource management
Administrative functions support full agent lifecycle management

Integration Testing Strategy#

Cross-component integration testing ensures the system works as a cohesive whole:

End-to-end workflows validate complete user journeys
Error recovery testing ensures robust operation under adverse conditions
Multi-user scenarios validate permission and security systems
Resource integration validates data consistency across components

UI/UX Enhancement Focus#

UI/UX enhancements focus on consistency and accessibility:

Data display components provide consistent interaction patterns
Theme system enables user preference customization
Accessibility compliance ensures the system works for all users
Progressive disclosure manages complexity without overwhelming users

Security Implementation Strategy#

Enhanced security testing validates protection against common threats:

CSRF protection prevents cross-site request forgery
Input validation prevents injection attacks
File upload security prevents malicious file execution
Authorization validation ensures proper access control

Completion Definition#

This step is complete when:

Agent management provides complete registration, monitoring, and administration capabilities
Cross-component integration works seamlessly across all major workflows
Error handling and recovery work properly under all tested conditions
UI/UX enhancements provide consistent, accessible, and responsive interfaces
Security measures comprehensively protect against identified threats
All integration and workflow tests pass in both Mock and E2E environments
Performance is acceptable for all complex workflows and administrative functions