agents-library 0.1.0

package/dist/types/tool-schemas.js

@@ -0,0 +1,457 @@
+/**
+ * Tool Schema Type Definitions
+ * ==============================
+ *
+ * Type definitions for KĀDI tool invocation, validation, and error handling.
+ * Provides standardized interfaces for tool schemas, invocation results, and error classification.
+ *
+ * Design Principles:
+ * - Discriminated unions for type-safe result handling
+ * - Clear error classification for retry logic
+ * - Compatible with @kadi.build/core tool registration
+ * - Runtime validation via Zod schemas
+ *
+ * @module tool-schemas
+ */
+import { z } from '@kadi.build/core';
+// ============================================================================
+// Error Classification
+// ============================================================================
+/**
+ * Error type classification for retry logic
+ *
+ * Discriminates between transient errors (retry allowed) and permanent errors (fail-fast).
+ * Used by circuit breaker and exponential backoff retry logic in BaseBot.
+ *
+ * @example
+ * ```typescript
+ * function classifyError(error: Error): ErrorType {
+ *   const message = error.message.toLowerCase();
+ *
+ *   // Transient errors - retry allowed
+ *   if (message.includes('timeout')) return ErrorType.Transient;
+ *   if (message.includes('econnrefused')) return ErrorType.Transient;
+ *   if (message.includes('enotfound')) return ErrorType.Transient;
+ *   if (message.includes('rate limit')) return ErrorType.Transient;
+ *
+ *   // Permanent errors - fail-fast
+ *   if (message.includes('unauthorized')) return ErrorType.Permanent;
+ *   if (message.includes('not found')) return ErrorType.Permanent;
+ *   if (message.includes('invalid')) return ErrorType.Permanent;
+ *   if (message.includes('validation')) return ErrorType.Permanent;
+ *
+ *   // Default to permanent to avoid infinite retry loops
+ *   return ErrorType.Permanent;
+ * }
+ * ```
+ */
+export var ErrorType;
+(function (ErrorType) {
+    /**
+     * Transient error - may succeed on retry
+     *
+     * Includes:
+     * - Network errors (ECONNREFUSED, ENOTFOUND)
+     * - Timeout errors
+     * - Rate limit errors (429)
+     * - Temporary service unavailable (503)
+     */
+    ErrorType["Transient"] = "transient";
+    /**
+     * Permanent error - will not succeed on retry
+     *
+     * Includes:
+     * - Validation errors (400)
+     * - Authentication errors (401, 403)
+     * - Not found errors (404)
+     * - Invalid input errors
+     * - Business logic errors
+     */
+    ErrorType["Permanent"] = "permanent";
+})(ErrorType || (ErrorType = {}));
+// ============================================================================
+// Zod Schemas for Runtime Validation
+// ============================================================================
+/**
+ * Zod schema for ToolInvocationSuccess
+ */
+export const ToolInvocationSuccessSchema = z.object({
+    success: z.literal(true),
+    result: z.any()
+});
+/**
+ * Zod schema for ToolInvocationFailure
+ */
+export const ToolInvocationFailureSchema = z.object({
+    success: z.literal(false),
+    error: z.instanceof(Error),
+    errorType: z.nativeEnum(ErrorType).optional()
+});
+/**
+ * Zod schema for ToolInvocationResult
+ */
+export const ToolInvocationResultSchema = z.discriminatedUnion('success', [
+    ToolInvocationSuccessSchema,
+    ToolInvocationFailureSchema
+]);
+/**
+ * Zod schema for ToolInvocationParams
+ */
+export const ToolInvocationParamsSchema = z.object({
+    targetAgent: z.string().min(1, 'Target agent ID is required'),
+    toolName: z.string().min(1, 'Tool name is required'),
+    toolInput: z.any(),
+    timeout: z.number().positive().optional()
+});
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Type guard to check if result is a success
+ *
+ * @param result - Tool invocation result
+ * @returns True if result is ToolInvocationSuccess
+ *
+ * @example
+ * ```typescript
+ * if (isToolInvocationSuccess(result)) {
+ *   console.log('Success:', result.result);
+ * }
+ * ```
+ */
+export function isToolInvocationSuccess(result) {
+    return result.success === true;
+}
+/**
+ * Type guard to check if result is a failure
+ *
+ * @param result - Tool invocation result
+ * @returns True if result is ToolInvocationFailure
+ *
+ * @example
+ * ```typescript
+ * if (isToolInvocationFailure(result)) {
+ *   console.error('Failure:', result.error.message);
+ * }
+ * ```
+ */
+export function isToolInvocationFailure(result) {
+    return result.success === false;
+}
+/**
+ * Classify error as transient or permanent with detailed categorization
+ *
+ * Analyzes errors from multiple sources (Claude API, KĀDI broker, Node.js) and returns
+ * detailed classification for intelligent retry logic. Handles HTTP status codes,
+ * Node.js error codes, and error message patterns.
+ *
+ * **Classification Rules:**
+ *
+ * **Transient Errors (retry allowed):**
+ * - Network errors: ECONNREFUSED, ENOTFOUND, ECONNRESET, ETIMEDOUT
+ * - Timeout errors: timeout, ETIMEDOUT
+ * - Rate limiting: 429 status code, "rate limit" message (use exponential backoff)
+ * - Server errors: 5xx status codes, "service unavailable"
+ * - Connection errors: "socket hang up", "connection reset"
+ *
+ * **Permanent Errors (fail-fast):**
+ * - Validation errors: 400 Bad Request, "validation", "invalid"
+ * - Authentication: 401 Unauthorized, "unauthorized"
+ * - Authorization: 403 Forbidden, "forbidden"
+ * - Not found: 404 Not Found, "not found"
+ * - Other 4xx client errors (except 429)
+ *
+ * **Special Cases:**
+ * - 429 (Rate Limit): Classified as transient with category 'rate_limit' - use exponential backoff
+ * - Unknown errors: Default to permanent to avoid infinite retry loops
+ *
+ * **Error Source Handling:**
+ * - **Claude API errors**: Anthropic SDK error objects with status codes
+ * - **KĀDI protocol errors**: Protocol response errors with status/statusCode fields
+ * - **Node.js errors**: Error objects with code property (ECONNREFUSED, etc.)
+ * - **Generic errors**: Error message pattern matching
+ *
+ * @param error - Error to classify (Error object, unknown type, or any)
+ * @returns Detailed error classification with type, category, message, retryable flag
+ *
+ * @example
+ * ```typescript
+ * // Network error (transient)
+ * try {
+ *   await fetch('http://unavailable-service.com');
+ * } catch (error) {
+ *   const classification = classifyToolError(error);
+ *   // { type: 'transient', category: 'network', message: 'ECONNREFUSED', retryable: true, errorCode: 'ECONNREFUSED' }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Rate limit error (transient with exponential backoff)
+ * try {
+ *   await anthropic.messages.create({ ... });
+ * } catch (error) {
+ *   const classification = classifyToolError(error);
+ *   // { type: 'transient', category: 'rate_limit', message: 'Rate limit exceeded', retryable: true, statusCode: 429 }
+ *
+ *   if (classification.category === 'rate_limit') {
+ *     // Use exponential backoff specifically for rate limits
+ *     await retryWithExponentialBackoff(() => operation(), { baseDelay: 1000, maxDelay: 60000 });
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Validation error (permanent)
+ * try {
+ *   await invokeTool({ toolName: 'invalid', toolInput: null });
+ * } catch (error) {
+ *   const classification = classifyToolError(error);
+ *   // { type: 'permanent', category: 'validation', message: 'Invalid tool input', retryable: false, statusCode: 400 }
+ *
+ *   // Don't retry - fail immediately
+ *   console.error('Validation failed:', classification.message);
+ *   throw error;
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Generic error handling with classification
+ * async function executeWithRetry(operation: () => Promise<any>, maxRetries: number = 3) {
+ *   let attempt = 0;
+ *
+ *   while (attempt < maxRetries) {
+ *     try {
+ *       return await operation();
+ *     } catch (error) {
+ *       const classification = classifyToolError(error);
+ *
+ *       console.error(`Attempt ${attempt + 1} failed:`, classification.message);
+ *
+ *       if (!classification.retryable) {
+ *         // Permanent error - fail immediately
+ *         throw new Error(`Permanent error (${classification.category}): ${classification.message}`);
+ *       }
+ *
+ *       // Calculate delay based on error category
+ *       const delay = classification.category === 'rate_limit'
+ *         ? Math.pow(2, attempt) * 1000  // Exponential backoff for rate limits
+ *         : 1000;  // Fixed delay for other transient errors
+ *
+ *       console.log(`Retrying in ${delay}ms...`);
+ *       await new Promise(resolve => setTimeout(resolve, delay));
+ *
+ *       attempt++;
+ *     }
+ *   }
+ *
+ *   throw new Error(`Operation failed after ${maxRetries} attempts`);
+ * }
+ * ```
+ */
+export function classifyToolError(error) {
+    // Extract error message for pattern matching
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const messageLower = errorMessage.toLowerCase();
+    // Extract Node.js error code if available
+    const errorCode = error?.code;
+    // Extract HTTP status code from various sources
+    let statusCode;
+    // Try to extract from error object (Anthropic SDK, KĀDI protocol)
+    if (typeof error?.status === 'number') {
+        statusCode = error.status;
+    }
+    else if (typeof error?.statusCode === 'number') {
+        statusCode = error.statusCode;
+    }
+    else if (typeof error?.response?.status === 'number') {
+        statusCode = error.response.status;
+    }
+    // Try to extract from error message (e.g., "400 Bad Request", "429 Too Many Requests")
+    if (!statusCode) {
+        const statusMatch = errorMessage.match(/\b([45]\d{2})\b/);
+        if (statusMatch) {
+            statusCode = parseInt(statusMatch[1], 10);
+        }
+    }
+    // ============================================================================
+    // Transient Error Classification (retry allowed)
+    // ============================================================================
+    // Rate Limit (429) - Special case: use exponential backoff
+    if (statusCode === 429 || messageLower.includes('rate limit') || messageLower.includes('too many requests')) {
+        return {
+            type: 'transient',
+            category: 'rate_limit',
+            message: 'Rate limit exceeded - use exponential backoff',
+            retryable: true,
+            statusCode: statusCode || 429,
+            errorCode
+        };
+    }
+    // Network Errors (Node.js error codes)
+    if (errorCode === 'ECONNREFUSED') {
+        return {
+            type: 'transient',
+            category: 'network',
+            message: 'Connection refused - service may be unavailable',
+            retryable: true,
+            errorCode
+        };
+    }
+    if (errorCode === 'ENOTFOUND') {
+        return {
+            type: 'transient',
+            category: 'network',
+            message: 'DNS lookup failed - hostname not found',
+            retryable: true,
+            errorCode
+        };
+    }
+    if (errorCode === 'ECONNRESET') {
+        return {
+            type: 'transient',
+            category: 'network',
+            message: 'Connection reset by peer',
+            retryable: true,
+            errorCode
+        };
+    }
+    if (errorCode === 'ETIMEDOUT') {
+        return {
+            type: 'transient',
+            category: 'timeout',
+            message: 'Connection timed out',
+            retryable: true,
+            errorCode
+        };
+    }
+    // Timeout Errors (message patterns)
+    if (messageLower.includes('timeout') || messageLower.includes('timed out')) {
+        return {
+            type: 'transient',
+            category: 'timeout',
+            message: 'Operation timed out',
+            retryable: true,
+            statusCode,
+            errorCode
+        };
+    }
+    // Server Errors (5xx status codes)
+    if (statusCode && statusCode >= 500 && statusCode < 600) {
+        return {
+            type: 'transient',
+            category: 'server_error',
+            message: `Server error (${statusCode})`,
+            retryable: true,
+            statusCode,
+            errorCode
+        };
+    }
+    // Service Unavailable (503 or message patterns)
+    if (messageLower.includes('service unavailable') || messageLower.includes('unavailable')) {
+        return {
+            type: 'transient',
+            category: 'service_unavailable',
+            message: 'Service temporarily unavailable',
+            retryable: true,
+            statusCode: statusCode || 503,
+            errorCode
+        };
+    }
+    // Connection Errors (message patterns)
+    if (messageLower.includes('socket hang up') || messageLower.includes('connection reset')) {
+        return {
+            type: 'transient',
+            category: 'network',
+            message: 'Connection interrupted',
+            retryable: true,
+            statusCode,
+            errorCode
+        };
+    }
+    // ============================================================================
+    // Permanent Error Classification (fail-fast)
+    // ============================================================================
+    // Bad Request (400)
+    if (statusCode === 400 || messageLower.includes('bad request')) {
+        return {
+            type: 'permanent',
+            category: 'bad_request',
+            message: 'Bad request - check input parameters',
+            retryable: false,
+            statusCode: statusCode || 400,
+            errorCode
+        };
+    }
+    // Validation Errors
+    if (messageLower.includes('validation') || messageLower.includes('invalid')) {
+        return {
+            type: 'permanent',
+            category: 'validation',
+            message: 'Validation failed - check input data',
+            retryable: false,
+            statusCode,
+            errorCode
+        };
+    }
+    // Authentication (401)
+    if (statusCode === 401 || messageLower.includes('unauthorized') || messageLower.includes('authentication')) {
+        return {
+            type: 'permanent',
+            category: 'authentication',
+            message: 'Authentication failed - check API key or credentials',
+            retryable: false,
+            statusCode: statusCode || 401,
+            errorCode
+        };
+    }
+    // Authorization (403)
+    if (statusCode === 403 || messageLower.includes('forbidden') || messageLower.includes('permission denied')) {
+        return {
+            type: 'permanent',
+            category: 'authorization',
+            message: 'Access forbidden - insufficient permissions',
+            retryable: false,
+            statusCode: statusCode || 403,
+            errorCode
+        };
+    }
+    // Not Found (404)
+    if (statusCode === 404 || messageLower.includes('not found')) {
+        return {
+            type: 'permanent',
+            category: 'not_found',
+            message: 'Resource not found',
+            retryable: false,
+            statusCode: statusCode || 404,
+            errorCode
+        };
+    }
+    // Other 4xx Client Errors (except 429 which is handled above)
+    if (statusCode && statusCode >= 400 && statusCode < 500 && statusCode !== 429) {
+        return {
+            type: 'permanent',
+            category: 'bad_request',
+            message: `Client error (${statusCode})`,
+            retryable: false,
+            statusCode,
+            errorCode
+        };
+    }
+    // ============================================================================
+    // Default Classification (unknown errors)
+    // ============================================================================
+    // Default to permanent to avoid infinite retry loops
+    // Better to fail-fast on unknown errors than retry indefinitely
+    return {
+        type: 'permanent',
+        category: 'unknown',
+        message: errorMessage || 'Unknown error',
+        retryable: false,
+        statusCode,
+        errorCode
+    };
+}
+//# sourceMappingURL=tool-schemas.js.map

package/dist/types/tool-schemas.js.map

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

package/dist/utils/logger.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Unreal Engine-Style Logger Utility
+ * ==================================
+ *
+ * Provides structured logging with Unreal Engine format:
+ * [MODULE_NAME] [HH:MM:SS.mmm] LogLevel: Message
+ *
+ * This logger is shared across all KĀDI agents (template-agent-typescript,
+ * agent-producer, agent-artist, etc.) for consistent log formatting.
+ *
+ * Usage:
+ * ```typescript
+ * import { logger, MODULE_AGENT } from 'agents-library';
+ *
+ * logger.info(MODULE_AGENT, 'Application started');
+ * logger.warn(MODULE_SLACK_BOT, 'Circuit breaker open', { timeout: 5000 });
+ * logger.error(MODULE_AGENT, 'Connection failed', error);
+ * logger.debug(MODULE_TOOLS, 'Tool invocation', { toolName: 'echo' });
+ * ```
+ *
+ * @module logger
+ */
+/**
+ * Module name constants for structured logging
+ * All use kebab-case for consistency with KĀDI naming conventions
+ */
+export declare const MODULE_AGENT: "template-agent";
+export declare const MODULE_SLACK_BOT: "slack-bot";
+export declare const MODULE_DISCORD_BOT: "discord-bot";
+export declare const MODULE_TASK_HANDLER: "task-handler";
+export declare const MODULE_TOOLS: "tools";
+/**
+ * UnrealLogger class for Unreal Engine-style structured logging
+ *
+ * Formats all log output as: [MODULE_NAME] [HH:MM:SS.mmm] LogLevel: Message
+ *
+ * @example
+ * ```typescript
+ * const logger = new UnrealLogger();
+ * logger.info('my-module', 'Initialization complete');
+ * // Output: [my-module] [14:32:45.123] Info: Initialization complete
+ * ```
+ */
+declare class Logger {
+    /**
+     * Get current timestamp in HH:MM:SS.mmm format
+     *
+     * @returns Formatted timestamp string with millisecond precision
+     */
+    private getTimestamp;
+    /**
+     * Determine if colors should be used in log output
+     *
+     * Colors are enabled only when:
+     * 1. stdout is a TTY (interactive terminal)
+     * 2. NO_COLOR environment variable is not set
+     *
+     * This respects the NO_COLOR standard (https://no-color.org/)
+     * which provides a universal way to disable colorized output.
+     *
+     * @returns true if colors should be applied, false for plain text
+     */
+    private shouldUseColors;
+    /**
+     * Format log message with module name and timestamp
+     *
+     * @param module - Module name (e.g., 'template-agent', 'slack-bot')
+     * @param level - Log level (Info, Warning, Error, Debug)
+     * @param message - Log message
+     * @param elapsedTime - Elapsed time suffix (e.g., '+5s', '+3m') - always included
+     * @param color - Optional ANSI color code to apply to module bracket, level indicator, and elapsed time
+     * @returns Formatted log string with selective coloring: <color>[module]<reset> [timestamp] <color>level<reset>: <white>message<reset> <color>elapsedTime<reset>
+     */
+    private formatMessage;
+    /**
+     * Log informational message
+     *
+     * Used for normal operational events (startup, connections, completions)
+     *
+     * @param module - Module name
+     * @param message - Log message
+     * @param elapsedTime - Elapsed time suffix (e.g., '+5s', '+3m')
+     * @param data - Optional data to log (will be logged on separate line)
+     */
+    info(module: string, message: string, elapsedTime: string, data?: any): void;
+    /**
+     * Log warning message
+     *
+     * Used for potentially problematic situations (circuit breaker open, retries, timeouts)
+     *
+     * @param module - Module name
+     * @param message - Log message
+     * @param elapsedTime - Elapsed time suffix (e.g., '+5s', '+3m')
+     * @param data - Optional data to log
+     */
+    warn(module: string, message: string, elapsedTime: string, data?: any): void;
+    /**
+     * Log error message
+     *
+     * Used for error conditions and exceptions
+     *
+     * @param module - Module name
+     * @param message - Log message
+     * @param elapsedTime - Elapsed time suffix (e.g., '+5s', '+3m')
+     * @param error - Optional error object or error message string
+     * @param data - Optional additional data to log
+     */
+    error(module: string, message: string, elapsedTime: string, error?: Error | string, data?: any): void;
+    /**
+     * Log debug message
+     *
+     * Used for detailed diagnostic information during development
+     *
+     * @param module - Module name
+     * @param message - Log message
+     * @param elapsedTime - Elapsed time suffix (e.g., '+5s', '+3m')
+     * @param data - Optional data to log
+     */
+    debug(module: string, message: string, elapsedTime: string, data?: any): void;
+}
+/**
+ * Singleton logger instance
+ *
+ * Export as singleton to ensure consistent timestamp generation and
+ * single source of truth for logging configuration across all agents.
+ *
+ * @example
+ * ```typescript
+ * import { logger, MODULE_AGENT } from 'agents-library';
+ * logger.info(MODULE_AGENT, 'Application started');
+ * ```
+ */
+export declare const logger: Logger;
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAG,gBAAyB,CAAC;AACtD,eAAO,MAAM,gBAAgB,EAAG,WAAoB,CAAC;AACrD,eAAO,MAAM,kBAAkB,EAAG,aAAsB,CAAC;AACzD,eAAO,MAAM,mBAAmB,EAAG,cAAuB,CAAC;AAC3D,eAAO,MAAM,YAAY,EAAG,OAAgB,CAAC;AAoB7C;;;;;;;;;;;GAWG;AACH,cAAM,MAAM;IACR;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAUpB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,eAAe;IAIvB;;;;;;;;;OASG;IACH,OAAO,CAAC,aAAa;IAkBrB;;;;;;;;;OASG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI;IAO5E;;;;;;;;;OASG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI;IAO5E;;;;;;;;;;OAUG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI;IAkBrG;;;;;;;;;OASG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI;CAMhF;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,MAAM,QAAe,CAAC"}