claude-flow
Version:
Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration
1,086 lines (840 loc) • 21.1 kB
text/typescript
/**
* Agentic-QE Plugin Interfaces
*
* Public interfaces for the Quality Engineering plugin's anti-corruption layer.
* These interfaces define contracts between agentic-qe and Claude Flow V3 domains.
*
* Based on ADR-030: Agentic-QE Plugin Integration
*
* @module v3/plugins/agentic-qe/interfaces
*/
// =============================================================================
// Memory Bridge Interfaces
// =============================================================================
/**
* Test pattern learned from successful test generation
*/
export interface TestPattern {
/** Unique identifier */
id: string;
/** Type of test (unit, integration, e2e, etc.) */
type: TestPatternType;
/** Programming language */
language: string;
/** Test framework (vitest, jest, pytest, etc.) */
framework: string;
/** Natural language description */
description: string;
/** The pattern's code template or structure */
code: string;
/** Tags for categorization */
tags: string[];
/** Effectiveness score from usage (0-1) */
effectiveness: number;
/** Number of times this pattern has been used */
usageCount: number;
/** Creation timestamp */
createdAt: number;
/** Last used timestamp */
lastUsedAt: number;
/** Additional metadata */
metadata: Record<string, unknown>;
}
export type TestPatternType =
| 'unit'
| 'integration'
| 'e2e'
| 'property'
| 'mutation'
| 'fuzz'
| 'api'
| 'performance'
| 'security'
| 'accessibility'
| 'contract'
| 'bdd';
/**
* Filters for pattern search
*/
export interface PatternFilters {
type?: TestPatternType;
language?: string;
framework?: string;
tags?: string[];
minEffectiveness?: number;
}
/**
* Coverage gap detected during analysis
*/
export interface CoverageGap {
/** Unique identifier */
id: string;
/** File path with gap */
file: string;
/** Type of gap (line, branch, function) */
type: 'line' | 'branch' | 'function' | 'statement';
/** Location information */
location: {
startLine: number;
endLine: number;
startColumn?: number;
endColumn?: number;
};
/** Risk score (0-1, higher = more risky) */
riskScore: number;
/** Priority ranking */
priority: 'critical' | 'high' | 'medium' | 'low';
/** Reason for the gap */
reason: string;
/** Suggested test approach */
suggestion: string;
/** Detection timestamp */
detectedAt: number;
}
/**
* Learning trajectory for ReasoningBank integration
*/
export interface LearningTrajectory {
/** Unique identifier */
id: string;
/** Type of task that generated this trajectory */
taskType: string;
/** Agent that performed the task */
agentId: string;
/** Whether the task succeeded */
success: boolean;
/** Reward signal for reinforcement learning */
reward: number;
/** Sequence of steps taken */
steps: LearningStep[];
/** Final verdict */
verdict: 'success' | 'failure' | 'partial';
/** Creation timestamp */
createdAt: number;
/** Duration in milliseconds */
durationMs: number;
/** Additional context */
context: Record<string, unknown>;
}
/**
* Single step in a learning trajectory
*/
export interface LearningStep {
/** Step index */
index: number;
/** Action taken */
action: string;
/** Input to the action */
input: Record<string, unknown>;
/** Output from the action */
output: Record<string, unknown>;
/** Quality score for this step */
quality: number;
/** Timestamp */
timestamp: number;
}
/**
* Memory bridge interface for V3 memory integration
*/
export interface IQEMemoryBridge {
/**
* Initialize memory namespaces
*/
initialize(): Promise<void>;
/**
* Store a test pattern with semantic embedding
*/
storeTestPattern(pattern: TestPattern): Promise<string>;
/**
* Search for similar patterns using HNSW (150x faster)
*/
searchSimilarPatterns(
query: string,
k?: number,
filters?: PatternFilters
): Promise<TestPattern[]>;
/**
* Store a coverage gap
*/
storeCoverageGap(gap: CoverageGap): Promise<string>;
/**
* Get coverage gaps for a file
*/
getCoverageGaps(file: string): Promise<CoverageGap[]>;
/**
* Get prioritized coverage gaps
*/
getPrioritizedGaps(limit?: number): Promise<CoverageGap[]>;
/**
* Store a learning trajectory for ReasoningBank
*/
storeTrajectory(trajectory: LearningTrajectory): Promise<string>;
/**
* Search trajectories by similarity
*/
searchTrajectories(
query: string,
k?: number,
filters?: { taskType?: string; success?: boolean }
): Promise<LearningTrajectory[]>;
/**
* Clear temporary data (e.g., coverage data)
*/
clearTemporaryData(): Promise<void>;
/**
* Get memory statistics
*/
getStats(): Promise<QEMemoryStats>;
}
/**
* Memory statistics for QE namespaces
*/
export interface QEMemoryStats {
testPatterns: number;
coverageGaps: number;
learningTrajectories: number;
codeKnowledge: number;
securityFindings: number;
totalMemoryBytes: number;
}
// =============================================================================
// Security Bridge Interfaces
// =============================================================================
/**
* Validated path result
*/
export interface ValidatedPath {
path: string;
valid: boolean;
error?: string;
resolvedPath?: string;
}
/**
* DAST probe definition
*/
export interface DASTProbe {
/** Probe identifier */
id: string;
/** Probe type */
type: 'xss' | 'sqli' | 'ssrf' | 'csrf' | 'auth' | 'header' | 'custom';
/** Target endpoint */
endpoint: string;
/** HTTP method */
method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
/** Request payload */
payload?: Record<string, unknown>;
/** Expected response indicators */
indicators: string[];
/** Maximum timeout */
timeout: number;
}
/**
* DAST scan result
*/
export interface DASTResult {
/** Probe identifier */
probeId: string;
/** Whether vulnerability was detected */
vulnerable: boolean;
/** Severity if vulnerable */
severity?: 'critical' | 'high' | 'medium' | 'low' | 'info';
/** Response status code */
statusCode: number;
/** Evidence of vulnerability */
evidence?: string;
/** Execution time */
executionTimeMs: number;
}
/**
* Audit event for compliance tracking
*/
export interface AuditEvent {
/** Event type */
type: 'scan_started' | 'scan_completed' | 'finding_detected' | 'remediation_applied';
/** Actor who triggered the event */
actor: string;
/** Target of the action */
target: string;
/** Event details */
details: Record<string, unknown>;
/** Timestamp */
timestamp: number;
}
/**
* Signed audit entry
*/
export interface SignedAuditEntry {
/** Unique identifier */
id: string;
/** The audit event */
event: AuditEvent;
/** Entry timestamp */
timestamp: number;
/** Actor who created the entry */
actor: string;
/** Cryptographic signature */
signature: string;
/** Whether signature is verifiable */
verifiable: boolean;
}
/**
* PII type classification
*/
export type PIIType =
| 'email'
| 'phone'
| 'ssn'
| 'credit_card'
| 'api_key'
| 'password'
| 'address'
| 'name'
| 'dob'
| 'ip_address';
/**
* PII detection result
*/
export interface PIIDetection {
/** Type of PII detected */
type: PIIType;
/** Location in the content */
location: {
start: number;
end: number;
};
/** Confidence score (0-1) */
confidence: number;
/** The detected value (redacted) */
redactedValue?: string;
}
/**
* Security bridge interface for V3 security integration
*/
export interface IQESecurityBridge {
/**
* Validate a file path before security scan
*/
validateScanTarget(path: string): Promise<ValidatedPath>;
/**
* Execute DAST probes with security constraints
*/
executeDAST(target: string, probes: DASTProbe[]): Promise<DASTResult[]>;
/**
* Create a signed audit entry
*/
createAuditEntry(event: AuditEvent): Promise<SignedAuditEntry>;
/**
* Detect PII in content
*/
detectPII(content: string): Promise<PIIDetection[]>;
/**
* Validate input against security schemas
*/
validateInput<T>(input: unknown, schema: string): Promise<{ valid: boolean; errors?: string[]; value?: T }>;
/**
* Sanitize error message for safe display
*/
sanitizeError(error: Error): Error;
/**
* Get security policy for a context
*/
getSecurityPolicy(context: string): SecurityPolicy;
}
/**
* Security policy configuration
*/
export interface SecurityPolicy {
/** Security level */
level: 'low' | 'medium' | 'high' | 'critical';
/** Network access policy */
networkPolicy: 'unrestricted' | 'restricted' | 'blocked';
/** File system policy */
fileSystemPolicy: 'full' | 'workspace-only' | 'readonly' | 'none';
/** Allowed commands */
allowedCommands: string[];
/** Blocked paths */
blockedPaths: string[];
/** Maximum execution time */
maxExecutionTime: number;
/** Maximum memory */
maxMemory: number;
}
// =============================================================================
// Core Bridge Interfaces
// =============================================================================
/**
* Test suite definition
*/
export interface TestSuite {
/** Unique identifier */
id: string;
/** Suite name */
name: string;
/** Test framework */
framework: string;
/** Individual test cases */
testCases: TestCase[];
/** Estimated duration in ms */
estimatedDuration: number;
/** Configuration */
config: TestSuiteConfig;
}
/**
* Test case definition
*/
export interface TestCase {
/** Test identifier */
id: string;
/** Test name */
name: string;
/** Test file path */
filePath: string;
/** Test function or describe block */
testBlock: string;
/** Tags */
tags: string[];
/** Estimated duration */
estimatedDuration: number;
}
/**
* Test suite configuration
*/
export interface TestSuiteConfig {
/** Run tests in parallel */
parallel: boolean;
/** Maximum parallel workers */
maxWorkers: number;
/** Retry count for flaky tests */
retryCount: number;
/** Timeout per test */
testTimeout: number;
/** Coverage collection */
collectCoverage: boolean;
/** Watch mode */
watch: boolean;
}
/**
* Executor configuration
*/
export interface ExecutorConfig {
/** Enable parallel execution */
parallel: boolean;
/** Maximum workers */
maxWorkers: number;
/** Retry count */
retryCount: number;
/** Timeout in ms */
timeout: number;
/** Environment variables */
env?: Record<string, string>;
}
/**
* Agent handle for managing spawned agents
*/
export interface AgentHandle {
/** Agent identifier */
id: string;
/** Agent type */
type: string;
/** Agent name */
name: string;
/** Current status */
status: 'spawning' | 'ready' | 'busy' | 'error' | 'terminated';
/** Terminate the agent */
terminate(): Promise<void>;
/** Send a message to the agent */
send(message: Record<string, unknown>): Promise<void>;
}
/**
* Task handle for managing created tasks
*/
export interface TaskHandle {
/** Task identifier */
id: string;
/** Task type */
type: string;
/** Current status */
status: 'pending' | 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
/** Wait for task completion */
wait(): Promise<TaskResult>;
/** Cancel the task */
cancel(): Promise<void>;
/** Get task progress */
getProgress(): Promise<TaskProgress>;
}
/**
* Task result
*/
export interface TaskResult {
/** Task identifier */
taskId: string;
/** Whether task succeeded */
success: boolean;
/** Result data */
data?: Record<string, unknown>;
/** Error if failed */
error?: string;
/** Duration in ms */
durationMs: number;
}
/**
* Task progress
*/
export interface TaskProgress {
/** Completion percentage (0-100) */
percentage: number;
/** Current step */
currentStep: string;
/** Total steps */
totalSteps: number;
/** Completed steps */
completedSteps: number;
/** Estimated remaining time in ms */
estimatedRemainingMs: number;
}
/**
* Quality gate definition
*/
export interface QualityGate {
/** Gate identifier */
id: string;
/** Gate name */
name: string;
/** Evaluation criteria */
criteria: QualityGateCriteria;
/** Required for release */
required: boolean;
/** Gate weight in overall score */
weight: number;
}
/**
* Quality gate criteria
*/
export interface QualityGateCriteria {
/** Metric to evaluate */
metric: string;
/** Comparison operator */
operator: '>' | '<' | '>=' | '<=' | '==' | '!=';
/** Threshold value */
threshold: number;
}
/**
* Quality metrics
*/
export interface QualityMetrics {
/** Code coverage percentage */
coveragePercent: number;
/** Number of passing tests */
testsPassed: number;
/** Number of failing tests */
testsFailed: number;
/** Number of skipped tests */
testsSkipped: number;
/** Number of security issues */
securityIssues: number;
/** Code complexity score */
complexityScore: number;
/** Technical debt minutes */
technicalDebtMinutes: number;
/** Custom metrics */
custom: Record<string, number>;
}
/**
* Workflow result
*/
export interface WorkflowResult {
/** Workflow identifier */
workflowId: string;
/** Whether workflow succeeded */
success: boolean;
/** Step results */
stepResults: StepResult[];
/** Overall duration */
durationMs: number;
/** Final output */
output?: Record<string, unknown>;
}
/**
* Step result
*/
export interface StepResult {
/** Step name */
name: string;
/** Whether step passed */
passed: boolean;
/** Step output */
output?: Record<string, unknown>;
/** Error if failed */
error?: string;
/** Duration */
durationMs: number;
}
/**
* Task priority
*/
export type Priority = 'critical' | 'high' | 'normal' | 'low';
/**
* Core bridge interface for V3 core services
*/
export interface IQECoreBridge {
/**
* Spawn a test execution agent
*/
spawnTestExecutor(testSuite: TestSuite, config: ExecutorConfig): Promise<AgentHandle>;
/**
* Create a test execution task
*/
createTestTask(testSuite: TestSuite, priority: Priority): Promise<TaskHandle>;
/**
* Execute a quality gate workflow
*/
executeQualityGateWorkflow(gates: QualityGate[], metrics: QualityMetrics): Promise<WorkflowResult>;
/**
* Get configuration value
*/
getConfig<T>(key: string): Promise<T | undefined>;
/**
* List available agents by type
*/
listAgents(filter?: { type?: string; status?: string }): Promise<AgentHandle[]>;
/**
* Get agent by ID
*/
getAgent(agentId: string): Promise<AgentHandle | null>;
}
// =============================================================================
// Hive Bridge Interfaces
// =============================================================================
/**
* Hive Mind role
*/
export type HiveRole = 'queen' | 'worker' | 'specialist' | 'scout';
/**
* QE swarm task
*/
export interface QESwarmTask {
/** Task identifier */
id: string;
/** Required agent types */
agents: string[];
/** Task priority */
priority: 'low' | 'normal' | 'high' | 'critical';
/** Task payload */
payload: Record<string, unknown>;
/** Task type */
type: string;
/** Timeout in ms */
timeout: number;
}
/**
* QE swarm result
*/
export interface QESwarmResult {
/** Task identifier */
taskId: string;
/** Results from each agent */
agentResults: AgentTaskResult[];
/** Number of completed agents */
completedAgents: number;
/** Total agents assigned */
totalAgents: number;
/** Overall success */
success: boolean;
/** Aggregated output */
aggregatedOutput?: Record<string, unknown>;
}
/**
* Individual agent task result
*/
export interface AgentTaskResult {
/** Agent identifier */
agentId: string;
/** Whether agent succeeded */
success: boolean;
/** Agent output */
output: Record<string, unknown>;
/** Error if failed */
error?: string;
/** Duration */
durationMs: number;
}
/**
* Consensus result
*/
export interface ConsensusResult {
/** Whether consensus was reached */
accepted: boolean;
/** Reason if rejected */
reason?: string;
/** Votes for */
votesFor: number;
/** Votes against */
votesAgainst: number;
/** Total voters */
totalVoters: number;
}
/**
* Hive bridge interface for V3 Hive Mind coordination
*/
export interface IQEHiveBridge {
/**
* Register QE Queen with Hive Mind
*/
registerQueen(): Promise<void>;
/**
* Spawn a QE worker and join to hive
*/
spawnQEWorker(agentType: string, context: string): Promise<string>;
/**
* Coordinate a QE swarm task
*/
coordinateQESwarm(task: QESwarmTask): Promise<QESwarmResult>;
/**
* Execute operation with Byzantine fault tolerance
*/
executeWithBFT<T>(operation: () => Promise<T>, replicaCount?: number): Promise<T>;
/**
* Propose task allocation via consensus
*/
proposeTaskAllocation(task: QESwarmTask, requiredAgents: string[]): Promise<ConsensusResult>;
/**
* Broadcast result to hive
*/
broadcastResult(taskId: string, result: QESwarmResult): Promise<void>;
/**
* Store QE state in hive memory
*/
storeQEState(key: string, value: unknown): Promise<void>;
/**
* Retrieve QE state from hive memory
*/
getQEState<T>(key: string): Promise<T | null>;
/**
* Get queen identifier
*/
getQueenId(): string;
/**
* Leave the hive (cleanup)
*/
leave(): Promise<void>;
}
// =============================================================================
// Model Routing Adapter Interfaces
// =============================================================================
/**
* QE task for model routing
*/
export interface QETask {
/** Task category */
category: string;
/** Task description */
description: string;
/** Target file path (optional) */
targetPath?: string;
/** Additional context */
context?: Record<string, unknown>;
}
/**
* Model tier
*/
export type ModelTier = 1 | 2 | 3;
/**
* Model selection
*/
export type ModelSelection = 'haiku' | 'sonnet' | 'opus';
/**
* Route result from model routing
*/
export interface QERouteResult {
/** Selected model tier */
tier: ModelTier;
/** Selected model */
model: ModelSelection;
/** QE category */
qeCategory: string;
/** QE complexity score (0-1) */
qeComplexity: number;
/** Recommended agents for this task */
recommendedAgents: string[];
/** Estimated cost */
costEstimate: number;
/** Whether Agent Booster can handle this */
agentBoosterAvailable: boolean;
/** Agent Booster intent if available */
agentBoosterIntent?: string;
/** Explanation of routing decision */
explanation: string;
}
/**
* Model routing adapter interface for TinyDancer <-> ADR-026 alignment
*/
export interface IQEModelRoutingAdapter {
/**
* Route a QE task to the appropriate model tier
*/
routeQETask(task: QETask): Promise<QERouteResult>;
/**
* Get complexity score for a category
*/
getCategoryComplexity(category: string): number;
/**
* Get recommended agents for a tier and category
*/
getRecommendedAgents(category: string, tier: ModelTier): string[];
/**
* Estimate cost for a task
*/
estimateCost(task: QETask, tier: ModelTier): number;
/**
* Check if Agent Booster can handle the task
*/
canUseAgentBooster(task: QETask): { available: boolean; intent?: string };
}
// =============================================================================
// Plugin Context Interface
// =============================================================================
/**
* QE Plugin context for dependency injection
*/
export interface QEPluginContext {
/** Memory bridge */
memory: IQEMemoryBridge;
/** Security bridge */
security: IQESecurityBridge;
/** Core bridge */
core: IQECoreBridge;
/** Hive bridge */
hive: IQEHiveBridge;
/** Model routing adapter */
modelRouter: IQEModelRoutingAdapter;
/** Logger */
logger: QELogger;
/** Configuration */
config: QEPluginConfig;
}
/**
* QE logger interface
*/
export interface QELogger {
debug(message: string, ...args: unknown[]): void;
info(message: string, ...args: unknown[]): void;
warn(message: string, ...args: unknown[]): void;
error(message: string, ...args: unknown[]): void;
}
/**
* QE plugin configuration
*/
export interface QEPluginConfig {
/** Plugin namespace */
namespace: string;
/** Default timeout */
defaultTimeout: number;
/** Enable learning */
enableLearning: boolean;
/** Max concurrent tests */
maxConcurrentTests: number;
/** Coverage target */
coverageTarget: number;
/** Security level */
securityLevel: 'low' | 'medium' | 'high' | 'critical';
}