mirror of
https://github.com/proffesor-for-testing/agentic-qe.git
synced 2026-09-19 08:45:47 +08:00
Profa
7363bb1278
## @ruvector/edge Integration - Phases 0-3 Complete ### Phase 0: Browser Runtime - WASM shims and browser compatibility - BrowserAgent, BrowserHNSWAdapter, IndexedDBStorage - Chrome DevTools panel ### Phase 1: VS Code Extension MVP - Full extension with real-time analysis - Inline test suggestions, coverage visualization - Offline-first storage with sync ### Phase 2: P2P Foundation - Ed25519 crypto, WebRTC connections - SignalingServer, AgentSpawnAPI, EdgeServer - Pattern sharing via data channels - CRDT conflict resolution ### Phase 3: Web Dashboard - React dashboard with dark theme - P2P connection management UI - QE Agent Launcher from browser - React hooks (useP2P, usePatternSync, etc.) ### Documentation - Edge Server Guide - P2P Pattern Sharing Guide - Updated CLI agent-commands ### Also includes - Dead code cleanup (~22k lines) - 143 new P2P integration tests - Version updates across all files 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
513 lines
12 KiB
Markdown
513 lines
12 KiB
Markdown
# Agent CLI Commands Reference
|
|
|
|
Complete reference for all 10+ agent management CLI commands in the AQE Fleet system.
|
|
|
|
## Overview
|
|
|
|
The AQE Fleet provides comprehensive agent management through CLI commands organized into four categories:
|
|
|
|
1. **Lifecycle Commands** - Spawn, kill, restart agents
|
|
2. **Monitoring Commands** - List, metrics, logs, inspect
|
|
3. **Task Commands** - Assign tasks to agents
|
|
4. **Interactive Commands** - Attach/detach console sessions
|
|
|
|
---
|
|
|
|
## Lifecycle Commands
|
|
|
|
### `agent spawn`
|
|
|
|
Spawn a new QE agent with the specified type and task.
|
|
|
|
**Usage:**
|
|
```bash
|
|
aqe agent spawn <agentType> --task "<task description>" [options]
|
|
```
|
|
|
|
**Agent Types:**
|
|
| Type | Description |
|
|
|------|-------------|
|
|
| `test-generator` | AI-powered test generation |
|
|
| `coverage-analyzer` | Coverage gap detection (O(log n)) |
|
|
| `quality-gate` | Quality gate decisions |
|
|
| `performance-tester` | Performance and load testing |
|
|
| `security-scanner` | Security vulnerability detection |
|
|
| `flaky-test-hunter` | Flaky test detection and fixes |
|
|
| `chaos-engineer` | Chaos engineering experiments |
|
|
| `visual-tester` | Visual regression testing |
|
|
| `code-reviewer` | Code quality review |
|
|
| `integration-tester` | Integration test execution |
|
|
|
|
**Options:**
|
|
- `--task <description>` - Task for the agent to execute (required)
|
|
- `--model <model>` - Model to use: claude-sonnet, claude-opus (default: claude-sonnet)
|
|
- `--max-tokens <n>` - Maximum tokens (default: 8192)
|
|
- `--wait` - Wait for completion and show output
|
|
- `--json` - Output in JSON format
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Generate tests for a service
|
|
aqe agent spawn test-generator --task "Create unit tests for UserService"
|
|
|
|
# Analyze coverage gaps
|
|
aqe agent spawn coverage-analyzer --task "Find untested code paths in auth module"
|
|
|
|
# Security scan with opus model
|
|
aqe agent spawn security-scanner --task "Audit API endpoints" --model claude-opus
|
|
|
|
# Wait for completion
|
|
aqe agent spawn test-generator --task "Generate tests" --wait
|
|
```
|
|
|
|
**Output:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"agentId": "agent-550e8400-e29b-41d4-a716-446655440000",
|
|
"agentType": "test-generator",
|
|
"status": "running",
|
|
"startedAt": "2025-01-03T10:30:00.000Z"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Alternative: Edge Server REST API
|
|
|
|
For external integrations, CI/CD pipelines, or web applications, you can spawn agents via the Edge Server REST API instead of CLI.
|
|
|
|
**Start Edge Server:**
|
|
```bash
|
|
# Start combined HTTP + WebSocket server
|
|
node dist/edge/server/index.js
|
|
|
|
# Or with custom ports
|
|
HTTP_PORT=3001 WS_PORT=3002 node dist/edge/server/index.js
|
|
```
|
|
|
|
**REST API Endpoints:**
|
|
|
|
| Endpoint | Method | Description |
|
|
|----------|--------|-------------|
|
|
| `POST /api/agents/spawn` | POST | Spawn new agent |
|
|
| `GET /api/agents` | GET | List all agents |
|
|
| `GET /api/agents/:id` | GET | Get agent status |
|
|
| `GET /api/agents/:id/output` | GET | Get agent output |
|
|
| `DELETE /api/agents/:id` | DELETE | Cancel agent |
|
|
| `GET /api/agents/types` | GET | List available types |
|
|
| `GET /api/health` | GET | Health check |
|
|
|
|
**Spawn Agent via REST:**
|
|
```bash
|
|
curl -X POST http://localhost:3001/api/agents/spawn \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"agentType": "test-generator",
|
|
"task": "Create unit tests for UserService",
|
|
"model": "claude-sonnet-4-20250514"
|
|
}'
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"agentId": "agent-550e8400-e29b-41d4-a716-446655440000",
|
|
"status": "running"
|
|
}
|
|
```
|
|
|
|
**When to Use:**
|
|
- **CLI (`aqe agent spawn`)**: Direct terminal usage, scripting
|
|
- **REST API**: CI/CD integration, web apps, external tools
|
|
|
|
---
|
|
|
|
### `agent restart`
|
|
|
|
Gracefully restart an agent while preserving configuration and state.
|
|
|
|
**Usage:**
|
|
```bash
|
|
aqe agent restart <agentId> [options]
|
|
```
|
|
|
|
**Options:**
|
|
- `--preserve-state` - Save and restore agent state (default: true)
|
|
- `--timeout <ms>` - Termination timeout in milliseconds (default: 30000)
|
|
- `--force` - Force restart without graceful shutdown
|
|
- `--no-state` - Skip state preservation
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Graceful restart with state preservation
|
|
aqe agent restart agent-1 --preserve-state
|
|
|
|
# Force restart
|
|
aqe agent restart agent-1 --force
|
|
|
|
# Custom timeout
|
|
aqe agent restart agent-1 --timeout 60000
|
|
```
|
|
|
|
**Output:**
|
|
```json
|
|
{
|
|
"agentId": "agent-1",
|
|
"oldInstanceId": "test-generator-1-...",
|
|
"newInstanceId": "test-generator-2-...",
|
|
"status": "active",
|
|
"restartTime": 1534,
|
|
"stateRestored": true
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Monitoring Commands
|
|
|
|
### `agent inspect`
|
|
|
|
Display detailed agent information including configuration, metrics, history, and health status.
|
|
|
|
**Usage:**
|
|
```bash
|
|
aqe agent inspect <agentId> [options]
|
|
```
|
|
|
|
**Options:**
|
|
- `--history` - Include task execution history
|
|
- `--metrics` - Include performance metrics (default: true)
|
|
- `--logs` - Include recent log entries
|
|
- `--format <type>` - Output format: json, yaml, table, detailed (default: json)
|
|
- `--depth <level>` - Inspection depth: shallow, deep (default: deep)
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Basic inspection
|
|
aqe agent inspect agent-1
|
|
|
|
# Full inspection with history and logs
|
|
aqe agent inspect agent-1 --history --logs
|
|
|
|
# Table format for terminal viewing
|
|
aqe agent inspect agent-1 --format table
|
|
|
|
# YAML output
|
|
aqe agent inspect agent-1 --format yaml
|
|
```
|
|
|
|
**Output:**
|
|
```json
|
|
{
|
|
"id": "test-generator-1-...",
|
|
"type": "TEST_GENERATOR",
|
|
"mcpType": "test-generator",
|
|
"status": "active",
|
|
"configuration": {
|
|
"name": "agent-1",
|
|
"capabilities": ["property-testing", "mutation-testing"],
|
|
"resources": {
|
|
"cpu": "1",
|
|
"memory": "512MB"
|
|
}
|
|
},
|
|
"lifecycle": {
|
|
"spawnedAt": "2025-10-06T13:30:00.000Z",
|
|
"lastActivity": "2025-10-06T13:37:00.000Z",
|
|
"uptime": 420000,
|
|
"restartCount": 2
|
|
},
|
|
"metrics": {
|
|
"tasksCompleted": 47,
|
|
"tasksActive": 1,
|
|
"tasksFailed": 3,
|
|
"averageExecutionTime": 1523,
|
|
"successRate": 0.936
|
|
},
|
|
"health": {
|
|
"status": "healthy",
|
|
"issues": [],
|
|
"lastCheck": "2025-10-06T13:37:10.000Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Task Commands
|
|
|
|
### `agent assign`
|
|
|
|
Assign tasks to agents with intelligent load balancing and capability matching.
|
|
|
|
**Usage:**
|
|
```bash
|
|
aqe agent assign <taskId> [options]
|
|
```
|
|
|
|
**Options:**
|
|
- `--agent <agentId>` - Manually assign to specific agent
|
|
- `--auto-balance` - Use load balancing algorithm
|
|
- `--require-capability <name>` - Require specific capability
|
|
- `--priority <level>` - Task priority: low, medium, high, critical (default: medium)
|
|
- `--timeout <ms>` - Task timeout in milliseconds (default: 300000)
|
|
- `--retry` - Retry on failure (default: true)
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Manual assignment
|
|
aqe agent assign task-123 --agent agent-1
|
|
|
|
# Auto-assignment with load balancing
|
|
aqe agent assign task-123 --auto-balance
|
|
|
|
# Require specific capability
|
|
aqe agent assign task-123 --auto-balance --require-capability performance-testing
|
|
|
|
# High priority task
|
|
aqe agent assign task-123 --agent agent-1 --priority high
|
|
```
|
|
|
|
**Output:**
|
|
```json
|
|
{
|
|
"taskId": "task-123",
|
|
"agentId": "agent-1",
|
|
"agentType": "performance-tester",
|
|
"status": "assigned",
|
|
"assignedAt": "2025-10-06T13:37:15.000Z",
|
|
"estimatedCompletion": "2025-10-06T13:39:00.000Z",
|
|
"capabilities": ["load-testing", "stress-testing"]
|
|
}
|
|
```
|
|
|
|
**Queued Response:**
|
|
```json
|
|
{
|
|
"taskId": "task-124",
|
|
"agentId": "agent-1",
|
|
"agentType": "performance-tester",
|
|
"status": "queued",
|
|
"assignedAt": "2025-10-06T13:37:20.000Z",
|
|
"queuePosition": 2,
|
|
"capabilities": ["load-testing"]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Interactive Commands
|
|
|
|
### `agent attach`
|
|
|
|
Attach to an agent's console for real-time monitoring of logs, metrics, and events.
|
|
|
|
**Usage:**
|
|
```bash
|
|
aqe agent attach <agentId> [options]
|
|
```
|
|
|
|
**Options:**
|
|
- `--follow` - Follow log output in real-time (default: true)
|
|
- `--metrics` - Show metrics updates (default: true)
|
|
- `--logs` - Show log entries (default: true)
|
|
- `--events` - Show event notifications (default: true)
|
|
- `--refresh <ms>` - Metrics refresh rate in milliseconds (default: 1000)
|
|
- `--filter <pattern>` - Filter logs by pattern
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Attach with all monitoring
|
|
aqe agent attach agent-1
|
|
|
|
# Attach with only logs
|
|
aqe agent attach agent-1 --no-metrics --no-events
|
|
|
|
# Filter error logs
|
|
aqe agent attach agent-1 --filter ERROR
|
|
|
|
# Custom refresh rate
|
|
aqe agent attach agent-1 --refresh 500
|
|
```
|
|
|
|
**Output:**
|
|
```
|
|
============================================================
|
|
📎 Attached to Agent: test-generator-1-...
|
|
============================================================
|
|
Type: test-generator
|
|
Status: active
|
|
Tasks Completed: 47
|
|
Last Activity: 10/6/2025, 1:37:00 PM
|
|
============================================================
|
|
|
|
[LOG] Starting test generation for module: UserService
|
|
[METRIC] {"tasksCompleted":48,"averageExecutionTime":1498}
|
|
[EVENT] task_started: Generating unit tests
|
|
[LOG] Generated 15 test cases
|
|
[LOG] Running property-based testing...
|
|
[METRIC] {"tasksCompleted":48,"averageExecutionTime":1501}
|
|
[EVENT] task_completed: Test generation completed
|
|
```
|
|
|
|
**Detach:** Press `Ctrl+C` or use `aqe agent detach <agentId>`
|
|
|
|
---
|
|
|
|
### `agent detach`
|
|
|
|
Detach from an active agent console session with optional session archival.
|
|
|
|
**Usage:**
|
|
```bash
|
|
aqe agent detach <agentId> [options]
|
|
```
|
|
|
|
**Options:**
|
|
- `--save-session` - Archive session data (default: true)
|
|
- `--show-stats` - Display session statistics (default: true)
|
|
- `--force` - Force detach even if errors occur
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Normal detach with stats
|
|
aqe agent detach agent-1
|
|
|
|
# Force detach without saving
|
|
aqe agent detach agent-1 --force --no-save-session
|
|
```
|
|
|
|
**Output:**
|
|
```
|
|
============================================================
|
|
📊 Session Statistics
|
|
============================================================
|
|
Agent ID: agent-1
|
|
Session ID: attach-agent-1-1728223030000
|
|
Duration: 124.53s
|
|
Logs Received: 342
|
|
Events Received: 28
|
|
Metrics Received: 124
|
|
============================================================
|
|
```
|
|
|
|
---
|
|
|
|
## Advanced Usage
|
|
|
|
### Load Balancing Algorithm
|
|
|
|
The `agent assign --auto-balance` command uses a sophisticated scoring algorithm:
|
|
|
|
```typescript
|
|
score = 100
|
|
- (tasksCompleted * 0.1) // Penalize by load
|
|
- (status === 'busy' ? 50 : 0) // Penalize busy agents
|
|
- (status === 'error' ? 80 : 0) // Penalize error agents
|
|
+ (status === 'idle' ? 20 : 0) // Bonus for idle
|
|
+ max(0, 20 - (avgTime / 1000)) // Bonus for fast agents
|
|
```
|
|
|
|
### Health Checks
|
|
|
|
Agent health is automatically monitored:
|
|
|
|
- **Healthy**: Normal operation, no issues
|
|
- **Degraded**: Inactive for >1 hour, or no tasks completed after 10min
|
|
- **Unhealthy**: Agent in error state
|
|
|
|
### Session Management
|
|
|
|
Attach sessions are automatically managed:
|
|
|
|
- Session metadata stored in `.aqe/sessions/`
|
|
- Completed sessions archived in `.aqe/sessions/archive/`
|
|
- Auto-cleanup of sessions older than 30 days
|
|
|
|
---
|
|
|
|
## Integration with AgentRegistry
|
|
|
|
All commands integrate with the centralized `AgentRegistry` service:
|
|
|
|
```typescript
|
|
import { getAgentRegistry } from '@/mcp/services/AgentRegistry';
|
|
|
|
const registry = getAgentRegistry();
|
|
const agent = registry.getRegisteredAgent(agentId);
|
|
```
|
|
|
|
---
|
|
|
|
## Error Handling
|
|
|
|
### Common Errors
|
|
|
|
**Agent Not Found:**
|
|
```
|
|
Error: Agent not found: agent-xyz
|
|
```
|
|
**Solution:** Check agent ID with `aqe agent list`
|
|
|
|
**Agent Lacks Capability:**
|
|
```
|
|
Error: Agent lacks required capability: performance-testing
|
|
```
|
|
**Solution:** Use `aqe agent inspect <agentId>` to check capabilities
|
|
|
|
**Not Attached:**
|
|
```
|
|
Error: Not attached to agent: agent-1
|
|
```
|
|
**Solution:** Use `aqe agent attach agent-1` first
|
|
|
|
---
|
|
|
|
## File Locations
|
|
|
|
- Agent configs: `.aqe/agents/<agentId>.json`
|
|
- Agent state: `.aqe/state/<agentId>.state.json`
|
|
- Agent logs: `.aqe/logs/<agentId>.log`
|
|
- Task queue: `.aqe/queue/<agentId>.json`
|
|
- Attach sessions: `.aqe/sessions/<sessionId>.json`
|
|
- Session archive: `.aqe/sessions/archive/<sessionId>.json`
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
All commands have comprehensive test coverage:
|
|
|
|
```bash
|
|
npm test -- tests/cli/agent.test.ts
|
|
```
|
|
|
|
**Test Suites:**
|
|
- ✅ agent restart (6 tests)
|
|
- ✅ agent inspect (7 tests)
|
|
- ✅ agent assign (7 tests)
|
|
- ✅ agent attach (6 tests)
|
|
- ✅ agent detach (7 tests)
|
|
|
|
**Total:** 33 tests covering all command functionality
|
|
|
|
---
|
|
|
|
## Related Commands
|
|
|
|
- `aqe fleet init` - Initialize AQE fleet
|
|
- `aqe fleet status` - Show fleet overview
|
|
- `aqe agent spawn` - Create new agent
|
|
- `aqe agent list` - List all agents
|
|
- `aqe agent metrics` - Show agent metrics
|
|
|
|
---
|
|
|
|
## Support
|
|
|
|
For issues or questions:
|
|
- GitHub: https://github.com/ruvnet/agentic-qe
|
|
- Documentation: `/docs`
|