Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 | /** * Core Plugin Interface * * Defines the contract that all plugins must implement. */ import type { PluginMetadata, PluginContext, PluginLifecycleState, AgentTypeDefinition, TaskTypeDefinition, MCPToolDefinition, CLICommandDefinition, MemoryBackendFactory, HookDefinition, WorkerDefinition, LLMProviderDefinition, HealthCheckResult, } from '../types/index.js'; // ============================================================================ // Plugin Interface // ============================================================================ /** * Core plugin interface that all plugins must implement. * * Plugins provide extensibility across multiple domains: * - Agent types and task definitions * - MCP tools for Claude interaction * - CLI commands for terminal interface * - Memory backends for storage * - Hooks for lifecycle events * - Workers for parallel execution * - LLM providers for model access */ export interface IPlugin { /** Plugin metadata (name, version, etc.) */ readonly metadata: PluginMetadata; /** Current lifecycle state */ readonly state: PluginLifecycleState; // ========================================================================= // Lifecycle Methods // ========================================================================= /** * Initialize the plugin with context. * Called once when the plugin is loaded. */ initialize(context: PluginContext): Promise<void>; /** * Shutdown the plugin gracefully. * Called when the plugin is being unloaded. */ shutdown(): Promise<void>; /** * Check plugin health. * Called periodically for monitoring. */ healthCheck?(): Promise<HealthCheckResult>; // ========================================================================= // Extension Point Registration // ========================================================================= /** * Register agent type definitions. * Called during initialization to collect agent types. */ registerAgentTypes?(): AgentTypeDefinition[]; /** * Register task type definitions. * Called during initialization to collect task types. */ registerTaskTypes?(): TaskTypeDefinition[]; /** * Register MCP tool definitions. * Called during initialization to expose tools to Claude. */ registerMCPTools?(): MCPToolDefinition[]; /** * Register CLI command definitions. * Called during initialization to extend the CLI. */ registerCLICommands?(): CLICommandDefinition[]; /** * Register memory backend factories. * Called during initialization to add storage options. */ registerMemoryBackends?(): MemoryBackendFactory[]; /** * Register hook definitions. * Called during initialization to add lifecycle hooks. */ registerHooks?(): HookDefinition[]; /** * Register worker definitions. * Called during initialization to add worker types. */ registerWorkers?(): WorkerDefinition[]; /** * Register LLM provider definitions. * Called during initialization to add model providers. */ registerProviders?(): LLMProviderDefinition[]; } // ============================================================================ // Plugin Factory // ============================================================================ /** * Factory function type for creating plugin instances. */ export type PluginFactory = () => IPlugin | Promise<IPlugin>; /** * Plugin module export interface. * Plugins should export a default factory or plugin instance. */ export interface PluginModule { default: IPlugin | PluginFactory; metadata?: PluginMetadata; } // ============================================================================ // Plugin Events // ============================================================================ export const PLUGIN_EVENTS = { LOADING: 'plugin:loading', LOADED: 'plugin:loaded', INITIALIZING: 'plugin:initializing', INITIALIZED: 'plugin:initialized', SHUTTING_DOWN: 'plugin:shutting-down', SHUTDOWN: 'plugin:shutdown', ERROR: 'plugin:error', HEALTH_CHECK: 'plugin:health-check', } as const; export type PluginEvent = typeof PLUGIN_EVENTS[keyof typeof PLUGIN_EVENTS]; // ============================================================================ // Plugin Validation // ============================================================================ /** * Validate plugin metadata. */ export function validatePluginMetadata(metadata: unknown): metadata is PluginMetadata { if (!metadata || typeof metadata !== 'object') return false; const m = metadata as Record<string, unknown>; if (typeof m.name !== 'string' || m.name.length === 0) return false; if (typeof m.version !== 'string' || !/^\d+\.\d+\.\d+/.test(m.version)) return false; if (m.description !== undefined && typeof m.description !== 'string') return false; if (m.author !== undefined && typeof m.author !== 'string') return false; if (m.dependencies !== undefined) { if (!Array.isArray(m.dependencies)) return false; if (!m.dependencies.every(d => typeof d === 'string')) return false; } return true; } /** * Validate plugin interface. */ export function validatePlugin(plugin: unknown): plugin is IPlugin { if (!plugin || typeof plugin !== 'object') return false; const p = plugin as Record<string, unknown>; // Check required properties if (!validatePluginMetadata(p.metadata)) return false; if (typeof p.state !== 'string') return false; if (typeof p.initialize !== 'function') return false; if (typeof p.shutdown !== 'function') return false; // Check optional methods are functions if present const optionalMethods = [ 'healthCheck', 'registerAgentTypes', 'registerTaskTypes', 'registerMCPTools', 'registerCLICommands', 'registerMemoryBackends', 'registerHooks', 'registerWorkers', 'registerProviders', ]; for (const method of optionalMethods) { if (p[method] !== undefined && typeof p[method] !== 'function') { return false; } } return true; } |