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
  • Table of Contents
  • Overview
  • Complete Agent Management Implementation
  • Cross-Component Integration Implementation
  • Agent Management Testing
  • Integration & Workflow Testing
  • Advanced UI/UX Features
  • UI/UX Testing
  • Enhanced Security Testing
  • Validation & Success Criteria
  • Implementation Notes
  • Completion Definition

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

Complete Agent Details Modal Implementation#

🔧 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-DETAIL-001: Agent Settings Tab

  • Essential controls: enable/disable toggle, update interval, native hashcat option (AGT-003a)
    • Settings Form: Editable agent label, enabled toggle, update interval, native hashcat toggle
    • Project Assignment: Multi-toggle list for project permissions
    • System Info: Read-only display of OS, IP, client signature, agent token
    • Form Validation: Real-time validation with clear error messaging
  • Benchmark control: toggle for additional hash types (--benchmark-all)
  • Project assignment: multi-toggle interface for project membership
  • System information: read-only OS, IP, signature, and token display

• AGENT-DETAIL-002: Agent Hardware Tab

  • Device management: individual toggles for each backend device from --backend-info (AGT-003b)
    • Device List: Toggle switches for each computational device (GPU, CPU)
    • Hardware Info: Device names from --backend-info with enable/disable controls
    • Task Warning: Modal prompt when changing devices during active tasks
    • Backend Settings: Toggle controls for CUDA, OpenCL, HIP, Metal backends
  • State-aware prompting: apply now/next task/cancel options when tasks are running
  • Graceful degradation: gray placeholders when device info not yet available (AGT-003f)
    • Loading States: Show placeholders until hardware info is available
    • Error States: Clear messaging when hardware detection fails
    • Fallback UI: Graceful degradation when device info unavailable
  • Hardware limits: temperature abort thresholds and OpenCL device type selection
  • Backend toggles: CUDA, HIP, Metal, OpenCL backend management

• AGENT-DETAIL-003: Agent Performance Tab

  • Time series visualization: line charts of guess rates over 8-hour windows (AGT-003c)
    • Time Series Charts: 8-hour line charts showing guess rate trends per device
    • Device Cards: Individual cards with donut charts for utilization percentages
    • Live Metrics: Real-time guess rate updates via SSE
    • Performance Context: Historical trends and comparative analysis displays
  • Device-specific metrics: individual donut charts showing utilization percentages
  • Live updates: real-time data via Server-Sent Events
  • Historical context: performance trends and comparative analysis

• AGENT-DETAIL-004: Agent Logs Tab

  • Timeline interface: chronological AgentError entries with color-coded severity (AGT-003d)
    • Timeline UI: Chronological AgentError entries with color-coded severity levels
    • Rich Context: Display message, error code, task links, expandable details
    • Filtering: Search and filter by severity, time range, task association
    • Error Details: Expandable JSON details for debugging information
  • Rich context: message, code, task links, and expandable details
  • Filtering capabilities: search and filter by severity, time range, task association

• AGENT-DETAIL-005: Agent Capabilities Tab

  • Comprehensive benchmarks: table view with toggle/hash ID/name/speed/category (AGT-003e)
    • Benchmark Table: Toggle, Hash ID, Name, Speed, Category columns
    • Expandable Rows: Per-device breakdowns for multi-GPU systems
    • Search/Filter: Quick access to specific hash types and performance data
    • Category Grouping: Organize benchmarks by hash type categories
  • Expandable details: per-device breakdowns for multi-GPU systems
  • Search and filter: quick access to specific hash types and performance data
  • Benchmark management: header button to trigger new benchmark runs (AGT-003g)
    • Rebenchmark Button: Header button to trigger new benchmark runs
    • Progress Feedback: Visual indication during benchmark execution
    • Results Update: Live update of benchmark table when completed
    • Benchmark History: Display last benchmark date and comparison data

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#

• WORKFLOW-001: Complete campaign creation to execution flow

  • Complete campaign creation to execution flow (INT-001a)
  • Campaign with resource upload and usage (INT-001c)
  • Campaign monitoring through completion (INT-001d)
  • Campaign results export and analysis (INT-001e)

• WORKFLOW-002: Multi-attack campaign with DAG sequencing

  • Multi-attack campaign with DAG sequencing (INT-001b)
  • Attack dependency management and validation
  • Sequential and parallel attack execution patterns
  • Progress tracking across complex attack sequences

Cross-Component Integration Workflows#

• INTEGRATION-001: Resource and attack integration

  • Resource creation and immediate use in attack (INT-002a)
  • Resource dropdown population in attack editor
  • Resource validation and dependency checking
  • Resource usage tracking across attacks

• INTEGRATION-002: Agent and task integration

  • Agent registration and task assignment (INT-002b)
  • Agent capability matching with attack requirements
  • Task distribution and monitoring workflows
  • Agent performance impact on task allocation

• INTEGRATION-003: User and project workflow integration

  • User creation and project assignment workflow (INT-002c)
  • Project switching with data context updates (INT-002d)
  • Multi-user collaboration scenarios (INT-002e)
  • Permission inheritance and validation across workflows

Error Recovery & Edge Cases#

• ERROR-RECOVERY-001: Network and connection error handling

  • Network failure recovery (INT-003a)
  • Connection timeout handling
  • Automatic retry mechanisms
  • Graceful degradation patterns

• ERROR-RECOVERY-002: File and data handling edge cases

  • Large file upload handling (INT-003b)
  • Upload interruption and resume
  • Data corruption detection and recovery
  • Storage quota and limit handling

• ERROR-RECOVERY-003: User interaction edge cases

  • Concurrent user modifications (INT-003c)
  • Browser refresh during operations (INT-003d)
  • Session expiry during long operations (INT-003e)
  • Navigation interruption handling

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)

Agent Details Modal Testing#

• 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:

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