agents-library 1.1.0

package/dist/types/tool-schemas.d.ts

@@ -0,0 +1,498 @@
+/**
+ * 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 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 declare enum ErrorType {
+    /**
+     * Transient error - may succeed on retry
+     *
+     * Includes:
+     * - Network errors (ECONNREFUSED, ENOTFOUND)
+     * - Timeout errors
+     * - Rate limit errors (429)
+     * - Temporary service unavailable (503)
+     */
+    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
+     */
+    Permanent = "permanent"
+}
+/**
+ * Tool schema interface for KĀDI tool registration
+ *
+ * Defines the structure of a tool including name, description, and Zod schemas
+ * for input/output validation. Compatible with @kadi.build/core tool registration.
+ *
+ * @example
+ * ```typescript
+ * const sendMessageTool: ToolSchema = {
+ *   name: 'send_slack_message',
+ *   description: 'Send a message to a Slack channel',
+ *   input: z.object({
+ *     channel: z.string().describe('Channel ID (e.g., C12345678)'),
+ *     text: z.string().describe('Message text to send'),
+ *     thread_ts: z.string().optional().describe('Optional thread timestamp for replies')
+ *   }),
+ *   output: z.object({
+ *     ok: z.boolean().describe('Whether the message was sent successfully'),
+ *     ts: z.string().describe('Timestamp of the sent message'),
+ *     channel: z.string().describe('Channel ID where message was sent')
+ *   })
+ * };
+ * ```
+ */
+export interface ToolSchema<TInput = any, TOutput = any> {
+    /**
+     * Tool name (must be unique within agent)
+     *
+     * Convention: lowercase with underscores (e.g., 'send_slack_message', 'plan_task')
+     */
+    name: string;
+    /**
+     * Human-readable tool description
+     *
+     * Describes what the tool does and when to use it.
+     * Used by Claude API for tool selection.
+     */
+    description: string;
+    /**
+     * Input schema using Zod
+     *
+     * Defines and validates the structure of tool input parameters.
+     * Use .describe() on each field to provide documentation.
+     */
+    input: z.ZodType<TInput>;
+    /**
+     * Output schema using Zod
+     *
+     * Defines and validates the structure of tool output.
+     * Use .describe() on each field to provide documentation.
+     */
+    output: z.ZodType<TOutput>;
+}
+/**
+ * Success result from tool invocation
+ *
+ * Represents a successful tool execution with result data.
+ * Discriminated by `success: true`.
+ *
+ * @example
+ * ```typescript
+ * const result: ToolInvocationSuccess = {
+ *   success: true,
+ *   result: {
+ *     ok: true,
+ *     ts: '1234567890.123456',
+ *     channel: 'C12345678'
+ *   }
+ * };
+ * ```
+ */
+export interface ToolInvocationSuccess<T = any> {
+    /** Discriminator for type narrowing */
+    success: true;
+    /** Tool execution result (validated against output schema) */
+    result: T;
+}
+/**
+ * Failure result from tool invocation
+ *
+ * Represents a failed tool execution with error details.
+ * Discriminated by `success: false`.
+ *
+ * @example
+ * ```typescript
+ * const result: ToolInvocationFailure = {
+ *   success: false,
+ *   error: new Error('Connection timeout after 10 seconds'),
+ *   errorType: ErrorType.Transient
+ * };
+ * ```
+ */
+export interface ToolInvocationFailure {
+    /** Discriminator for type narrowing */
+    success: false;
+    /** Error object with message and stack trace */
+    error: Error;
+    /**
+     * Error classification for retry logic (optional)
+     *
+     * If not provided, retry logic should classify error based on error message.
+     */
+    errorType?: ErrorType;
+}
+/**
+ * Tool invocation result (discriminated union)
+ *
+ * Result of a tool execution - either success with result data or failure with error.
+ * Use discriminated union pattern for type-safe error handling.
+ *
+ * @example
+ * ```typescript
+ * async function invokeTool(toolName: string, input: any): Promise<ToolInvocationResult> {
+ *   try {
+ *     const result = await protocol.invokeTool({ toolName, toolInput: input });
+ *     return { success: true, result };
+ *   } catch (error) {
+ *     return {
+ *       success: false,
+ *       error: error instanceof Error ? error : new Error(String(error)),
+ *       errorType: classifyError(error)
+ *     };
+ *   }
+ * }
+ *
+ * // Usage with type narrowing
+ * const result = await invokeTool('send_message', { channel: 'C123', text: 'Hello' });
+ *
+ * if (result.success) {
+ *   // TypeScript knows result.result exists
+ *   console.log('Message sent:', result.result.ts);
+ * } else {
+ *   // TypeScript knows result.error exists
+ *   if (result.errorType === ErrorType.Transient) {
+ *     console.log('Transient error - retrying:', result.error.message);
+ *   } else {
+ *     console.error('Permanent error - failing:', result.error.message);
+ *   }
+ * }
+ * ```
+ */
+export type ToolInvocationResult<T = any> = ToolInvocationSuccess<T> | ToolInvocationFailure;
+/**
+ * Parameters for invoking a tool via KĀDI broker protocol
+ *
+ * Used by BaseBot.invokeToolWithRetry() and protocol.invokeTool().
+ *
+ * @example
+ * ```typescript
+ * const params: ToolInvocationParams = {
+ *   targetAgent: 'mcp-server-slack',
+ *   toolName: 'send_slack_message',
+ *   toolInput: {
+ *     channel: 'C12345678',
+ *     text: 'Hello from KĀDI!'
+ *   },
+ *   timeout: 10000
+ * };
+ *
+ * const result = await protocol.invokeTool(params);
+ * ```
+ */
+export interface ToolInvocationParams<T = any> {
+    /**
+     * Target agent ID that provides the tool
+     *
+     * @example 'mcp-server-slack', 'mcp-server-shrimp-agent-playground'
+     */
+    targetAgent: string;
+    /**
+     * Name of the tool to invoke
+     *
+     * @example 'send_slack_message', 'shrimp_plan_task'
+     */
+    toolName: string;
+    /**
+     * Input parameters for the tool (validated against tool's input schema)
+     */
+    toolInput: T;
+    /**
+     * Timeout in milliseconds
+     *
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+}
+/**
+ * Zod schema for ToolInvocationSuccess
+ */
+export declare const ToolInvocationSuccessSchema: z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    result: z.ZodAny;
+}, z.core.$strip>;
+/**
+ * Zod schema for ToolInvocationFailure
+ */
+export declare const ToolInvocationFailureSchema: z.ZodObject<{
+    success: z.ZodLiteral<false>;
+    error: z.ZodCustom<Error, Error>;
+    errorType: z.ZodOptional<z.ZodEnum<typeof ErrorType>>;
+}, z.core.$strip>;
+/**
+ * Zod schema for ToolInvocationResult
+ */
+export declare const ToolInvocationResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    result: z.ZodAny;
+}, z.core.$strip>, z.ZodObject<{
+    success: z.ZodLiteral<false>;
+    error: z.ZodCustom<Error, Error>;
+    errorType: z.ZodOptional<z.ZodEnum<typeof ErrorType>>;
+}, z.core.$strip>], "success">;
+/**
+ * Zod schema for ToolInvocationParams
+ */
+export declare const ToolInvocationParamsSchema: z.ZodObject<{
+    targetAgent: z.ZodString;
+    toolName: z.ZodString;
+    toolInput: z.ZodAny;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * 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 declare function isToolInvocationSuccess<T = any>(result: ToolInvocationResult<T>): result is ToolInvocationSuccess<T>;
+/**
+ * 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 declare function isToolInvocationFailure(result: ToolInvocationResult): result is ToolInvocationFailure;
+/**
+ * Detailed error classification result
+ *
+ * Provides comprehensive error information for intelligent retry logic and error handling.
+ * Used by BaseBot, producer utilities, and worker agents to decide retry strategies.
+ *
+ * @example
+ * ```typescript
+ * const classification = classifyToolError(error);
+ *
+ * if (classification.retryable) {
+ *   console.log(`Transient ${classification.category}: ${classification.message}`);
+ *   if (classification.category === 'rate_limit') {
+ *     // Use exponential backoff for rate limiting
+ *     await retryWithExponentialBackoff(() => operation());
+ *   } else {
+ *     // Use standard retry for other transient errors
+ *     await retryWithBackoff(() => operation());
+ *   }
+ * } else {
+ *   console.error(`Permanent ${classification.category}: ${classification.message}`);
+ *   throw error; // Fail-fast
+ * }
+ * ```
+ */
+export interface ErrorClassification {
+    /**
+     * Error type for basic classification
+     *
+     * - 'transient': Error may succeed on retry (network issues, timeouts, rate limits, 5xx)
+     * - 'permanent': Error will not succeed on retry (validation, auth, 4xx except 429)
+     */
+    type: 'transient' | 'permanent';
+    /**
+     * Specific error category for fine-grained handling
+     *
+     * Categories:
+     * - Transient: 'network', 'timeout', 'rate_limit', 'server_error', 'service_unavailable'
+     * - Permanent: 'validation', 'authentication', 'authorization', 'not_found', 'bad_request', 'unknown'
+     */
+    category: string;
+    /**
+     * Human-readable error message
+     *
+     * Describes what went wrong and provides context for debugging.
+     */
+    message: string;
+    /**
+     * Whether the error is retriable
+     *
+     * True for transient errors, false for permanent errors.
+     * Use this flag to decide retry strategy.
+     */
+    retryable: boolean;
+    /**
+     * Optional HTTP status code if available
+     *
+     * Extracted from error message, error object, or HTTP response.
+     */
+    statusCode?: number;
+    /**
+     * Optional Node.js error code if available
+     *
+     * Examples: ECONNREFUSED, ETIMEDOUT, ENOTFOUND, ECONNRESET
+     */
+    errorCode?: string;
+}
+/**
+ * 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 declare function classifyToolError(error: Error | unknown): ErrorClassification;
+//# sourceMappingURL=tool-schemas.d.ts.map

package/dist/types/tool-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-schemas.d.ts","sourceRoot":"","sources":["../../src/types/tool-schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,kBAAkB,CAAC;AAMrC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,oBAAY,SAAS;IACnB;;;;;;;;OAQG;IACH,SAAS,cAAc;IAEvB;;;;;;;;;OASG;IACH,SAAS,cAAc;CACxB;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,UAAU,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG;IACrD;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;OAKG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;;OAKG;IACH,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzB;;;;;OAKG;IACH,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5B;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC,GAAG,GAAG;IAC5C,uCAAuC;IACvC,OAAO,EAAE,IAAI,CAAC;IAEd,8DAA8D;IAC9D,MAAM,EAAE,CAAC,CAAC;CACX;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,qBAAqB;IACpC,uCAAuC;IACvC,OAAO,EAAE,KAAK,CAAC;IAEf,gDAAgD;IAChD,KAAK,EAAE,KAAK,CAAC;IAEb;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,GAAG,GAAG,IAAI,qBAAqB,CAAC,CAAC,CAAC,GAAG,qBAAqB,CAAC;AAM7F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,GAAG,GAAG;IAC3C;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,SAAS,EAAE,CAAC,CAAC;IAEb;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD;;GAEG;AACH,eAAO,MAAM,2BAA2B;;;iBAGtC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,2BAA2B;;;;iBAItC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,0BAA0B;;;;;;;8BAGrC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,0BAA0B;;;;;iBAKrC,CAAC;AAMH;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,GAAG,GAAG,EAC7C,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC9B,MAAM,IAAI,qBAAqB,CAAC,CAAC,CAAC,CAEpC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,oBAAoB,GAC3B,MAAM,IAAI,qBAAqB,CAEjC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,IAAI,EAAE,WAAW,GAAG,WAAW,CAAC;IAEhC;;;;;;OAMG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,SAAS,EAAE,OAAO,CAAC;IAEnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgHG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,GAAG,mBAAmB,CA+N7E"}