agents-library 1.1.0

package/dist/base-bot.d.ts

@@ -0,0 +1,282 @@
+/**
+ * Base Bot Abstract Class for Platform-Agnostic Bot Logic
+ * ========================================================
+ *
+ * Provides shared functionality for all platform-specific bots (Slack, Discord, etc.)
+ * Eliminates code duplication by consolidating common patterns:
+ * - Circuit breaker pattern for fault tolerance
+ * - Exponential backoff retry logic
+ * - Metrics tracking and monitoring
+ * - Tool invocation with resilience
+ *
+ * This is an abstract class - cannot be instantiated directly.
+ * Platform-specific bots must extend this and implement abstract methods.
+ *
+ * @example
+ * ```typescript
+ * export class SlackBot extends BaseBot {
+ *   async handleMention(event: SlackMentionEvent): Promise<void> {
+ *     // Slack-specific mention handling
+ *   }
+ *
+ *   async start(): Promise<void> {
+ *     await super.initializeAbilityResponseSubscription();
+ *     await this.subscribeToMentions();
+ *   }
+ *
+ *   stop(): void {
+ *     // Cleanup logic
+ *   }
+ * }
+ * ```
+ */
+import Anthropic from '@anthropic-ai/sdk';
+import type { KadiClient } from '@kadi.build/core';
+import type { ProviderManager } from './providers/provider-manager.js';
+import type { MemoryService } from './memory/memory-service.js';
+/**
+ * Base configuration required by all bots
+ */
+export interface BaseBotConfig {
+    /** KĀDI client instance for event subscription and tool invocation */
+    client: KadiClient;
+    /** Anthropic API key for Claude integration */
+    anthropicApiKey: string;
+    /** Bot user ID for topic routing (platform-specific format) */
+    botUserId: string;
+    /** Optional provider manager for LLM operations (shared service) */
+    providerManager?: ProviderManager;
+    /** Optional memory service for conversation context (shared service) */
+    memoryService?: MemoryService;
+}
+/**
+ * Abstract base class for platform-agnostic bot logic
+ *
+ * Provides common functionality shared across all platform bots:
+ * - Circuit breaker for fault tolerance
+ * - Retry logic with exponential backoff
+ * - Metrics tracking
+ * - Tool invocation helpers
+ *
+ * Platform-specific bots (SlackBot, DiscordBot) extend this class
+ * and implement the abstract methods.
+ */
+export declare abstract class BaseBot {
+    /** KĀDI client for broker communication */
+    protected client: KadiClient;
+    /** Anthropic API client for Claude integration */
+    protected anthropic: Anthropic;
+    /** Bot user ID for topic routing */
+    protected botUserId: string;
+    /** Optional provider manager for LLM operations */
+    protected providerManager?: ProviderManager;
+    /** Optional memory service for conversation context */
+    protected memoryService?: MemoryService;
+    /** Pending async tool responses (requestId -> Promise resolver) */
+    private pendingResponses;
+    /** Number of consecutive failures */
+    private failureCount;
+    /** Timestamp of last failure (for reset timeout) */
+    private lastFailureTime;
+    /** Maximum failures before circuit opens */
+    private readonly maxFailures;
+    /** Time in ms before circuit breaker resets */
+    private readonly resetTimeMs;
+    /** Whether circuit breaker is open (blocking requests) */
+    private isCircuitOpen;
+    /** Maximum retry attempts for failed operations */
+    private readonly maxRetries;
+    /** Base delay in ms for exponential backoff (1s, 2s, 4s) */
+    private readonly baseDelayMs;
+    /** Total number of requests processed */
+    private totalRequests;
+    /** Number of requests that timed out */
+    private timeoutCount;
+    /** Number of successful requests */
+    private successCount;
+    /**
+     * Create a new BaseBot instance
+     *
+     * @param config - Base bot configuration with client, API key, and bot ID
+     */
+    constructor(config: BaseBotConfig);
+    /**
+     * Handle platform-specific mention event
+     *
+     * Subclasses must implement this to process @mentions for their platform.
+     *
+     * @param event - Platform-specific mention event (e.g., SlackMentionEvent, DiscordMentionEvent)
+     */
+    protected abstract handleMention(event: any): Promise<void>;
+    /**
+     * Start the bot and begin processing events
+     *
+     * Subclasses must implement this to:
+     * 1. Call initializeAbilityResponseSubscription()
+     * 2. Subscribe to platform-specific events
+     */
+    abstract start(): Promise<void>;
+    /**
+     * Stop the bot and cleanup resources
+     *
+     * Subclasses must implement this to unsubscribe from events
+     * and perform any platform-specific cleanup.
+     */
+    abstract stop(): void;
+    /**
+     * Initialize ability response subscription
+     *
+     * Must be called by subclasses in their start() method
+     * before attempting to invoke tools or subscribe to events.
+     *
+     * Subscribes to async ability responses from kadi-broker.
+     */
+    protected initializeAbilityResponseSubscription(): Promise<void>;
+    /**
+     * Subscribe to kadi.ability.response notifications
+     *
+     * Handles async tool results from broker. When a tool returns {status: "pending"},
+     * the actual result arrives later as a kadi.ability.response notification.
+     *
+     * @private
+     */
+    private subscribeToAbilityResponses;
+    /**
+     * Wait for async ability response from kadi-broker
+     *
+     * When a tool returns {status: "pending", requestId: "..."}, this method
+     * waits for the actual result to arrive via kadi.ability.response notification.
+     *
+     * @param requestId - Request ID from pending status response
+     * @param timeout - Timeout in milliseconds (default: 30000)
+     * @returns Promise that resolves with the actual tool result
+     * @throws Error if timeout expires before result arrives
+     *
+     * @example
+     * ```typescript
+     * const result = await this.protocol.invokeTool({...});
+     * if (result?.status === 'pending') {
+     *   const actualResult = await this.waitForAbilityResponse(result.requestId);
+     *   return actualResult;
+     * }
+     * ```
+     */
+    protected waitForAbilityResponse(requestId: string, timeout?: number): Promise<any>;
+    /**
+     * Sleep for specified milliseconds
+     *
+     * Used for exponential backoff delays in retry logic.
+     *
+     * @param ms - Milliseconds to sleep
+     */
+    protected sleep(ms: number): Promise<void>;
+    /**
+     * Check circuit breaker state and reset if needed
+     *
+     * Returns true if circuit is open (blocking requests).
+     * Automatically resets circuit after resetTimeMs has elapsed.
+     *
+     * @returns true if circuit is open, false if closed
+     *
+     * @example
+     * ```typescript
+     * if (this.checkCircuitBreaker()) {
+     *   console.log('Circuit open - skipping request');
+     *   return;
+     * }
+     * ```
+     */
+    protected checkCircuitBreaker(): boolean;
+    /**
+     * Record failure and update circuit breaker state
+     *
+     * Increments failure count and opens circuit if maxFailures threshold reached.
+     * Logs metrics every 10 requests.
+     *
+     * @param _error - Error object (for potential future use)
+     */
+    protected recordFailure(_error: any): void;
+    /**
+     * Record success and reset failure counter
+     *
+     * Resets consecutive failure count when a request succeeds.
+     * Increments success metrics.
+     */
+    protected recordSuccess(): void;
+    /**
+     * Reset circuit breaker state
+     *
+     * Manually resets circuit breaker and clears failure count.
+     * Use with caution - typically circuit should auto-reset.
+     */
+    protected resetCircuitBreaker(): void;
+    /**
+     * Invoke KĀDI tool with retry logic and exponential backoff
+     *
+     * Automatically retries failed tool invocations with exponential backoff:
+     * - Attempt 1: Immediate
+     * - Attempt 2: 1s delay
+     * - Attempt 3: 2s delay
+     * - Attempt 4: 4s delay
+     *
+     * Only retries on timeout or network errors. Other errors fail immediately.
+     *
+     * @param params - Tool invocation parameters
+     * @param params.targetAgent - Target agent ID (e.g., 'mcp-server-slack')
+     * @param params.toolName - Tool name to invoke (e.g., 'send_slack_message')
+     * @param params.toolInput - Tool input parameters
+     * @param params.timeout - Timeout in milliseconds
+     * @param retryCount - Current retry attempt (internal, do not set)
+     * @returns Tool invocation result
+     * @throws Error if all retries exhausted
+     *
+     * @example
+     * ```typescript
+     * await this.invokeToolWithRetry({
+     *   targetAgent: 'mcp-server-slack',
+     *   toolName: 'send_slack_message',
+     *   toolInput: { channel: 'C123', text: 'Hello' },
+     *   timeout: 10000
+     * });
+     * ```
+     */
+    protected invokeToolWithRetry(params: {
+        targetAgent: string;
+        toolName: string;
+        toolInput: any;
+        timeout: number;
+    }, retryCount?: number): Promise<any>;
+    /**
+     * Get current bot metrics
+     *
+     * Returns metrics for monitoring and debugging:
+     * - Total requests processed
+     * - Success count and rate
+     * - Timeout count and rate
+     * - Circuit breaker state
+     *
+     * @returns Metrics object
+     *
+     * @example
+     * ```typescript
+     * const metrics = this.getMetrics();
+     * console.log(`Success rate: ${metrics.successRate}%`);
+     * ```
+     */
+    protected getMetrics(): {
+        totalRequests: number;
+        successCount: number;
+        timeoutCount: number;
+        successRate: number;
+        timeoutRate: number;
+        isCircuitOpen: boolean;
+    };
+    /**
+     * Log timeout and success metrics
+     *
+     * Logs formatted metrics to console for monitoring.
+     * Called automatically every 10 requests or can be called manually.
+     */
+    protected logMetrics(): void;
+}
+//# sourceMappingURL=base-bot.d.ts.map

package/dist/base-bot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-bot.d.ts","sourceRoot":"","sources":["../src/base-bot.ts"],"names":[],"mappings":"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"}

package/dist/base-bot.js

@@ -0,0 +1,375 @@
+/**
+ * Base Bot Abstract Class for Platform-Agnostic Bot Logic
+ * ========================================================
+ *
+ * Provides shared functionality for all platform-specific bots (Slack, Discord, etc.)
+ * Eliminates code duplication by consolidating common patterns:
+ * - Circuit breaker pattern for fault tolerance
+ * - Exponential backoff retry logic
+ * - Metrics tracking and monitoring
+ * - Tool invocation with resilience
+ *
+ * This is an abstract class - cannot be instantiated directly.
+ * Platform-specific bots must extend this and implement abstract methods.
+ *
+ * @example
+ * ```typescript
+ * export class SlackBot extends BaseBot {
+ *   async handleMention(event: SlackMentionEvent): Promise<void> {
+ *     // Slack-specific mention handling
+ *   }
+ *
+ *   async start(): Promise<void> {
+ *     await super.initializeAbilityResponseSubscription();
+ *     await this.subscribeToMentions();
+ *   }
+ *
+ *   stop(): void {
+ *     // Cleanup logic
+ *   }
+ * }
+ * ```
+ */
+import Anthropic from '@anthropic-ai/sdk';
+import { logger, MODULE_AGENT } from './utils/logger.js';
+import { timer } from './utils/timer.js';
+// ============================================================================
+// Abstract Base Bot Class
+// ============================================================================
+/**
+ * Abstract base class for platform-agnostic bot logic
+ *
+ * Provides common functionality shared across all platform bots:
+ * - Circuit breaker for fault tolerance
+ * - Retry logic with exponential backoff
+ * - Metrics tracking
+ * - Tool invocation helpers
+ *
+ * Platform-specific bots (SlackBot, DiscordBot) extend this class
+ * and implement the abstract methods.
+ */
+export class BaseBot {
+    // ============================================================================
+    // Protected Properties (accessible to subclasses)
+    // ============================================================================
+    /** KĀDI client for broker communication */
+    client;
+    /** Anthropic API client for Claude integration */
+    anthropic;
+    /** Bot user ID for topic routing */
+    botUserId;
+    /** Optional provider manager for LLM operations */
+    providerManager;
+    /** Optional memory service for conversation context */
+    memoryService;
+    /** Pending async tool responses (requestId -> Promise resolver) */
+    pendingResponses = new Map();
+    // ============================================================================
+    // Circuit Breaker State (private)
+    // ============================================================================
+    /** Number of consecutive failures */
+    failureCount = 0;
+    /** Timestamp of last failure (for reset timeout) */
+    lastFailureTime = 0;
+    /** Maximum failures before circuit opens */
+    maxFailures = 5;
+    /** Time in ms before circuit breaker resets */
+    resetTimeMs = 60000; // 1 minute
+    /** Whether circuit breaker is open (blocking requests) */
+    isCircuitOpen = false;
+    // ============================================================================
+    // Retry Configuration (private)
+    // ============================================================================
+    /** Maximum retry attempts for failed operations */
+    maxRetries = 3;
+    /** Base delay in ms for exponential backoff (1s, 2s, 4s) */
+    baseDelayMs = 1000;
+    // ============================================================================
+    // Metrics Tracking (private)
+    // ============================================================================
+    /** Total number of requests processed */
+    totalRequests = 0;
+    /** Number of requests that timed out */
+    timeoutCount = 0;
+    /** Number of successful requests */
+    successCount = 0;
+    // ============================================================================
+    // Constructor
+    // ============================================================================
+    /**
+     * Create a new BaseBot instance
+     *
+     * @param config - Base bot configuration with client, API key, and bot ID
+     */
+    constructor(config) {
+        this.client = config.client;
+        this.anthropic = new Anthropic({ apiKey: config.anthropicApiKey });
+        this.botUserId = config.botUserId;
+        this.providerManager = config.providerManager;
+        this.memoryService = config.memoryService;
+    }
+    // ============================================================================
+    // Protected Helper Methods (available to subclasses)
+    // ============================================================================
+    /**
+     * Initialize ability response subscription
+     *
+     * Must be called by subclasses in their start() method
+     * before attempting to invoke tools or subscribe to events.
+     *
+     * Subscribes to async ability responses from kadi-broker.
+     */
+    async initializeAbilityResponseSubscription() {
+        // Subscribe to async ability responses from kadi-broker
+        await this.subscribeToAbilityResponses();
+    }
+    /**
+     * Subscribe to kadi.ability.response notifications
+     *
+     * Handles async tool results from broker. When a tool returns {status: "pending"},
+     * the actual result arrives later as a kadi.ability.response notification.
+     *
+     * @private
+     */
+    async subscribeToAbilityResponses() {
+        // Subscribe to kadi.ability.response events via kadi-core v0.6.0 subscribe API
+        await this.client.subscribe('kadi.ability.response', (event) => {
+            const { requestId, result, error } = event || {};
+            const pending = this.pendingResponses.get(requestId);
+            if (!pending) {
+                // This response is for a different request or already handled
+                return;
+            }
+            // Clear timeout timer
+            clearTimeout(pending.timer);
+            this.pendingResponses.delete(requestId);
+            // Resolve or reject the promise
+            if (error) {
+                pending.reject(new Error(`Async tool failed: ${error}`));
+            }
+            else {
+                pending.resolve(result);
+            }
+        }, { broker: 'default' });
+        logger.info(MODULE_AGENT, 'Subscribed to kadi.ability.response notifications', timer.elapsed('main'));
+    }
+    /**
+     * Wait for async ability response from kadi-broker
+     *
+     * When a tool returns {status: "pending", requestId: "..."}, this method
+     * waits for the actual result to arrive via kadi.ability.response notification.
+     *
+     * @param requestId - Request ID from pending status response
+     * @param timeout - Timeout in milliseconds (default: 30000)
+     * @returns Promise that resolves with the actual tool result
+     * @throws Error if timeout expires before result arrives
+     *
+     * @example
+     * ```typescript
+     * const result = await this.protocol.invokeTool({...});
+     * if (result?.status === 'pending') {
+     *   const actualResult = await this.waitForAbilityResponse(result.requestId);
+     *   return actualResult;
+     * }
+     * ```
+     */
+    waitForAbilityResponse(requestId, timeout = 30000) {
+        return new Promise((resolve, reject) => {
+            // Setup timeout
+            const timer = setTimeout(() => {
+                this.pendingResponses.delete(requestId);
+                reject(new Error(`Timeout waiting for async tool result: ${requestId}`));
+            }, timeout);
+            // Register promise resolver
+            this.pendingResponses.set(requestId, {
+                resolve,
+                reject,
+                timer
+            });
+        });
+    }
+    /**
+     * Sleep for specified milliseconds
+     *
+     * Used for exponential backoff delays in retry logic.
+     *
+     * @param ms - Milliseconds to sleep
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Check circuit breaker state and reset if needed
+     *
+     * Returns true if circuit is open (blocking requests).
+     * Automatically resets circuit after resetTimeMs has elapsed.
+     *
+     * @returns true if circuit is open, false if closed
+     *
+     * @example
+     * ```typescript
+     * if (this.checkCircuitBreaker()) {
+     *   console.log('Circuit open - skipping request');
+     *   return;
+     * }
+     * ```
+     */
+    checkCircuitBreaker() {
+        const now = Date.now();
+        // Reset circuit if enough time has passed
+        if (this.isCircuitOpen && (now - this.lastFailureTime) > this.resetTimeMs) {
+            console.log('🔧 Circuit breaker reset - attempting recovery');
+            this.isCircuitOpen = false;
+            this.failureCount = 0;
+        }
+        return this.isCircuitOpen;
+    }
+    /**
+     * Record failure and update circuit breaker state
+     *
+     * Increments failure count and opens circuit if maxFailures threshold reached.
+     * Logs metrics every 10 requests.
+     *
+     * @param _error - Error object (for potential future use)
+     */
+    recordFailure(_error) {
+        this.failureCount++;
+        this.lastFailureTime = Date.now();
+        this.timeoutCount++;
+        if (this.failureCount >= this.maxFailures && !this.isCircuitOpen) {
+            this.isCircuitOpen = true;
+            console.error(`⚡ Circuit breaker OPEN after ${this.failureCount} failures`);
+            console.error(`   Will retry after ${this.resetTimeMs / 1000} seconds`);
+        }
+        // Log timeout metrics every 10 requests
+        if (this.totalRequests % 10 === 0) {
+            this.logMetrics();
+        }
+    }
+    /**
+     * Record success and reset failure counter
+     *
+     * Resets consecutive failure count when a request succeeds.
+     * Increments success metrics.
+     */
+    recordSuccess() {
+        if (this.failureCount > 0) {
+            console.log(`✅ Request succeeded - resetting failure count (was ${this.failureCount})`);
+        }
+        this.failureCount = 0;
+        this.successCount++;
+    }
+    /**
+     * Reset circuit breaker state
+     *
+     * Manually resets circuit breaker and clears failure count.
+     * Use with caution - typically circuit should auto-reset.
+     */
+    resetCircuitBreaker() {
+        this.isCircuitOpen = false;
+        this.failureCount = 0;
+        this.lastFailureTime = 0;
+        console.log('🔧 Circuit breaker manually reset');
+    }
+    /**
+     * Invoke KĀDI tool with retry logic and exponential backoff
+     *
+     * Automatically retries failed tool invocations with exponential backoff:
+     * - Attempt 1: Immediate
+     * - Attempt 2: 1s delay
+     * - Attempt 3: 2s delay
+     * - Attempt 4: 4s delay
+     *
+     * Only retries on timeout or network errors. Other errors fail immediately.
+     *
+     * @param params - Tool invocation parameters
+     * @param params.targetAgent - Target agent ID (e.g., 'mcp-server-slack')
+     * @param params.toolName - Tool name to invoke (e.g., 'send_slack_message')
+     * @param params.toolInput - Tool input parameters
+     * @param params.timeout - Timeout in milliseconds
+     * @param retryCount - Current retry attempt (internal, do not set)
+     * @returns Tool invocation result
+     * @throws Error if all retries exhausted
+     *
+     * @example
+     * ```typescript
+     * await this.invokeToolWithRetry({
+     *   targetAgent: 'mcp-server-slack',
+     *   toolName: 'send_slack_message',
+     *   toolInput: { channel: 'C123', text: 'Hello' },
+     *   timeout: 10000
+     * });
+     * ```
+     */
+    async invokeToolWithRetry(params, retryCount = 0) {
+        this.totalRequests++;
+        try {
+            const result = await this.client.invokeRemote(params.toolName, params.toolInput, { timeout: params.timeout });
+            this.recordSuccess();
+            return result;
+        }
+        catch (error) {
+            const isTimeout = error.message?.includes('timeout');
+            const isNetworkError = error.message?.includes('ECONNREFUSED') ||
+                error.message?.includes('ENOTFOUND');
+            // Only retry on timeout or network errors
+            if ((isTimeout || isNetworkError) && retryCount < this.maxRetries) {
+                const delayMs = this.baseDelayMs * Math.pow(2, retryCount);
+                console.warn(`⚠️  Request failed (${error.message}), retrying in ${delayMs}ms (attempt ${retryCount + 1}/${this.maxRetries})...`);
+                await this.sleep(delayMs);
+                return this.invokeToolWithRetry(params, retryCount + 1);
+            }
+            // Record failure after all retries exhausted
+            this.recordFailure(error);
+            throw error;
+        }
+    }
+    /**
+     * Get current bot metrics
+     *
+     * Returns metrics for monitoring and debugging:
+     * - Total requests processed
+     * - Success count and rate
+     * - Timeout count and rate
+     * - Circuit breaker state
+     *
+     * @returns Metrics object
+     *
+     * @example
+     * ```typescript
+     * const metrics = this.getMetrics();
+     * console.log(`Success rate: ${metrics.successRate}%`);
+     * ```
+     */
+    getMetrics() {
+        const successRate = this.totalRequests > 0
+            ? (this.successCount / this.totalRequests) * 100
+            : 0;
+        const timeoutRate = this.totalRequests > 0
+            ? (this.timeoutCount / this.totalRequests) * 100
+            : 0;
+        return {
+            totalRequests: this.totalRequests,
+            successCount: this.successCount,
+            timeoutCount: this.timeoutCount,
+            successRate: parseFloat(successRate.toFixed(1)),
+            timeoutRate: parseFloat(timeoutRate.toFixed(1)),
+            isCircuitOpen: this.isCircuitOpen
+        };
+    }
+    /**
+     * Log timeout and success metrics
+     *
+     * Logs formatted metrics to console for monitoring.
+     * Called automatically every 10 requests or can be called manually.
+     */
+    logMetrics() {
+        const metrics = this.getMetrics();
+        console.log('📊 Bot Metrics:');
+        console.log(`   Total Requests: ${metrics.totalRequests}`);
+        console.log(`   Successes: ${metrics.successCount} (${metrics.successRate}%)`);
+        console.log(`   Timeouts: ${metrics.timeoutCount} (${metrics.timeoutRate}%)`);
+        console.log(`   Circuit Breaker: ${metrics.isCircuitOpen ? 'OPEN' : 'CLOSED'}`);
+    }
+}
+//# sourceMappingURL=base-bot.js.map

package/dist/base-bot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-bot.js","sourceRoot":"","sources":["../src/base-bot.ts"],"names":[],"mappings":"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"}