elsabro 2.2.0 → 3.7.0

package/references/plugin-system.md

@@ -0,0 +1,1526 @@
+# ELSABRO Plugin System
+
+> Sistema de plugins extensible con carga dinámica, aislamiento y gestión de lifecycle.
+
+## Arquitectura General
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           Plugin System                                  │
+├─────────────────────────────────────────────────────────────────────────┤
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐         │
+│  │  PluginLoader   │  │ PluginRegistry  │  │ PluginManager   │         │
+│  │  ─────────────  │  │  ─────────────  │  │  ─────────────  │         │
+│  │ • Discovery     │  │ • Registration  │  │ • Lifecycle     │         │
+│  │ • Validation    │  │ • Dependencies  │  │ • Hot-reload    │         │
+│  │ • Isolation     │  │ • Versioning    │  │ • Health        │         │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘         │
+│                              │                                          │
+│  ┌───────────────────────────┴───────────────────────────────┐         │
+│  │                      HookSystem                            │         │
+│  │  • Before/After hooks • Middleware • Event propagation    │         │
+│  └────────────────────────────────────────────────────────────┘         │
+│                              │                                          │
+│  ┌───────────────────────────┴───────────────────────────────┐         │
+│  │                    PluginContext                           │         │
+│  │  • Sandboxed APIs • Resource limits • Permissions         │         │
+│  └────────────────────────────────────────────────────────────┘         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 1. Plugin Definition
+
+### Estructura de Plugin
+
+```typescript
+interface PluginManifest {
+  // Identity
+  name: string;           // Unique identifier (e.g., "elsabro-git-plugin")
+  version: string;        // Semver (e.g., "1.2.3")
+  displayName: string;    // Human-readable name
+  description: string;
+  author: string | { name: string; email?: string; url?: string };
+  license: string;
+
+  // Entry points
+  main: string;           // Main entry file
+  types?: string;         // TypeScript definitions
+
+  // Dependencies
+  engines: {
+    elsabro: string;      // Required ELSABRO version (semver range)
+    node?: string;        // Node.js version
+  };
+  dependencies?: Record<string, string>;       // npm packages
+  pluginDependencies?: Record<string, string>; // Other ELSABRO plugins
+
+  // Capabilities
+  contributes?: {
+    agents?: AgentContribution[];
+    tools?: ToolContribution[];
+    commands?: CommandContribution[];
+    hooks?: HookContribution[];
+    config?: ConfigContribution;
+    views?: ViewContribution[];
+  };
+
+  // Permissions
+  permissions?: PluginPermission[];
+
+  // Activation
+  activationEvents?: string[];  // When to activate (e.g., "onCommand:myCmd")
+}
+
+type PluginPermission =
+  | 'filesystem:read'
+  | 'filesystem:write'
+  | 'network'
+  | 'shell'
+  | 'env'
+  | 'secrets'
+  | 'config:read'
+  | 'config:write';
+```
+
+### Plugin Interface
+
+```typescript
+interface Plugin {
+  // Lifecycle
+  activate(context: PluginContext): Promise<void>;
+  deactivate?(): Promise<void>;
+
+  // Optional exports
+  api?: Record<string, unknown>;  // Public API for other plugins
+}
+
+interface PluginContext {
+  // Plugin info
+  readonly pluginPath: string;
+  readonly manifest: PluginManifest;
+
+  // Storage
+  readonly globalState: Memento;
+  readonly workspaceState: Memento;
+  readonly secrets: SecretsStorage;
+
+  // Subscriptions (auto-disposed on deactivate)
+  subscriptions: Disposable[];
+
+  // Logging
+  readonly logger: Logger;
+
+  // Extension APIs
+  readonly elsabro: ElsabroAPI;
+}
+
+interface Memento {
+  get<T>(key: string, defaultValue?: T): T;
+  update(key: string, value: unknown): Promise<void>;
+  keys(): readonly string[];
+}
+
+interface Disposable {
+  dispose(): void;
+}
+```
+
+---
+
+## 2. PluginLoader
+
+### Propósito
+Descubre, valida y carga plugins desde múltiples fuentes.
+
+### Interfaz
+
+```typescript
+interface PluginSource {
+  type: 'directory' | 'npm' | 'url';
+  path?: string;
+  package?: string;
+  url?: string;
+}
+
+interface LoadedPlugin {
+  manifest: PluginManifest;
+  module: Plugin;
+  path: string;
+  state: PluginState;
+}
+
+type PluginState =
+  | 'discovered'
+  | 'validated'
+  | 'loaded'
+  | 'activated'
+  | 'deactivated'
+  | 'error';
+
+interface PluginLoader {
+  // Discovery
+  discover(sources: PluginSource[]): Promise<PluginManifest[]>;
+  discoverFromDirectory(path: string): Promise<PluginManifest[]>;
+
+  // Validation
+  validate(manifest: PluginManifest): ValidationResult;
+  checkDependencies(manifest: PluginManifest): DependencyResult;
+
+  // Loading
+  load(manifest: PluginManifest): Promise<LoadedPlugin>;
+  loadAll(manifests: PluginManifest[]): Promise<LoadedPlugin[]>;
+
+  // Isolation
+  createSandbox(plugin: LoadedPlugin): PluginSandbox;
+}
+```
+
+### Implementación
+
+```typescript
+class PluginLoaderImpl implements PluginLoader {
+  private loadedPlugins: Map<string, LoadedPlugin> = new Map();
+
+  constructor(
+    private config: ConfigManager,
+    private registry: PluginRegistry
+  ) {}
+
+  async discover(sources: PluginSource[]): Promise<PluginManifest[]> {
+    const manifests: PluginManifest[] = [];
+
+    for (const source of sources) {
+      try {
+        switch (source.type) {
+          case 'directory':
+            manifests.push(...await this.discoverFromDirectory(source.path!));
+            break;
+          case 'npm':
+            manifests.push(await this.discoverFromNpm(source.package!));
+            break;
+          case 'url':
+            manifests.push(await this.discoverFromUrl(source.url!));
+            break;
+        }
+      } catch (error) {
+        console.warn(`Failed to discover plugins from ${source.type}:`, error);
+      }
+    }
+
+    return manifests;
+  }
+
+  async discoverFromDirectory(dirPath: string): Promise<PluginManifest[]> {
+    const manifests: PluginManifest[] = [];
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+
+      const pluginPath = path.join(dirPath, entry.name);
+      const manifestPath = path.join(pluginPath, 'plugin.json');
+
+      if (await this.fileExists(manifestPath)) {
+        try {
+          const content = await fs.readFile(manifestPath, 'utf-8');
+          const manifest = JSON.parse(content) as PluginManifest;
+          manifest._path = pluginPath;
+          manifests.push(manifest);
+        } catch (error) {
+          console.warn(`Invalid plugin manifest at ${manifestPath}:`, error);
+        }
+      }
+    }
+
+    return manifests;
+  }
+
+  private async discoverFromNpm(packageName: string): Promise<PluginManifest> {
+    const packagePath = require.resolve(`${packageName}/plugin.json`);
+    const content = await fs.readFile(packagePath, 'utf-8');
+    const manifest = JSON.parse(content);
+    manifest._path = path.dirname(packagePath);
+    return manifest;
+  }
+
+  validate(manifest: PluginManifest): ValidationResult {
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    // Required fields
+    if (!manifest.name) errors.push('Missing required field: name');
+    if (!manifest.version) errors.push('Missing required field: version');
+    if (!manifest.main) errors.push('Missing required field: main');
+
+    // Version format
+    if (manifest.version && !semver.valid(manifest.version)) {
+      errors.push(`Invalid version format: ${manifest.version}`);
+    }
+
+    // Engine compatibility
+    if (manifest.engines?.elsabro) {
+      const elsabroVersion = this.config.get<string>('version');
+      if (!semver.satisfies(elsabroVersion, manifest.engines.elsabro)) {
+        errors.push(
+          `Incompatible ELSABRO version. Required: ${manifest.engines.elsabro}, Current: ${elsabroVersion}`
+        );
+      }
+    }
+
+    // Permissions validation
+    if (manifest.permissions) {
+      const validPermissions = [
+        'filesystem:read', 'filesystem:write', 'network',
+        'shell', 'env', 'secrets', 'config:read', 'config:write'
+      ];
+      for (const perm of manifest.permissions) {
+        if (!validPermissions.includes(perm)) {
+          warnings.push(`Unknown permission: ${perm}`);
+        }
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings
+    };
+  }
+
+  checkDependencies(manifest: PluginManifest): DependencyResult {
+    const missing: string[] = [];
+    const incompatible: Array<{ name: string; required: string; installed: string }> = [];
+
+    // Check plugin dependencies
+    if (manifest.pluginDependencies) {
+      for (const [name, versionRange] of Object.entries(manifest.pluginDependencies)) {
+        const installed = this.registry.get(name);
+        if (!installed) {
+          missing.push(name);
+        } else if (!semver.satisfies(installed.manifest.version, versionRange)) {
+          incompatible.push({
+            name,
+            required: versionRange,
+            installed: installed.manifest.version
+          });
+        }
+      }
+    }
+
+    return {
+      satisfied: missing.length === 0 && incompatible.length === 0,
+      missing,
+      incompatible
+    };
+  }
+
+  async load(manifest: PluginManifest): Promise<LoadedPlugin> {
+    const validation = this.validate(manifest);
+    if (!validation.valid) {
+      throw new PluginLoadError(manifest.name, validation.errors);
+    }
+
+    const depCheck = this.checkDependencies(manifest);
+    if (!depCheck.satisfied) {
+      throw new PluginDependencyError(manifest.name, depCheck);
+    }
+
+    // Load the plugin module
+    const mainPath = path.join(manifest._path!, manifest.main);
+    const module = await import(mainPath);
+
+    const plugin: LoadedPlugin = {
+      manifest,
+      module: module.default || module,
+      path: manifest._path!,
+      state: 'loaded'
+    };
+
+    this.loadedPlugins.set(manifest.name, plugin);
+    return plugin;
+  }
+
+  async loadAll(manifests: PluginManifest[]): Promise<LoadedPlugin[]> {
+    // Sort by dependencies
+    const sorted = this.topologicalSort(manifests);
+
+    const loaded: LoadedPlugin[] = [];
+    for (const manifest of sorted) {
+      try {
+        const plugin = await this.load(manifest);
+        loaded.push(plugin);
+      } catch (error) {
+        console.error(`Failed to load plugin ${manifest.name}:`, error);
+      }
+    }
+
+    return loaded;
+  }
+
+  private topologicalSort(manifests: PluginManifest[]): PluginManifest[] {
+    const graph = new Map<string, Set<string>>();
+    const manifestMap = new Map<string, PluginManifest>();
+
+    // Build dependency graph
+    for (const manifest of manifests) {
+      manifestMap.set(manifest.name, manifest);
+      graph.set(manifest.name, new Set(
+        Object.keys(manifest.pluginDependencies || {})
+      ));
+    }
+
+    // Kahn's algorithm
+    const result: PluginManifest[] = [];
+    const noDeps = manifests.filter(m => (graph.get(m.name)?.size || 0) === 0);
+
+    while (noDeps.length > 0) {
+      const current = noDeps.shift()!;
+      result.push(current);
+
+      for (const [name, deps] of graph) {
+        if (deps.has(current.name)) {
+          deps.delete(current.name);
+          if (deps.size === 0) {
+            noDeps.push(manifestMap.get(name)!);
+          }
+        }
+      }
+    }
+
+    // Check for cycles
+    if (result.length !== manifests.length) {
+      throw new Error('Circular dependency detected in plugins');
+    }
+
+    return result;
+  }
+
+  createSandbox(plugin: LoadedPlugin): PluginSandbox {
+    return new PluginSandbox(plugin, {
+      permissions: plugin.manifest.permissions || [],
+      resourceLimits: this.config.get('plugins.resourceLimits', {
+        memory: 128 * 1024 * 1024, // 128MB
+        cpu: 0.5
+      })
+    });
+  }
+
+  private async fileExists(path: string): Promise<boolean> {
+    try {
+      await fs.access(path);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+```
+
+---
+
+## 3. PluginRegistry
+
+### Propósito
+Mantiene el registro de plugins instalados y sus contribuciones.
+
+### Interfaz
+
+```typescript
+interface PluginRegistry {
+  // Registration
+  register(plugin: LoadedPlugin): void;
+  unregister(name: string): void;
+
+  // Queries
+  get(name: string): LoadedPlugin | undefined;
+  getAll(): LoadedPlugin[];
+  getByState(state: PluginState): LoadedPlugin[];
+  find(predicate: (plugin: LoadedPlugin) => boolean): LoadedPlugin[];
+
+  // Contributions
+  getAgents(): AgentContribution[];
+  getTools(): ToolContribution[];
+  getCommands(): CommandContribution[];
+  getHooks(point: string): HookContribution[];
+
+  // Dependencies
+  getDependents(name: string): LoadedPlugin[];
+  getDependencies(name: string): LoadedPlugin[];
+
+  // Events
+  onRegister(callback: (plugin: LoadedPlugin) => void): Disposable;
+  onUnregister(callback: (name: string) => void): Disposable;
+}
+
+interface AgentContribution {
+  pluginName: string;
+  name: string;
+  displayName: string;
+  description: string;
+  model?: string;
+  systemPrompt?: string;
+  tools?: string[];
+}
+
+interface ToolContribution {
+  pluginName: string;
+  name: string;
+  displayName: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  handler: string;  // Reference to handler function
+}
+
+interface CommandContribution {
+  pluginName: string;
+  command: string;
+  title: string;
+  description?: string;
+  category?: string;
+  handler: string;
+}
+
+interface HookContribution {
+  pluginName: string;
+  point: string;
+  priority: number;
+  handler: string;
+}
+```
+
+### Implementación
+
+```typescript
+class PluginRegistryImpl implements PluginRegistry {
+  private plugins: Map<string, LoadedPlugin> = new Map();
+  private contributions = {
+    agents: new Map<string, AgentContribution>(),
+    tools: new Map<string, ToolContribution>(),
+    commands: new Map<string, CommandContribution>(),
+    hooks: new Map<string, HookContribution[]>()
+  };
+
+  private registerCallbacks: Set<Function> = new Set();
+  private unregisterCallbacks: Set<Function> = new Set();
+
+  register(plugin: LoadedPlugin): void {
+    const { manifest } = plugin;
+
+    // Check for duplicates
+    if (this.plugins.has(manifest.name)) {
+      throw new Error(`Plugin already registered: ${manifest.name}`);
+    }
+
+    this.plugins.set(manifest.name, plugin);
+
+    // Register contributions
+    if (manifest.contributes) {
+      this.registerContributions(manifest.name, manifest.contributes);
+    }
+
+    // Notify listeners
+    this.registerCallbacks.forEach(cb => cb(plugin));
+  }
+
+  unregister(name: string): void {
+    const plugin = this.plugins.get(name);
+    if (!plugin) return;
+
+    // Check for dependents
+    const dependents = this.getDependents(name);
+    if (dependents.length > 0) {
+      throw new Error(
+        `Cannot unregister ${name}: required by ${dependents.map(p => p.manifest.name).join(', ')}`
+      );
+    }
+
+    // Remove contributions
+    this.removeContributions(name);
+
+    this.plugins.delete(name);
+    this.unregisterCallbacks.forEach(cb => cb(name));
+  }
+
+  private registerContributions(pluginName: string, contributes: PluginManifest['contributes']): void {
+    if (contributes.agents) {
+      for (const agent of contributes.agents) {
+        this.contributions.agents.set(agent.name, { ...agent, pluginName });
+      }
+    }
+
+    if (contributes.tools) {
+      for (const tool of contributes.tools) {
+        this.contributions.tools.set(tool.name, { ...tool, pluginName });
+      }
+    }
+
+    if (contributes.commands) {
+      for (const cmd of contributes.commands) {
+        this.contributions.commands.set(cmd.command, { ...cmd, pluginName });
+      }
+    }
+
+    if (contributes.hooks) {
+      for (const hook of contributes.hooks) {
+        const hookWithPlugin = { ...hook, pluginName };
+        if (!this.contributions.hooks.has(hook.point)) {
+          this.contributions.hooks.set(hook.point, []);
+        }
+        this.contributions.hooks.get(hook.point)!.push(hookWithPlugin);
+        // Sort by priority
+        this.contributions.hooks.get(hook.point)!.sort((a, b) => a.priority - b.priority);
+      }
+    }
+  }
+
+  private removeContributions(pluginName: string): void {
+    // Remove agents
+    for (const [name, agent] of this.contributions.agents) {
+      if (agent.pluginName === pluginName) {
+        this.contributions.agents.delete(name);
+      }
+    }
+
+    // Remove tools
+    for (const [name, tool] of this.contributions.tools) {
+      if (tool.pluginName === pluginName) {
+        this.contributions.tools.delete(name);
+      }
+    }
+
+    // Remove commands
+    for (const [name, cmd] of this.contributions.commands) {
+      if (cmd.pluginName === pluginName) {
+        this.contributions.commands.delete(name);
+      }
+    }
+
+    // Remove hooks
+    for (const [point, hooks] of this.contributions.hooks) {
+      this.contributions.hooks.set(
+        point,
+        hooks.filter(h => h.pluginName !== pluginName)
+      );
+    }
+  }
+
+  get(name: string): LoadedPlugin | undefined {
+    return this.plugins.get(name);
+  }
+
+  getAll(): LoadedPlugin[] {
+    return Array.from(this.plugins.values());
+  }
+
+  getByState(state: PluginState): LoadedPlugin[] {
+    return this.getAll().filter(p => p.state === state);
+  }
+
+  find(predicate: (plugin: LoadedPlugin) => boolean): LoadedPlugin[] {
+    return this.getAll().filter(predicate);
+  }
+
+  getAgents(): AgentContribution[] {
+    return Array.from(this.contributions.agents.values());
+  }
+
+  getTools(): ToolContribution[] {
+    return Array.from(this.contributions.tools.values());
+  }
+
+  getCommands(): CommandContribution[] {
+    return Array.from(this.contributions.commands.values());
+  }
+
+  getHooks(point: string): HookContribution[] {
+    return this.contributions.hooks.get(point) || [];
+  }
+
+  getDependents(name: string): LoadedPlugin[] {
+    return this.getAll().filter(plugin => {
+      const deps = plugin.manifest.pluginDependencies || {};
+      return name in deps;
+    });
+  }
+
+  getDependencies(name: string): LoadedPlugin[] {
+    const plugin = this.plugins.get(name);
+    if (!plugin) return [];
+
+    const deps = plugin.manifest.pluginDependencies || {};
+    return Object.keys(deps)
+      .map(depName => this.plugins.get(depName))
+      .filter((p): p is LoadedPlugin => p !== undefined);
+  }
+
+  onRegister(callback: Function): Disposable {
+    this.registerCallbacks.add(callback);
+    return { dispose: () => this.registerCallbacks.delete(callback) };
+  }
+
+  onUnregister(callback: Function): Disposable {
+    this.unregisterCallbacks.add(callback);
+    return { dispose: () => this.unregisterCallbacks.delete(callback) };
+  }
+}
+```
+
+---
+
+## 4. PluginManager
+
+### Propósito
+Gestiona el lifecycle completo de plugins incluyendo activación, desactivación y hot-reload.
+
+### Interfaz
+
+```typescript
+interface PluginManager {
+  // Lifecycle
+  activate(name: string): Promise<void>;
+  activateAll(): Promise<void>;
+  deactivate(name: string): Promise<void>;
+  deactivateAll(): Promise<void>;
+  reload(name: string): Promise<void>;
+
+  // Installation
+  install(source: PluginSource): Promise<LoadedPlugin>;
+  uninstall(name: string): Promise<void>;
+  update(name: string): Promise<LoadedPlugin>;
+
+  // Status
+  getStatus(name: string): PluginStatus;
+  getAllStatus(): Map<string, PluginStatus>;
+  isActive(name: string): boolean;
+
+  // Hot-reload
+  enableHotReload(name: string): void;
+  disableHotReload(name: string): void;
+
+  // Events
+  onActivate(callback: (plugin: LoadedPlugin) => void): Disposable;
+  onDeactivate(callback: (name: string) => void): Disposable;
+  onError(callback: (error: PluginError) => void): Disposable;
+}
+
+interface PluginStatus {
+  state: PluginState;
+  activatedAt?: Date;
+  error?: Error;
+  resourceUsage?: {
+    memory: number;
+    cpu: number;
+  };
+}
+```
+
+### Implementación
+
+```typescript
+class PluginManagerImpl implements PluginManager {
+  private contexts: Map<string, PluginContext> = new Map();
+  private watchers: Map<string, FSWatcher> = new Map();
+  private activateCallbacks: Set<Function> = new Set();
+  private deactivateCallbacks: Set<Function> = new Set();
+  private errorCallbacks: Set<Function> = new Set();
+
+  constructor(
+    private loader: PluginLoader,
+    private registry: PluginRegistry,
+    private config: ConfigManager
+  ) {}
+
+  async activate(name: string): Promise<void> {
+    const plugin = this.registry.get(name);
+    if (!plugin) {
+      throw new Error(`Plugin not found: ${name}`);
+    }
+
+    if (plugin.state === 'activated') {
+      return; // Already active
+    }
+
+    // Activate dependencies first
+    const deps = this.registry.getDependencies(name);
+    for (const dep of deps) {
+      if (dep.state !== 'activated') {
+        await this.activate(dep.manifest.name);
+      }
+    }
+
+    // Create context
+    const context = this.createContext(plugin);
+    this.contexts.set(name, context);
+
+    try {
+      // Activate plugin
+      await plugin.module.activate(context);
+      plugin.state = 'activated';
+
+      this.activateCallbacks.forEach(cb => cb(plugin));
+    } catch (error) {
+      plugin.state = 'error';
+      this.errorCallbacks.forEach(cb => cb({ plugin: name, error }));
+      throw error;
+    }
+  }
+
+  async activateAll(): Promise<void> {
+    const plugins = this.registry.getAll();
+    const sorted = this.sortByDependencies(plugins);
+
+    for (const plugin of sorted) {
+      try {
+        await this.activate(plugin.manifest.name);
+      } catch (error) {
+        console.error(`Failed to activate ${plugin.manifest.name}:`, error);
+      }
+    }
+  }
+
+  async deactivate(name: string): Promise<void> {
+    const plugin = this.registry.get(name);
+    if (!plugin || plugin.state !== 'activated') {
+      return;
+    }
+
+    // Check if any active plugins depend on this one
+    const dependents = this.registry.getDependents(name);
+    const activeDependents = dependents.filter(p => p.state === 'activated');
+    if (activeDependents.length > 0) {
+      throw new Error(
+        `Cannot deactivate ${name}: still required by active plugins: ` +
+        activeDependents.map(p => p.manifest.name).join(', ')
+      );
+    }
+
+    const context = this.contexts.get(name);
+
+    try {
+      // Call deactivate if implemented
+      if (plugin.module.deactivate) {
+        await plugin.module.deactivate();
+      }
+
+      // Dispose all subscriptions
+      if (context) {
+        for (const sub of context.subscriptions) {
+          sub.dispose();
+        }
+        this.contexts.delete(name);
+      }
+
+      plugin.state = 'deactivated';
+      this.deactivateCallbacks.forEach(cb => cb(name));
+    } catch (error) {
+      plugin.state = 'error';
+      this.errorCallbacks.forEach(cb => cb({ plugin: name, error }));
+      throw error;
+    }
+  }
+
+  async deactivateAll(): Promise<void> {
+    const plugins = this.registry.getByState('activated');
+    const sorted = this.sortByDependencies(plugins).reverse();
+
+    for (const plugin of sorted) {
+      try {
+        await this.deactivate(plugin.manifest.name);
+      } catch (error) {
+        console.error(`Failed to deactivate ${plugin.manifest.name}:`, error);
+      }
+    }
+  }
+
+  async reload(name: string): Promise<void> {
+    const plugin = this.registry.get(name);
+    if (!plugin) {
+      throw new Error(`Plugin not found: ${name}`);
+    }
+
+    const wasActive = plugin.state === 'activated';
+
+    // Deactivate if active
+    if (wasActive) {
+      await this.deactivate(name);
+    }
+
+    // Unregister old version
+    this.registry.unregister(name);
+
+    // Clear module cache
+    this.clearModuleCache(plugin.path);
+
+    // Reload manifest and module
+    const manifests = await this.loader.discoverFromDirectory(
+      path.dirname(plugin.path)
+    );
+    const manifest = manifests.find(m => m.name === name);
+    if (!manifest) {
+      throw new Error(`Plugin manifest not found after reload: ${name}`);
+    }
+
+    // Load and register
+    const reloaded = await this.loader.load(manifest);
+    this.registry.register(reloaded);
+
+    // Reactivate if was active
+    if (wasActive) {
+      await this.activate(name);
+    }
+  }
+
+  async install(source: PluginSource): Promise<LoadedPlugin> {
+    // Discover plugin
+    const manifests = await this.loader.discover([source]);
+    if (manifests.length === 0) {
+      throw new Error('No plugin found at source');
+    }
+
+    const manifest = manifests[0];
+
+    // Check if already installed
+    if (this.registry.get(manifest.name)) {
+      throw new Error(`Plugin already installed: ${manifest.name}`);
+    }
+
+    // Load and register
+    const plugin = await this.loader.load(manifest);
+    this.registry.register(plugin);
+
+    return plugin;
+  }
+
+  async uninstall(name: string): Promise<void> {
+    const plugin = this.registry.get(name);
+    if (!plugin) {
+      throw new Error(`Plugin not found: ${name}`);
+    }
+
+    // Deactivate if active
+    if (plugin.state === 'activated') {
+      await this.deactivate(name);
+    }
+
+    // Stop hot-reload watching
+    this.disableHotReload(name);
+
+    // Unregister
+    this.registry.unregister(name);
+
+    // Clear module cache
+    this.clearModuleCache(plugin.path);
+  }
+
+  async update(name: string): Promise<LoadedPlugin> {
+    const plugin = this.registry.get(name);
+    if (!plugin) {
+      throw new Error(`Plugin not found: ${name}`);
+    }
+
+    // TODO: Fetch latest version from source
+    // For now, just reload
+    await this.reload(name);
+    return this.registry.get(name)!;
+  }
+
+  enableHotReload(name: string): void {
+    const plugin = this.registry.get(name);
+    if (!plugin) return;
+
+    if (this.watchers.has(name)) return; // Already watching
+
+    const watcher = fs.watch(plugin.path, { recursive: true }, async (event, filename) => {
+      if (!filename || !this.shouldReload(filename)) return;
+
+      console.log(`Hot-reloading plugin ${name} due to change in ${filename}`);
+      try {
+        await this.reload(name);
+      } catch (error) {
+        console.error(`Hot-reload failed for ${name}:`, error);
+        this.errorCallbacks.forEach(cb => cb({ plugin: name, error }));
+      }
+    });
+
+    this.watchers.set(name, watcher);
+  }
+
+  disableHotReload(name: string): void {
+    const watcher = this.watchers.get(name);
+    if (watcher) {
+      watcher.close();
+      this.watchers.delete(name);
+    }
+  }
+
+  private shouldReload(filename: string): boolean {
+    const ext = path.extname(filename);
+    return ['.js', '.ts', '.json'].includes(ext) && !filename.includes('node_modules');
+  }
+
+  private createContext(plugin: LoadedPlugin): PluginContext {
+    const storagePath = path.join(
+      this.config.get('plugins.storagePath', '.elsabro/plugins'),
+      plugin.manifest.name
+    );
+
+    return {
+      pluginPath: plugin.path,
+      manifest: plugin.manifest,
+      globalState: new MementoImpl(path.join(storagePath, 'global-state.json')),
+      workspaceState: new MementoImpl(path.join(storagePath, 'workspace-state.json')),
+      secrets: new SecretsStorageImpl(plugin.manifest.name),
+      subscriptions: [],
+      logger: new PluginLogger(plugin.manifest.name),
+      elsabro: this.createElsabroAPI(plugin)
+    };
+  }
+
+  private createElsabroAPI(plugin: LoadedPlugin): ElsabroAPI {
+    const permissions = new Set(plugin.manifest.permissions || []);
+
+    return {
+      // Only expose APIs based on permissions
+      config: permissions.has('config:read') ? this.config : undefined,
+      secrets: permissions.has('secrets') ? secretsVault : undefined,
+      // ... other APIs
+    };
+  }
+
+  getStatus(name: string): PluginStatus {
+    const plugin = this.registry.get(name);
+    if (!plugin) {
+      return { state: 'error', error: new Error('Plugin not found') };
+    }
+
+    return {
+      state: plugin.state,
+      activatedAt: plugin._activatedAt,
+      error: plugin._lastError,
+      resourceUsage: this.getResourceUsage(name)
+    };
+  }
+
+  getAllStatus(): Map<string, PluginStatus> {
+    const status = new Map<string, PluginStatus>();
+    for (const plugin of this.registry.getAll()) {
+      status.set(plugin.manifest.name, this.getStatus(plugin.manifest.name));
+    }
+    return status;
+  }
+
+  isActive(name: string): boolean {
+    const plugin = this.registry.get(name);
+    return plugin?.state === 'activated';
+  }
+
+  private sortByDependencies(plugins: LoadedPlugin[]): LoadedPlugin[] {
+    // Topological sort by dependencies
+    const visited = new Set<string>();
+    const result: LoadedPlugin[] = [];
+
+    const visit = (plugin: LoadedPlugin) => {
+      if (visited.has(plugin.manifest.name)) return;
+      visited.add(plugin.manifest.name);
+
+      const deps = this.registry.getDependencies(plugin.manifest.name);
+      for (const dep of deps) {
+        visit(dep);
+      }
+      result.push(plugin);
+    };
+
+    for (const plugin of plugins) {
+      visit(plugin);
+    }
+
+    return result;
+  }
+
+  private clearModuleCache(pluginPath: string): void {
+    // Clear all cached modules from this plugin
+    for (const key of Object.keys(require.cache)) {
+      if (key.startsWith(pluginPath)) {
+        delete require.cache[key];
+      }
+    }
+  }
+
+  onActivate(callback: Function): Disposable {
+    this.activateCallbacks.add(callback);
+    return { dispose: () => this.activateCallbacks.delete(callback) };
+  }
+
+  onDeactivate(callback: Function): Disposable {
+    this.deactivateCallbacks.add(callback);
+    return { dispose: () => this.deactivateCallbacks.delete(callback) };
+  }
+
+  onError(callback: Function): Disposable {
+    this.errorCallbacks.add(callback);
+    return { dispose: () => this.errorCallbacks.delete(callback) };
+  }
+}
+```
+
+---
+
+## 5. Hook System
+
+### Propósito
+Sistema de hooks para interceptar y extender funcionalidad del core.
+
+### Interfaz
+
+```typescript
+type HookCallback<T = unknown, R = T> = (
+  context: HookContext<T>,
+  next: () => Promise<R>
+) => Promise<R>;
+
+interface HookContext<T> {
+  data: T;
+  plugin?: string;
+  metadata: Record<string, unknown>;
+  abort(reason?: string): void;
+}
+
+interface HookSystem {
+  // Registration
+  register<T>(point: string, callback: HookCallback<T>, priority?: number): Disposable;
+  registerBefore<T>(point: string, callback: (data: T) => T | Promise<T>): Disposable;
+  registerAfter<T>(point: string, callback: (data: T, result: unknown) => void): Disposable;
+
+  // Execution
+  execute<T, R>(point: string, data: T): Promise<R>;
+  executeWaterfall<T>(point: string, data: T): Promise<T>;
+
+  // Queries
+  getHooks(point: string): Array<{ callback: HookCallback; priority: number; plugin?: string }>;
+  hasHooks(point: string): boolean;
+
+  // Built-in hook points
+  readonly POINTS: {
+    AGENT_BEFORE_RUN: 'agent:beforeRun';
+    AGENT_AFTER_RUN: 'agent:afterRun';
+    TOOL_BEFORE_EXECUTE: 'tool:beforeExecute';
+    TOOL_AFTER_EXECUTE: 'tool:afterExecute';
+    LLM_BEFORE_CALL: 'llm:beforeCall';
+    LLM_AFTER_CALL: 'llm:afterCall';
+    CONFIG_CHANGE: 'config:change';
+    PLUGIN_ACTIVATE: 'plugin:activate';
+    PLUGIN_DEACTIVATE: 'plugin:deactivate';
+  };
+}
+```
+
+### Implementación
+
+```typescript
+class HookSystemImpl implements HookSystem {
+  private hooks: Map<string, Array<{
+    callback: HookCallback;
+    priority: number;
+    plugin?: string;
+  }>> = new Map();
+
+  readonly POINTS = {
+    AGENT_BEFORE_RUN: 'agent:beforeRun',
+    AGENT_AFTER_RUN: 'agent:afterRun',
+    TOOL_BEFORE_EXECUTE: 'tool:beforeExecute',
+    TOOL_AFTER_EXECUTE: 'tool:afterExecute',
+    LLM_BEFORE_CALL: 'llm:beforeCall',
+    LLM_AFTER_CALL: 'llm:afterCall',
+    CONFIG_CHANGE: 'config:change',
+    PLUGIN_ACTIVATE: 'plugin:activate',
+    PLUGIN_DEACTIVATE: 'plugin:deactivate'
+  } as const;
+
+  register<T>(
+    point: string,
+    callback: HookCallback<T>,
+    priority: number = 100
+  ): Disposable {
+    if (!this.hooks.has(point)) {
+      this.hooks.set(point, []);
+    }
+
+    const hook = { callback, priority };
+    this.hooks.get(point)!.push(hook);
+    this.hooks.get(point)!.sort((a, b) => a.priority - b.priority);
+
+    return {
+      dispose: () => {
+        const hooks = this.hooks.get(point);
+        if (hooks) {
+          const index = hooks.indexOf(hook);
+          if (index > -1) hooks.splice(index, 1);
+        }
+      }
+    };
+  }
+
+  registerBefore<T>(point: string, callback: (data: T) => T | Promise<T>): Disposable {
+    return this.register<T>(point, async (ctx, next) => {
+      ctx.data = await callback(ctx.data);
+      return next();
+    }, 50);
+  }
+
+  registerAfter<T>(
+    point: string,
+    callback: (data: T, result: unknown) => void
+  ): Disposable {
+    return this.register<T>(point, async (ctx, next) => {
+      const result = await next();
+      callback(ctx.data, result);
+      return result;
+    }, 150);
+  }
+
+  async execute<T, R>(point: string, data: T): Promise<R> {
+    const hooks = this.hooks.get(point) || [];
+    let aborted = false;
+    let abortReason: string | undefined;
+
+    const context: HookContext<T> = {
+      data,
+      metadata: {},
+      abort: (reason) => {
+        aborted = true;
+        abortReason = reason;
+      }
+    };
+
+    // Build middleware chain
+    let index = -1;
+
+    const dispatch = async (i: number): Promise<R> => {
+      if (aborted) {
+        throw new HookAbortError(point, abortReason);
+      }
+
+      if (i <= index) {
+        throw new Error('next() called multiple times');
+      }
+      index = i;
+
+      if (i >= hooks.length) {
+        // End of chain - return data as result
+        return context.data as unknown as R;
+      }
+
+      const hook = hooks[i];
+      context.plugin = hook.plugin;
+
+      return hook.callback(context, () => dispatch(i + 1)) as Promise<R>;
+    };
+
+    return dispatch(0);
+  }
+
+  async executeWaterfall<T>(point: string, data: T): Promise<T> {
+    const hooks = this.hooks.get(point) || [];
+    let result = data;
+
+    for (const hook of hooks) {
+      const context: HookContext<T> = {
+        data: result,
+        plugin: hook.plugin,
+        metadata: {},
+        abort: () => {
+          throw new HookAbortError(point, 'Waterfall aborted');
+        }
+      };
+
+      result = await hook.callback(context, async () => context.data) as T;
+    }
+
+    return result;
+  }
+
+  getHooks(point: string) {
+    return this.hooks.get(point) || [];
+  }
+
+  hasHooks(point: string): boolean {
+    return (this.hooks.get(point)?.length || 0) > 0;
+  }
+}
+```
+
+### Uso de Hooks
+
+```typescript
+const hooks = new HookSystem();
+
+// Plugin registers a hook to modify agent prompts
+hooks.registerBefore<AgentRunContext>('agent:beforeRun', async (data) => {
+  // Add custom instructions to system prompt
+  data.systemPrompt += '\n\nAdditional instructions from plugin...';
+  return data;
+});
+
+// Plugin registers a hook to log all tool executions
+hooks.registerAfter<ToolExecuteContext>('tool:afterExecute', (data, result) => {
+  analytics.track('tool_executed', {
+    tool: data.toolName,
+    duration: result.duration,
+    success: !result.error
+  });
+});
+
+// Middleware-style hook
+hooks.register<LLMCallContext>('llm:beforeCall', async (ctx, next) => {
+  const start = Date.now();
+
+  try {
+    const result = await next();
+    metrics.recordLatency('llm_call', Date.now() - start);
+    return result;
+  } catch (error) {
+    metrics.increment('llm_errors');
+    throw error;
+  }
+}, 10); // High priority (runs early)
+```
+
+---
+
+## 6. Plugin Examples
+
+### Example: Git Integration Plugin
+
+```typescript
+// plugins/elsabro-git/plugin.json
+{
+  "name": "elsabro-git",
+  "version": "1.0.0",
+  "displayName": "Git Integration",
+  "description": "Git operations for ELSABRO agents",
+  "main": "dist/index.js",
+  "engines": { "elsabro": ">=3.0.0" },
+  "permissions": ["shell", "filesystem:read"],
+  "contributes": {
+    "tools": [
+      {
+        "name": "git-status",
+        "displayName": "Git Status",
+        "description": "Get the current git repository status",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "path": { "type": "string", "description": "Repository path" }
+          }
+        },
+        "handler": "tools/gitStatus"
+      },
+      {
+        "name": "git-commit",
+        "displayName": "Git Commit",
+        "description": "Create a git commit",
+        "inputSchema": {
+          "type": "object",
+          "required": ["message"],
+          "properties": {
+            "message": { "type": "string" },
+            "files": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "handler": "tools/gitCommit"
+      }
+    ],
+    "hooks": [
+      {
+        "point": "agent:afterRun",
+        "priority": 100,
+        "handler": "hooks/autoCommit"
+      }
+    ]
+  }
+}
+```
+
+```typescript
+// plugins/elsabro-git/src/index.ts
+import { Plugin, PluginContext } from '@elsabro/plugin-api';
+
+export default class GitPlugin implements Plugin {
+  private context!: PluginContext;
+
+  async activate(context: PluginContext): Promise<void> {
+    this.context = context;
+
+    context.logger.info('Git plugin activated');
+
+    // Check if git is available
+    try {
+      await this.runGitCommand(['--version']);
+    } catch (error) {
+      context.logger.warn('Git not found in PATH');
+    }
+  }
+
+  async deactivate(): Promise<void> {
+    this.context.logger.info('Git plugin deactivated');
+  }
+
+  private async runGitCommand(args: string[]): Promise<string> {
+    // Implementation
+  }
+}
+```
+
+### Example: Analytics Plugin
+
+```typescript
+// plugins/elsabro-analytics/plugin.json
+{
+  "name": "elsabro-analytics",
+  "version": "1.0.0",
+  "displayName": "Analytics",
+  "description": "Usage analytics and insights",
+  "main": "dist/index.js",
+  "engines": { "elsabro": ">=3.0.0" },
+  "permissions": ["network", "config:read"],
+  "contributes": {
+    "hooks": [
+      { "point": "agent:afterRun", "priority": 200, "handler": "hooks/trackAgentRun" },
+      { "point": "tool:afterExecute", "priority": 200, "handler": "hooks/trackToolUse" },
+      { "point": "llm:afterCall", "priority": 200, "handler": "hooks/trackLLMCall" }
+    ],
+    "commands": [
+      {
+        "command": "analytics.dashboard",
+        "title": "Show Analytics Dashboard",
+        "category": "Analytics"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 7. Plugin Security
+
+### Sandbox Aislado
+
+```typescript
+class PluginSandbox {
+  private vm: NodeVM;
+
+  constructor(plugin: LoadedPlugin, options: SandboxOptions) {
+    this.vm = new NodeVM({
+      timeout: options.timeout || 30000,
+      sandbox: {},
+      require: {
+        external: options.allowedModules || ['lodash', 'dayjs'],
+        builtin: this.getAllowedBuiltins(plugin.manifest.permissions),
+        root: plugin.path,
+        mock: this.createMocks(plugin.manifest.permissions)
+      }
+    });
+  }
+
+  private getAllowedBuiltins(permissions: PluginPermission[]): string[] {
+    const allowed = ['path', 'url', 'util', 'events'];
+
+    if (permissions.includes('filesystem:read')) {
+      allowed.push('fs/promises');
+    }
+    if (permissions.includes('network')) {
+      allowed.push('http', 'https');
+    }
+
+    return allowed;
+  }
+
+  private createMocks(permissions: PluginPermission[]): Record<string, unknown> {
+    const mocks: Record<string, unknown> = {};
+
+    // Mock dangerous modules
+    if (!permissions.includes('shell')) {
+      mocks['child_process'] = {
+        exec: () => { throw new Error('Permission denied: shell'); },
+        spawn: () => { throw new Error('Permission denied: shell'); }
+      };
+    }
+
+    return mocks;
+  }
+}
+```
+
+### Permission Enforcement
+
+```typescript
+class PermissionEnforcer {
+  constructor(private permissions: Set<PluginPermission>) {}
+
+  checkFileRead(path: string): void {
+    if (!this.permissions.has('filesystem:read')) {
+      throw new PermissionDeniedError('filesystem:read', path);
+    }
+  }
+
+  checkFileWrite(path: string): void {
+    if (!this.permissions.has('filesystem:write')) {
+      throw new PermissionDeniedError('filesystem:write', path);
+    }
+  }
+
+  checkNetwork(url: string): void {
+    if (!this.permissions.has('network')) {
+      throw new PermissionDeniedError('network', url);
+    }
+  }
+
+  checkSecrets(): void {
+    if (!this.permissions.has('secrets')) {
+      throw new PermissionDeniedError('secrets');
+    }
+  }
+}
+```
+
+---
+
+## 8. Plugin Dashboard
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        ELSABRO Plugin Manager                                │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  Installed: 5 plugins (4 active, 1 disabled)                                │
+│  Hot-reload: Enabled for development                                        │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                              Plugins                                         │
+├──────────────────────┬─────────┬────────────┬─────────────┬─────────────────┤
+│ Name                 │ Version │ Status     │ Permissions │ Memory          │
+├──────────────────────┼─────────┼────────────┼─────────────┼─────────────────┤
+│ elsabro-git          │ 1.2.0   │ ✓ Active   │ shell, fs   │ 12.3 MB         │
+│ elsabro-analytics    │ 2.0.1   │ ✓ Active   │ network     │  8.1 MB         │
+│ elsabro-jira         │ 1.0.0   │ ✓ Active   │ network     │ 15.2 MB         │
+│ elsabro-slack        │ 1.5.2   │ ✓ Active   │ network     │ 10.8 MB         │
+│ elsabro-debug        │ 0.9.0   │ ✗ Disabled │ shell, fs   │    - MB         │
+└──────────────────────┴─────────┴────────────┴─────────────┴─────────────────┘
+│                           Contributions                                      │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  Agents: 2 (git-reviewer, jira-assistant)                                   │
+│  Tools: 8 (git-status, git-commit, jira-create-issue, ...)                 │
+│  Commands: 5                                                                 │
+│  Hooks: 12 registered                                                        │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Referencias
+
+- **REF-001**: Architecture Guide
+- **REF-022**: Security System
+- **REF-023**: Configuration Management
+- **REF-024**: Esta referencia (Plugin System)