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
544 lines • 11.8 kB
TypeScript
/**
* V3 Plugin Interface
* Domain-Driven Design - Plugin-Based Architecture (ADR-004)
*
* Microkernel pattern for extensible Claude-Flow V3
* Enables modular extension points for agents, tasks, MCP tools, CLI commands, and memory backends
*/
import type { IEventBus } from './core/interfaces/event.interface.js';
import type { IAgentConfig } from './core/interfaces/agent.interface.js';
import type { MCPTool } from './types/mcp.types.js';
/**
* Logger interface for plugin context
*/
export interface ILogger {
debug(message: string, ...args: unknown[]): void;
info(message: string, ...args: unknown[]): void;
warn(message: string, ...args: unknown[]): void;
error(message: string, ...args: unknown[]): void;
}
/**
* Service container for dependency injection
*/
export interface ServiceContainer {
/**
* Register a service in the container
*/
register<T>(name: string, service: T): void;
/**
* Get a service from the container
*/
get<T>(name: string): T | undefined;
/**
* Check if a service is registered
*/
has(name: string): boolean;
/**
* Get all registered service names
*/
getServiceNames(): string[];
}
/**
* Plugin configuration
*/
export interface PluginConfig {
/**
* Plugin-specific configuration
*/
[key: string]: unknown;
/**
* Enable/disable features
*/
features?: Record<string, boolean>;
/**
* Resource limits
*/
resources?: {
maxMemoryMb?: number;
maxCpuPercent?: number;
};
}
/**
* Plugin context provided during initialization
* Contains services and resources available to plugins
*/
export interface PluginContext {
/**
* Plugin-specific configuration
*/
config: PluginConfig;
/**
* Event bus for pub/sub communication
*/
eventBus: IEventBus;
/**
* Logger instance
*/
logger: ILogger;
/**
* Service container for dependency injection
*/
services: ServiceContainer;
}
/**
* Agent type definition for plugin registration
*/
export interface AgentTypeDefinition {
/**
* Unique type identifier
*/
type: string;
/**
* Human-readable name
*/
name: string;
/**
* Description of agent capabilities
*/
description: string;
/**
* Default configuration for this agent type
*/
defaultConfig: Partial<IAgentConfig>;
/**
* Required capabilities for this agent type
*/
requiredCapabilities?: string[];
/**
* Optional metadata
*/
metadata?: Record<string, unknown>;
}
/**
* Task type definition for plugin registration
*/
export interface TaskTypeDefinition {
/**
* Unique type identifier
*/
type: string;
/**
* Human-readable name
*/
name: string;
/**
* Description of task purpose
*/
description: string;
/**
* Default priority (0-100)
*/
defaultPriority: number;
/**
* Default timeout in milliseconds
*/
defaultTimeout: number;
/**
* Required agent capabilities to execute this task
*/
requiredCapabilities?: string[];
/**
* Task input schema (JSON Schema)
*/
inputSchema?: {
type: 'object';
properties: Record<string, unknown>;
required?: string[];
};
/**
* Optional metadata
*/
metadata?: Record<string, unknown>;
}
/**
* MCP tool definition for plugin registration
*/
export interface MCPToolDefinition extends MCPTool {
/**
* Plugin that registered this tool
*/
pluginName?: string;
/**
* Tool version
*/
version?: string;
/**
* Optional metadata
*/
metadata?: Record<string, unknown>;
}
/**
* CLI command definition for plugin registration
*/
export interface CLICommandDefinition {
/**
* Command name
*/
name: string;
/**
* Command description
*/
description: string;
/**
* Command aliases
*/
aliases?: string[];
/**
* Command options
*/
options?: CLICommandOption[];
/**
* Command arguments
*/
arguments?: CLICommandArgument[];
/**
* Command handler function
*/
handler: (args: CLICommandArgs) => Promise<void> | void;
/**
* Optional metadata
*/
metadata?: Record<string, unknown>;
}
/**
* CLI command option
*/
export interface CLICommandOption {
/**
* Option name (without dashes)
*/
name: string;
/**
* Short flag (single character)
*/
short?: string;
/**
* Option description
*/
description: string;
/**
* Option type
*/
type: 'string' | 'number' | 'boolean';
/**
* Default value
*/
default?: string | number | boolean;
/**
* Is this option required?
*/
required?: boolean;
}
/**
* CLI command argument
*/
export interface CLICommandArgument {
/**
* Argument name
*/
name: string;
/**
* Argument description
*/
description: string;
/**
* Is this argument required?
*/
required?: boolean;
/**
* Default value
*/
default?: string;
/**
* Allowed values (for validation)
*/
choices?: string[];
}
/**
* CLI command parsed arguments
*/
export interface CLICommandArgs {
/**
* Positional arguments
*/
_: string[];
/**
* Named options
*/
[key: string]: unknown;
}
/**
* Memory backend factory for plugin registration
*/
export interface MemoryBackendFactory {
/**
* Backend name
*/
name: string;
/**
* Backend description
*/
description: string;
/**
* Create a new backend instance
*/
create(config: MemoryBackendConfig): Promise<IMemoryBackend>;
/**
* Backend capabilities
*/
capabilities: {
supportsVectorSearch: boolean;
supportsFullText: boolean;
supportsTransactions: boolean;
supportsPersistence: boolean;
};
/**
* Optional metadata
*/
metadata?: Record<string, unknown>;
}
/**
* Memory backend configuration
*/
export interface MemoryBackendConfig {
/**
* Storage path or connection string
*/
path?: string;
/**
* Backend-specific options
*/
options?: Record<string, unknown>;
/**
* Resource limits
*/
limits?: {
maxMemoryMb?: number;
maxStorageMb?: number;
};
}
/**
* Memory backend interface
*/
export interface IMemoryBackend {
/**
* Initialize the backend
*/
initialize(): Promise<void>;
/**
* Shutdown the backend
*/
shutdown(): Promise<void>;
/**
* Store a memory entry
*/
store(key: string, value: unknown, metadata?: Record<string, unknown>): Promise<void>;
/**
* Retrieve a memory entry
*/
retrieve(key: string): Promise<unknown | null>;
/**
* Delete a memory entry
*/
delete(key: string): Promise<boolean>;
/**
* Search memory entries
*/
search(query: string, options?: MemorySearchOptions): Promise<MemorySearchResult[]>;
/**
* Clear all memory entries
*/
clear(): Promise<void>;
/**
* Get backend statistics
*/
getStats(): Promise<MemoryBackendStats>;
}
/**
* Memory search options
*/
export interface MemorySearchOptions {
/**
* Maximum number of results
*/
limit?: number;
/**
* Result offset for pagination
*/
offset?: number;
/**
* Minimum similarity score (0-1)
*/
minScore?: number;
/**
* Filter by metadata
*/
filter?: Record<string, unknown>;
}
/**
* Memory search result
*/
export interface MemorySearchResult {
/**
* Memory key
*/
key: string;
/**
* Memory value
*/
value: unknown;
/**
* Similarity score (0-1)
*/
score: number;
/**
* Associated metadata
*/
metadata?: Record<string, unknown>;
}
/**
* Memory backend statistics
*/
export interface MemoryBackendStats {
/**
* Total number of entries
*/
entryCount: number;
/**
* Total storage size in bytes
*/
sizeBytes: number;
/**
* Memory usage in bytes
*/
memoryUsageBytes: number;
/**
* Backend-specific metrics
*/
metrics?: Record<string, number>;
}
/**
* Core ClaudeFlowPlugin interface
* All plugins must implement this interface
*/
export interface ClaudeFlowPlugin {
/**
* Unique plugin name
*/
readonly name: string;
/**
* Plugin version (semver)
*/
readonly version: string;
/**
* Optional plugin dependencies
* List of plugin names that must be loaded before this plugin
*/
readonly dependencies?: string[];
/**
* Plugin description
*/
readonly description?: string;
/**
* Plugin author
*/
readonly author?: string;
/**
* Initialize the plugin
* Called after all dependencies are loaded
*/
initialize(context: PluginContext): Promise<void>;
/**
* Shutdown the plugin
* Called during system shutdown
*/
shutdown(): Promise<void>;
/**
* Register custom agent types (optional)
* @returns Array of agent type definitions
*/
registerAgentTypes?(): AgentTypeDefinition[];
/**
* Register custom task types (optional)
* @returns Array of task type definitions
*/
registerTaskTypes?(): TaskTypeDefinition[];
/**
* Register MCP tools (optional)
* @returns Array of MCP tool definitions
*/
registerMCPTools?(): MCPToolDefinition[];
/**
* Register CLI commands (optional)
* @returns Array of CLI command definitions
*/
registerCLICommands?(): CLICommandDefinition[];
/**
* Register memory backends (optional)
* @returns Array of memory backend factories
*/
registerMemoryBackends?(): MemoryBackendFactory[];
/**
* Optional health check
* @returns true if plugin is healthy, false otherwise
*/
healthCheck?(): Promise<boolean>;
/**
* Optional plugin metadata
*/
metadata?: Record<string, unknown>;
}
/**
* Plugin lifecycle state
*/
export type PluginLifecycleState = 'uninitialized' | 'initializing' | 'initialized' | 'shutting-down' | 'shutdown' | 'error';
/**
* Plugin info for registry tracking
*/
export interface PluginInfo {
/**
* Plugin instance
*/
plugin: ClaudeFlowPlugin;
/**
* Current lifecycle state
*/
state: PluginLifecycleState;
/**
* Initialization timestamp
*/
initializedAt?: Date;
/**
* Shutdown timestamp
*/
shutdownAt?: Date;
/**
* Plugin context
*/
context?: PluginContext;
/**
* Error if state is 'error'
*/
error?: Error;
/**
* Plugin metrics
*/
metrics?: {
agentTypesRegistered: number;
taskTypesRegistered: number;
mcpToolsRegistered: number;
cliCommandsRegistered: number;
memoryBackendsRegistered: number;
};
}
/**
* Plugin error types
*/
export declare class PluginError extends Error {
readonly pluginName: string;
readonly code: PluginErrorCode;
readonly cause?: Error | undefined;
constructor(message: string, pluginName: string, code: PluginErrorCode, cause?: Error | undefined);
}
export type PluginErrorCode = 'INITIALIZATION_FAILED' | 'SHUTDOWN_FAILED' | 'DEPENDENCY_NOT_FOUND' | 'CIRCULAR_DEPENDENCY' | 'INVALID_PLUGIN' | 'DUPLICATE_PLUGIN' | 'HEALTH_CHECK_FAILED';
//# sourceMappingURL=plugin-interface.d.ts.map