Tool Registry

// types/tool-registry.ts
interface RegisteredTool {
  id: string
  name: string
  version: string
  category: ToolCategory
  
  // Metadata
  description: string
  longDescription?: string
  examples?: ToolExample[]
  
  // Schema
  parameters: ZodSchema
  returnType: ZodSchema
  
  // Permissions
  requiredPermissions: string[]
  requiresApproval: boolean
  riskLevel: "low" | "medium" | "high" | "critical"
  
  // Configuration
  timeout: number
  retryPolicy?: RetryPolicy
  rateLimits?: RateLimits
  
  // Tracking
  createdAt: Date
  updatedAt: Date
  createdBy: string
  usageCount: number
  errorRate: number
  avgDuration: number
}

type ToolCategory =
  | "communication"    // Email, SMS, notifications
  | "payments"         // Invoices, refunds, subscriptions
  | "social"           // Social media posting
  | "database"         // Data operations
  | "documents"        // PDF, contracts, reports
  | "integrations"     // Third-party APIs
  | "calculations"     // Business logic
  | "validation"       // Checks and verification
  | "internal"         // System operations

// lib/tools/registry.ts
import { ToolRegistry } from "@/lib/registry"
import { sendEmailTool } from "./communication/email"
import { calculateRentTool } from "./custom/rent-calculator"
import { screenTenantTool } from "./custom/tenant-screening"

const registry = new ToolRegistry()

// Register a tool with full metadata
registry.register({
  tool: sendEmailTool,
  metadata: {
    name: "sendEmail",
    version: "2.1.0",
    category: "communication",
    description: "Send transactional or marketing emails",
    longDescription: `
      Send emails using React Email templates with support for:
      - Multiple recipients
      - HTML and plain text
      - Attachments
      - Delivery tracking
    `,
    examples: [
      {
        description: "Send rent reminder",
        input: {
          to: ["tenant@example.com"],
          subject: "Rent Reminder",
          template: "rent_reminder",
          data: { amount: 2500, dueDate: "Feb 1" }
        }
      }
    ],
    requiredPermissions: ["email:send"],
    requiresApproval: false,
    riskLevel: "low",
    timeout: 10000,
    rateLimits: {
      perMinute: 60,
      perHour: 500,
      perDay: 2000,
    }
  }
})

// Batch register multiple tools
registry.registerBatch([
  { tool: calculateRentTool, metadata: { ... } },
  { tool: screenTenantTool, metadata: { ... } },
  { tool: createInvoiceTool, metadata: { ... } },
])

export { registry }

// Query tools from the registry
import { registry } from "@/lib/tools/registry"

// Get a specific tool by name
const emailTool = registry.get("sendEmail")

// Find tools by category
const communicationTools = registry.findByCategory("communication")
// Returns: [sendEmail, sendSms, sendPushNotification, ...]

// Search tools by capability
const paymentTools = registry.search({
  query: "invoice",
  categories: ["payments"],
  riskLevel: ["low", "medium"],
})

// Get tools for an agent based on permissions
const agentTools = registry.getToolsForAgent({
  agentId: "maintenance-coordinator",
  permissions: ["email:send", "issues:create", "database:read"],
})

// Get tool statistics
const stats = registry.getStats("sendEmail")
// {
//   usageCount: 15420,
//   errorRate: 0.02,
//   avgDuration: 234,
//   lastUsed: "2024-01-15T10:30:00Z",
//   topAgents: ["communications-agent", "tenant-support"]
// }

// Versioning and upgrades
import { registry } from "@/lib/tools/registry"

// Register a new version
registry.registerVersion({
  name: "sendEmail",
  version: "2.2.0",
  tool: sendEmailToolV2,
  changelog: "Added attachment support and delivery tracking",
  breaking: false,
})

// Get specific version
const v2Tool = registry.get("sendEmail", "2.0.0")

// List all versions
const versions = registry.getVersions("sendEmail")
// ["1.0.0", "1.1.0", "2.0.0", "2.1.0", "2.2.0"]

// Deprecate old version
registry.deprecate("sendEmail", "1.0.0", {
  reason: "Security vulnerability fixed in 1.1.0",
  sunset: new Date("2024-03-01"),
  migration: "Upgrade to 2.x for new features",
})

// Set default version for new agents
registry.setDefault("sendEmail", "2.2.0")

// Tool permissions and access control
import { registry } from "@/lib/tools/registry"

// Define permission groups
const permissionGroups = {
  "basic": [
    "email:send",
    "database:read",
    "notifications:create",
  ],
  "financial": [
    "payments:read",
    "invoices:create",
    "refunds:create",
  ],
  "admin": [
    "users:manage",
    "agents:configure",
    "tools:register",
  ],
}

// Check if agent can use tool
const canUse = registry.checkPermission({
  agentId: "maintenance-coordinator",
  toolName: "createRefund",
})
// { allowed: false, missing: ["refunds:create"] }

// Grant permissions to agent
await registry.grantPermissions({
  agentId: "financial-agent",
  permissions: permissionGroups.financial,
  grantedBy: "admin-user",
  expiresAt: null, // Permanent
})

// Audit permission usage
const audit = await registry.auditPermissions({
  agentId: "financial-agent",
  startDate: new Date("2024-01-01"),
  endDate: new Date("2024-01-31"),
})
// Returns detailed log of all tool invocations

// Tool monitoring and analytics
import { registry } from "@/lib/tools/registry"

// Get real-time metrics
const metrics = await registry.getMetrics({
  tools: ["sendEmail", "createInvoice"],
  period: "24h",
})
// {
//   sendEmail: {
//     invocations: 1234,
//     successRate: 0.98,
//     avgDuration: 245,
//     p95Duration: 450,
//     errors: [{ type: "rate_limit", count: 12 }]
//   },
//   ...
// }

// Set up alerts
registry.createAlert({
  name: "High Error Rate",
  condition: {
    metric: "errorRate",
    operator: ">",
    threshold: 0.05,
    duration: "5m",
  },
  actions: [
    { type: "slack", channel: "#alerts" },
    { type: "email", to: ["ops@company.com"] },
  ],
})

// Get usage trends
const trends = await registry.getTrends({
  tool: "sendEmail",
  metric: "invocations",
  period: "30d",
  groupBy: "day",
})