elsabro 2.3.0 → 3.7.0

package/references/tool-registry.md

@@ -0,0 +1,886 @@
+# Tool Registry System (v3.3)
+
+Sistema de registro dinámico de herramientas con discovery, versionado, y capability matching.
+
+## Arquitectura
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                       TOOL REGISTRY SYSTEM                               │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                    TOOL REGISTRY                                 │    │
+│  │  ┌─────────────────────────────────────────────────────────┐    │    │
+│  │  │                 Registered Tools                         │    │    │
+│  │  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │    │    │
+│  │  │  │  Bash   │  │  Read   │  │  Write  │  │   MCP   │    │    │    │
+│  │  │  │ v1.2.0  │  │ v1.0.0  │  │ v1.0.0  │  │ v2.0.0  │    │    │    │
+│  │  │  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │    │    │
+│  │  └─────────────────────────────────────────────────────────┘    │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                    │                                     │
+│                                    ▼                                     │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                    TOOL DISCOVERY                                │    │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │    │
+│  │  │  By Name    │  │ By Category │  │By Capability│              │    │
+│  │  │  "Bash"     │  │  "file-ops" │  │ "can:write" │              │    │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘              │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                    │                                     │
+│                                    ▼                                     │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                    CAPABILITY MATCHER                            │    │
+│  │  ┌───────────────────────────────────────────────────────────┐  │    │
+│  │  │  Agent Request         →        Matching Tools            │  │    │
+│  │  │  "Need to read files"  →  [Read, Glob, Grep, WebFetch]   │  │    │
+│  │  └───────────────────────────────────────────────────────────┘  │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                    │                                     │
+│                                    ▼                                     │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                    VERSION MANAGER                               │    │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │    │
+│  │  │ Versioning  │  │ Deprecation │  │  Migration  │              │    │
+│  │  │  semver     │  │  warnings   │  │   paths     │              │    │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘              │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## ToolRegistry
+
+### API Principal
+
+```typescript
+interface ToolDefinition {
+  name: string;
+  version: string;
+  description: string;
+  category: string;
+  capabilities: string[];
+  parameters: ToolParameter[];
+  returns: ToolReturn;
+  examples?: ToolExample[];
+  metadata?: Record<string, unknown>;
+}
+
+interface ToolParameter {
+  name: string;
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  description: string;
+  required: boolean;
+  default?: unknown;
+  enum?: unknown[];
+  schema?: JSONSchema;
+}
+
+interface ToolReturn {
+  type: string;
+  description: string;
+  schema?: JSONSchema;
+}
+
+interface ToolExample {
+  description: string;
+  input: Record<string, unknown>;
+  output: unknown;
+}
+
+interface RegisteredTool extends ToolDefinition {
+  id: string;
+  registered_at: string;
+  updated_at: string;
+  status: 'active' | 'deprecated' | 'disabled';
+  deprecation?: {
+    message: string;
+    replacement?: string;
+    remove_at?: string;
+  };
+  usage: {
+    total_calls: number;
+    success_rate: number;
+    avg_duration_ms: number;
+  };
+}
+
+class ToolRegistry {
+  private tools: Map<string, RegisteredTool>;
+  private categories: Map<string, Set<string>>;
+  private capabilities: Map<string, Set<string>>;
+  private config: ToolRegistryConfig;
+
+  constructor(config: ToolRegistryConfig) {
+    this.config = config;
+    this.tools = new Map();
+    this.categories = new Map();
+    this.capabilities = new Map();
+    this.loadBuiltinTools();
+  }
+
+  // Register new tool
+  register(definition: ToolDefinition): RegisteredTool {
+    const existing = this.tools.get(definition.name);
+
+    // Version conflict check
+    if (existing && !this.isNewerVersion(definition.version, existing.version)) {
+      throw new Error(
+        `Tool ${definition.name} v${existing.version} already registered. ` +
+        `Provided v${definition.version} is not newer.`
+      );
+    }
+
+    const tool: RegisteredTool = {
+      ...definition,
+      id: this.generateId(),
+      registered_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+      status: 'active',
+      usage: {
+        total_calls: existing?.usage.total_calls || 0,
+        success_rate: existing?.usage.success_rate || 100,
+        avg_duration_ms: existing?.usage.avg_duration_ms || 0
+      }
+    };
+
+    // Register tool
+    this.tools.set(definition.name, tool);
+
+    // Index by category
+    if (!this.categories.has(definition.category)) {
+      this.categories.set(definition.category, new Set());
+    }
+    this.categories.get(definition.category)!.add(definition.name);
+
+    // Index by capabilities
+    for (const capability of definition.capabilities) {
+      if (!this.capabilities.has(capability)) {
+        this.capabilities.set(capability, new Set());
+      }
+      this.capabilities.get(capability)!.add(definition.name);
+    }
+
+    // Emit event
+    EventBus.publish('tool.registered', {
+      name: definition.name,
+      version: definition.version,
+      category: definition.category
+    });
+
+    return tool;
+  }
+
+  // Get tool by name
+  get(name: string): RegisteredTool | undefined {
+    return this.tools.get(name);
+  }
+
+  // Get tool with version check
+  getVersion(name: string, version?: string): RegisteredTool | undefined {
+    const tool = this.tools.get(name);
+    if (!tool) return undefined;
+
+    if (version && !this.satisfiesVersion(tool.version, version)) {
+      return undefined;
+    }
+
+    return tool;
+  }
+
+  // List all tools
+  list(options?: ListOptions): RegisteredTool[] {
+    let tools = Array.from(this.tools.values());
+
+    if (options?.category) {
+      tools = tools.filter(t => t.category === options.category);
+    }
+
+    if (options?.status) {
+      tools = tools.filter(t => t.status === options.status);
+    }
+
+    if (options?.capability) {
+      const toolNames = this.capabilities.get(options.capability);
+      if (toolNames) {
+        tools = tools.filter(t => toolNames.has(t.name));
+      } else {
+        tools = [];
+      }
+    }
+
+    return tools;
+  }
+
+  // Search tools
+  search(query: string): RegisteredTool[] {
+    const lowerQuery = query.toLowerCase();
+
+    return Array.from(this.tools.values()).filter(tool =>
+      tool.name.toLowerCase().includes(lowerQuery) ||
+      tool.description.toLowerCase().includes(lowerQuery) ||
+      tool.capabilities.some(c => c.toLowerCase().includes(lowerQuery))
+    );
+  }
+
+  // Deprecate tool
+  deprecate(name: string, message: string, replacement?: string): void {
+    const tool = this.tools.get(name);
+    if (!tool) throw new Error(`Tool not found: ${name}`);
+
+    tool.status = 'deprecated';
+    tool.deprecation = {
+      message,
+      replacement,
+      remove_at: this.calculateRemovalDate()
+    };
+    tool.updated_at = new Date().toISOString();
+
+    EventBus.publish('tool.deprecated', {
+      name,
+      message,
+      replacement
+    });
+  }
+
+  // Disable tool
+  disable(name: string): void {
+    const tool = this.tools.get(name);
+    if (!tool) throw new Error(`Tool not found: ${name}`);
+
+    tool.status = 'disabled';
+    tool.updated_at = new Date().toISOString();
+
+    EventBus.publish('tool.disabled', { name });
+  }
+
+  // Enable tool
+  enable(name: string): void {
+    const tool = this.tools.get(name);
+    if (!tool) throw new Error(`Tool not found: ${name}`);
+
+    tool.status = 'active';
+    tool.deprecation = undefined;
+    tool.updated_at = new Date().toISOString();
+
+    EventBus.publish('tool.enabled', { name });
+  }
+
+  // Unregister tool
+  unregister(name: string): boolean {
+    const tool = this.tools.get(name);
+    if (!tool) return false;
+
+    // Remove from indices
+    this.categories.get(tool.category)?.delete(name);
+    for (const capability of tool.capabilities) {
+      this.capabilities.get(capability)?.delete(name);
+    }
+
+    this.tools.delete(name);
+
+    EventBus.publish('tool.unregistered', { name });
+
+    return true;
+  }
+
+  // Record tool usage
+  recordUsage(name: string, success: boolean, duration_ms: number): void {
+    const tool = this.tools.get(name);
+    if (!tool) return;
+
+    tool.usage.total_calls++;
+
+    // Update success rate (rolling average)
+    const successValue = success ? 100 : 0;
+    tool.usage.success_rate =
+      (tool.usage.success_rate * (tool.usage.total_calls - 1) + successValue) /
+      tool.usage.total_calls;
+
+    // Update average duration (rolling average)
+    tool.usage.avg_duration_ms =
+      (tool.usage.avg_duration_ms * (tool.usage.total_calls - 1) + duration_ms) /
+      tool.usage.total_calls;
+  }
+
+  // Get categories
+  getCategories(): string[] {
+    return Array.from(this.categories.keys());
+  }
+
+  // Get capabilities
+  getCapabilities(): string[] {
+    return Array.from(this.capabilities.keys());
+  }
+
+  // Export registry
+  export(): ToolRegistryExport {
+    return {
+      version: '1.0.0',
+      exported_at: new Date().toISOString(),
+      tools: Array.from(this.tools.values())
+    };
+  }
+
+  // Import registry
+  import(data: ToolRegistryExport): number {
+    let imported = 0;
+    for (const tool of data.tools) {
+      try {
+        this.register(tool);
+        imported++;
+      } catch {
+        // Skip conflicts
+      }
+    }
+    return imported;
+  }
+
+  private loadBuiltinTools(): void {
+    // Register Claude Code built-in tools
+    const builtins: ToolDefinition[] = [
+      {
+        name: 'Bash',
+        version: '1.0.0',
+        description: 'Execute bash commands',
+        category: 'system',
+        capabilities: ['execute', 'shell', 'git', 'npm'],
+        parameters: [
+          { name: 'command', type: 'string', description: 'Command to execute', required: true },
+          { name: 'timeout', type: 'number', description: 'Timeout in ms', required: false }
+        ],
+        returns: { type: 'string', description: 'Command output' }
+      },
+      {
+        name: 'Read',
+        version: '1.0.0',
+        description: 'Read file contents',
+        category: 'file-ops',
+        capabilities: ['read', 'file', 'content'],
+        parameters: [
+          { name: 'file_path', type: 'string', description: 'Path to file', required: true },
+          { name: 'offset', type: 'number', description: 'Start line', required: false },
+          { name: 'limit', type: 'number', description: 'Max lines', required: false }
+        ],
+        returns: { type: 'string', description: 'File content' }
+      },
+      {
+        name: 'Write',
+        version: '1.0.0',
+        description: 'Write file contents',
+        category: 'file-ops',
+        capabilities: ['write', 'file', 'create'],
+        parameters: [
+          { name: 'file_path', type: 'string', description: 'Path to file', required: true },
+          { name: 'content', type: 'string', description: 'Content to write', required: true }
+        ],
+        returns: { type: 'boolean', description: 'Success status' }
+      },
+      {
+        name: 'Edit',
+        version: '1.0.0',
+        description: 'Edit file with replacements',
+        category: 'file-ops',
+        capabilities: ['edit', 'file', 'modify'],
+        parameters: [
+          { name: 'file_path', type: 'string', description: 'Path to file', required: true },
+          { name: 'old_string', type: 'string', description: 'Text to replace', required: true },
+          { name: 'new_string', type: 'string', description: 'Replacement text', required: true }
+        ],
+        returns: { type: 'boolean', description: 'Success status' }
+      },
+      {
+        name: 'Glob',
+        version: '1.0.0',
+        description: 'Find files by pattern',
+        category: 'search',
+        capabilities: ['search', 'find', 'pattern'],
+        parameters: [
+          { name: 'pattern', type: 'string', description: 'Glob pattern', required: true },
+          { name: 'path', type: 'string', description: 'Base path', required: false }
+        ],
+        returns: { type: 'array', description: 'Matching file paths' }
+      },
+      {
+        name: 'Grep',
+        version: '1.0.0',
+        description: 'Search file contents',
+        category: 'search',
+        capabilities: ['search', 'content', 'regex'],
+        parameters: [
+          { name: 'pattern', type: 'string', description: 'Search pattern', required: true },
+          { name: 'path', type: 'string', description: 'Search path', required: false }
+        ],
+        returns: { type: 'array', description: 'Matching lines' }
+      },
+      {
+        name: 'Task',
+        version: '1.0.0',
+        description: 'Launch subagent for complex tasks',
+        category: 'agent',
+        capabilities: ['delegate', 'parallel', 'subagent'],
+        parameters: [
+          { name: 'prompt', type: 'string', description: 'Task description', required: true },
+          { name: 'subagent_type', type: 'string', description: 'Agent type', required: true }
+        ],
+        returns: { type: 'object', description: 'Agent result' }
+      },
+      {
+        name: 'WebFetch',
+        version: '1.0.0',
+        description: 'Fetch and process web content',
+        category: 'web',
+        capabilities: ['fetch', 'http', 'web'],
+        parameters: [
+          { name: 'url', type: 'string', description: 'URL to fetch', required: true },
+          { name: 'prompt', type: 'string', description: 'Processing prompt', required: true }
+        ],
+        returns: { type: 'string', description: 'Processed content' }
+      },
+      {
+        name: 'WebSearch',
+        version: '1.0.0',
+        description: 'Search the web',
+        category: 'web',
+        capabilities: ['search', 'web', 'query'],
+        parameters: [
+          { name: 'query', type: 'string', description: 'Search query', required: true }
+        ],
+        returns: { type: 'array', description: 'Search results' }
+      }
+    ];
+
+    for (const tool of builtins) {
+      this.register(tool);
+    }
+  }
+
+  private isNewerVersion(newVersion: string, oldVersion: string): boolean {
+    const parse = (v: string) => v.split('.').map(Number);
+    const [newMajor, newMinor, newPatch] = parse(newVersion);
+    const [oldMajor, oldMinor, oldPatch] = parse(oldVersion);
+
+    if (newMajor > oldMajor) return true;
+    if (newMajor < oldMajor) return false;
+    if (newMinor > oldMinor) return true;
+    if (newMinor < oldMinor) return false;
+    return newPatch > oldPatch;
+  }
+
+  private satisfiesVersion(actual: string, required: string): boolean {
+    // Simple semver satisfaction check
+    if (required.startsWith('^')) {
+      const base = required.slice(1);
+      const [reqMajor] = base.split('.').map(Number);
+      const [actMajor] = actual.split('.').map(Number);
+      return actMajor === reqMajor && this.isNewerVersion(actual, base);
+    }
+    if (required.startsWith('~')) {
+      const base = required.slice(1);
+      const [reqMajor, reqMinor] = base.split('.').map(Number);
+      const [actMajor, actMinor] = actual.split('.').map(Number);
+      return actMajor === reqMajor && actMinor === reqMinor;
+    }
+    return actual === required;
+  }
+
+  private calculateRemovalDate(): string {
+    const date = new Date();
+    date.setMonth(date.getMonth() + 3);
+    return date.toISOString();
+  }
+
+  private generateId(): string {
+    return `tool_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  }
+}
+```
+
+---
+
+## ToolDiscovery
+
+```typescript
+interface DiscoveryQuery {
+  text?: string;
+  capabilities?: string[];
+  category?: string;
+  minVersion?: string;
+  includeDeprecated?: boolean;
+}
+
+interface DiscoveryResult {
+  tool: RegisteredTool;
+  score: number;
+  matchedCapabilities: string[];
+  matchReason: string;
+}
+
+class ToolDiscovery {
+  private registry: ToolRegistry;
+  private cache: Map<string, DiscoveryResult[]>;
+
+  constructor(registry: ToolRegistry) {
+    this.registry = registry;
+    this.cache = new Map();
+  }
+
+  // Discover tools matching query
+  discover(query: DiscoveryQuery): DiscoveryResult[] {
+    const cacheKey = JSON.stringify(query);
+    if (this.cache.has(cacheKey)) {
+      return this.cache.get(cacheKey)!;
+    }
+
+    let candidates = this.registry.list({
+      status: query.includeDeprecated ? undefined : 'active'
+    });
+
+    const results: DiscoveryResult[] = [];
+
+    for (const tool of candidates) {
+      const score = this.calculateScore(tool, query);
+      if (score > 0) {
+        results.push({
+          tool,
+          score,
+          matchedCapabilities: this.getMatchedCapabilities(tool, query),
+          matchReason: this.getMatchReason(tool, query, score)
+        });
+      }
+    }
+
+    // Sort by score descending
+    results.sort((a, b) => b.score - a.score);
+
+    // Cache results
+    this.cache.set(cacheKey, results);
+
+    return results;
+  }
+
+  // Find best tool for capability
+  findBest(capability: string): RegisteredTool | undefined {
+    const results = this.discover({ capabilities: [capability] });
+    return results[0]?.tool;
+  }
+
+  // Find all tools for category
+  findByCategory(category: string): RegisteredTool[] {
+    return this.registry.list({ category });
+  }
+
+  // Suggest tools for task description
+  suggest(taskDescription: string): DiscoveryResult[] {
+    // Extract likely capabilities from description
+    const capabilities = this.extractCapabilities(taskDescription);
+
+    return this.discover({
+      text: taskDescription,
+      capabilities
+    });
+  }
+
+  // Clear discovery cache
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  private calculateScore(tool: RegisteredTool, query: DiscoveryQuery): number {
+    let score = 0;
+
+    // Text match
+    if (query.text) {
+      const text = query.text.toLowerCase();
+      if (tool.name.toLowerCase().includes(text)) score += 50;
+      if (tool.description.toLowerCase().includes(text)) score += 30;
+    }
+
+    // Capability match
+    if (query.capabilities) {
+      for (const cap of query.capabilities) {
+        if (tool.capabilities.includes(cap)) score += 25;
+      }
+    }
+
+    // Category match
+    if (query.category && tool.category === query.category) {
+      score += 20;
+    }
+
+    // Version match
+    if (query.minVersion) {
+      if (this.satisfiesMinVersion(tool.version, query.minVersion)) {
+        score += 10;
+      } else {
+        score = 0; // Exclude if version doesn't satisfy
+      }
+    }
+
+    // Usage bonus (more used = more trusted)
+    if (tool.usage.total_calls > 100) score += 5;
+    if (tool.usage.success_rate > 95) score += 5;
+
+    // Penalty for deprecated
+    if (tool.status === 'deprecated') score -= 20;
+
+    return Math.max(0, score);
+  }
+
+  private getMatchedCapabilities(tool: RegisteredTool, query: DiscoveryQuery): string[] {
+    if (!query.capabilities) return [];
+    return query.capabilities.filter(c => tool.capabilities.includes(c));
+  }
+
+  private getMatchReason(tool: RegisteredTool, query: DiscoveryQuery, score: number): string {
+    const reasons: string[] = [];
+
+    if (query.text && tool.name.toLowerCase().includes(query.text.toLowerCase())) {
+      reasons.push('name match');
+    }
+
+    if (query.capabilities) {
+      const matched = this.getMatchedCapabilities(tool, query);
+      if (matched.length > 0) {
+        reasons.push(`capabilities: ${matched.join(', ')}`);
+      }
+    }
+
+    if (query.category && tool.category === query.category) {
+      reasons.push('category match');
+    }
+
+    return reasons.join('; ') || 'general match';
+  }
+
+  private extractCapabilities(description: string): string[] {
+    const keywords: Record<string, string[]> = {
+      'read': ['read', 'file', 'content'],
+      'write': ['write', 'create', 'save'],
+      'edit': ['edit', 'modify', 'change', 'update'],
+      'search': ['search', 'find', 'look', 'grep'],
+      'execute': ['run', 'execute', 'command', 'bash', 'shell'],
+      'fetch': ['fetch', 'download', 'http', 'api', 'web'],
+      'delegate': ['agent', 'task', 'parallel', 'complex']
+    };
+
+    const lower = description.toLowerCase();
+    const capabilities: string[] = [];
+
+    for (const [capability, triggers] of Object.entries(keywords)) {
+      if (triggers.some(t => lower.includes(t))) {
+        capabilities.push(capability);
+      }
+    }
+
+    return capabilities;
+  }
+
+  private satisfiesMinVersion(actual: string, min: string): boolean {
+    const parse = (v: string) => v.split('.').map(Number);
+    const [actMajor, actMinor, actPatch] = parse(actual);
+    const [minMajor, minMinor, minPatch] = parse(min);
+
+    if (actMajor > minMajor) return true;
+    if (actMajor < minMajor) return false;
+    if (actMinor > minMinor) return true;
+    if (actMinor < minMinor) return false;
+    return actPatch >= minPatch;
+  }
+}
+```
+
+---
+
+## CapabilityMatcher
+
+```typescript
+interface CapabilityRequirement {
+  capability: string;
+  required: boolean;
+  priority: number;
+}
+
+interface MatchResult {
+  tool: RegisteredTool;
+  matchedCapabilities: string[];
+  missingCapabilities: string[];
+  matchPercentage: number;
+}
+
+class CapabilityMatcher {
+  private registry: ToolRegistry;
+
+  constructor(registry: ToolRegistry) {
+    this.registry = registry;
+  }
+
+  // Match tools to required capabilities
+  match(requirements: CapabilityRequirement[]): MatchResult[] {
+    const tools = this.registry.list({ status: 'active' });
+    const results: MatchResult[] = [];
+
+    for (const tool of tools) {
+      const matched: string[] = [];
+      const missing: string[] = [];
+
+      for (const req of requirements) {
+        if (tool.capabilities.includes(req.capability)) {
+          matched.push(req.capability);
+        } else if (req.required) {
+          missing.push(req.capability);
+        }
+      }
+
+      // Skip if missing required capabilities
+      if (missing.length > 0 && requirements.some(r => r.required && missing.includes(r.capability))) {
+        continue;
+      }
+
+      const matchPercentage = (matched.length / requirements.length) * 100;
+
+      results.push({
+        tool,
+        matchedCapabilities: matched,
+        missingCapabilities: missing,
+        matchPercentage
+      });
+    }
+
+    // Sort by match percentage
+    return results.sort((a, b) => b.matchPercentage - a.matchPercentage);
+  }
+
+  // Find minimum set of tools covering all capabilities
+  findMinimalSet(capabilities: string[]): RegisteredTool[] {
+    const uncovered = new Set(capabilities);
+    const selected: RegisteredTool[] = [];
+
+    while (uncovered.size > 0) {
+      // Find tool that covers most uncovered capabilities
+      let best: RegisteredTool | undefined;
+      let bestCoverage = 0;
+
+      for (const tool of this.registry.list({ status: 'active' })) {
+        const coverage = tool.capabilities.filter(c => uncovered.has(c)).length;
+        if (coverage > bestCoverage) {
+          best = tool;
+          bestCoverage = coverage;
+        }
+      }
+
+      if (!best || bestCoverage === 0) break;
+
+      selected.push(best);
+      for (const cap of best.capabilities) {
+        uncovered.delete(cap);
+      }
+    }
+
+    return selected;
+  }
+
+  // Check if capabilities are satisfiable
+  canSatisfy(capabilities: string[]): boolean {
+    const available = new Set(this.registry.getCapabilities());
+    return capabilities.every(c => available.has(c));
+  }
+
+  // Get missing capabilities
+  getMissing(capabilities: string[]): string[] {
+    const available = new Set(this.registry.getCapabilities());
+    return capabilities.filter(c => !available.has(c));
+  }
+}
+```
+
+---
+
+## Integración con Agentes
+
+```typescript
+// Uso en agentes
+class SmartAgent {
+  private discovery: ToolDiscovery;
+
+  async selectTools(taskDescription: string): Promise<RegisteredTool[]> {
+    // Discover relevant tools
+    const results = this.discovery.suggest(taskDescription);
+
+    // Filter to top matches
+    const topTools = results
+      .filter(r => r.score > 30)
+      .slice(0, 5)
+      .map(r => r.tool);
+
+    return topTools;
+  }
+
+  async execute(task: Task): Promise<Result> {
+    // Get available tools for this task
+    const tools = await this.selectTools(task.description);
+
+    // Build tool context for prompt
+    const toolContext = tools.map(t => ({
+      name: t.name,
+      description: t.description,
+      parameters: t.parameters
+    }));
+
+    // Execute with selected tools
+    return this.runWithTools(task, toolContext);
+  }
+}
+```
+
+---
+
+## Comandos
+
+```bash
+/elsabro:tools                    # Listar todas las herramientas
+/elsabro:tools search "file"      # Buscar herramientas
+/elsabro:tools info Bash          # Ver detalles de herramienta
+/elsabro:tools stats              # Ver estadísticas de uso
+/elsabro:tools register ./tool.json  # Registrar nueva herramienta
+/elsabro:tools deprecate OldTool  # Marcar como deprecated
+```
+
+---
+
+## Configuración
+
+```json
+{
+  "toolRegistry": {
+    "enabled": true,
+    "autoLoadBuiltins": true,
+    "customToolsPath": ".elsabro/tools",
+    "caching": {
+      "enabled": true,
+      "ttl": 300000
+    },
+    "validation": {
+      "strictSchema": true,
+      "requireExamples": false
+    },
+    "deprecation": {
+      "warningPeriod": "30d",
+      "removalPeriod": "90d"
+    }
+  }
+}
+```
+
+---
+
+## Changelog
+
+- **v3.3.0**: Initial Tool Registry System
+  - ToolRegistry with registration/versioning
+  - ToolDiscovery for smart tool finding
+  - CapabilityMatcher for requirements matching
+  - Built-in tool definitions