@allternit/gizzi-code 1.0.0

package/src/runtime/tools/Tool.d.ts

@@ -0,0 +1,239 @@
+/**
+ * @fileoverview Runtime tool base class and interfaces
+ * @module runtime/tools/Tool
+ *
+ * Defines the abstract base class for all runtime tools, providing
+ * a standardized interface for tool execution, validation, and schema generation.
+ * All tools in the gizzi-code runtime must extend this base class.
+ */
+import type { Message } from '../../types/message.js';
+/**
+ * Context passed to tools during execution
+ * @interface ToolContext
+ */
+export interface ToolContext {
+    /** Unique identifier for the current execution session */
+    readonly sessionId: string;
+    /** Current user identifier */
+    readonly userId?: string;
+    /** Messages in the current conversation context */
+    readonly messages: readonly Message[];
+    /** Abort signal for cancellation support */
+    readonly signal?: AbortSignal;
+    /** Additional metadata for the execution context */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    /** Callback for reporting progress during long-running operations */
+    readonly onProgress?: (progress: ToolProgress) => void;
+}
+/**
+ * Progress information for long-running tool operations
+ * @interface ToolProgress
+ */
+export interface ToolProgress {
+    /** Current step number */
+    readonly current: number;
+    /** Total number of steps */
+    readonly total: number;
+    /** Human-readable status message */
+    readonly message: string;
+    /** Optional percentage completion (0-100) */
+    readonly percent?: number;
+}
+/**
+ * JSON Schema property definition for tool parameters
+ * @interface ToolParameterSchema
+ */
+export interface ToolParameterSchema {
+    /** Parameter type */
+    readonly type: 'string' | 'number' | 'boolean' | 'array' | 'object' | 'integer';
+    /** Human-readable description of the parameter */
+    readonly description: string;
+    /** Whether the parameter is required */
+    readonly required?: boolean;
+    /** Default value for the parameter */
+    readonly default?: unknown;
+    /** Enum values for constrained parameters */
+    readonly enum?: readonly unknown[];
+    /** Array item schema for array types */
+    readonly items?: ToolParameterSchema;
+    /** Object properties schema for object types */
+    readonly properties?: Readonly<Record<string, ToolParameterSchema>>;
+    /** Format hint for string parameters (e.g., 'date', 'email', 'uri') */
+    readonly format?: string;
+}
+/**
+ * Complete tool schema definition for JSON Schema output
+ * @interface ToolSchema
+ */
+export interface ToolSchema {
+    /** Tool name */
+    readonly name: string;
+    /** Tool description */
+    readonly description: string;
+    /** JSON Schema version */
+    readonly schema: 'http://json-schema.org/draft-07/schema#';
+    /** Parameter definitions */
+    readonly parameters: {
+        readonly type: 'object';
+        readonly properties: Readonly<Record<string, ToolParameterSchema>>;
+        readonly required: readonly string[];
+        readonly additionalProperties: boolean;
+    };
+}
+/**
+ * Result of a tool execution
+ * @interface ToolResult
+ */
+export interface ToolResult<T = unknown> {
+    /** Whether the execution was successful */
+    readonly success: boolean;
+    /** Result data (only present on success) */
+    readonly data?: T;
+    /** Error information (only present on failure) */
+    readonly error?: ToolError;
+    /** Execution metadata */
+    readonly metadata?: {
+        /** Execution duration in milliseconds */
+        readonly duration: number;
+        /** Timestamp when execution completed */
+        readonly timestamp: Date;
+        /** Additional metadata */
+        readonly [key: string]: unknown;
+    };
+}
+/**
+ * Tool error information
+ * @interface ToolError
+ */
+export interface ToolError {
+    /** Error code for programmatic handling */
+    readonly code: ToolErrorCode;
+    /** Human-readable error message */
+    readonly message: string;
+    /** Additional error details */
+    readonly details?: Readonly<Record<string, unknown>>;
+    /** Original error if wrapped */
+    readonly cause?: Error;
+}
+/**
+ * Standard tool error codes
+ * @typedef {'validation_error' | 'execution_error' | 'timeout_error' | 'cancelled_error' | 'permission_error' | 'not_found_error' | 'rate_limit_error' | 'internal_error'} ToolErrorCode
+ */
+export type ToolErrorCode = 'validation_error' | 'execution_error' | 'timeout_error' | 'cancelled_error' | 'permission_error' | 'not_found_error' | 'rate_limit_error' | 'internal_error';
+/**
+ * Tool parameter definitions mapping
+ * @type ToolParameters
+ */
+export type ToolParameters = Readonly<Record<string, ToolParameterSchema>>;
+/**
+ * Abstract base class for all runtime tools
+ * @abstract
+ * @class Tool
+ *
+ * @example
+ * ```typescript
+ * class MyTool extends Tool<{ input: string }, { output: string }> {
+ *   name = 'my_tool';
+ *   description = 'A sample tool';
+ *   parameters = {
+ *     input: {
+ *       type: 'string',
+ *       description: 'Input text',
+ *       required: true
+ *     }
+ *   };
+ *
+ *   async execute(args: { input: string }, context: ToolContext): Promise<ToolResult<{ output: string }>> {
+ *     return {
+ *       success: true,
+ *       data: { output: args.input.toUpperCase() },
+ *       metadata: { duration: 0, timestamp: new Date() }
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class Tool<TArgs = Record<string, unknown>, TResult = unknown> {
+    /**
+     * Unique tool identifier (kebab-case or snake_case)
+     * @abstract
+     * @readonly
+     */
+    abstract readonly name: string;
+    /**
+     * Human-readable description of what the tool does
+     * @abstract
+     * @readonly
+     */
+    abstract readonly description: string;
+    /**
+     * Parameter schema definitions for validation and documentation
+     * @abstract
+     * @readonly
+     */
+    abstract readonly parameters: ToolParameters;
+    /**
+     * Execute the tool with the given arguments and context
+     * @abstract
+     * @param {TArgs} args - Validated tool arguments
+     * @param {ToolContext} context - Execution context
+     * @returns {Promise<ToolResult<TResult>>} Tool execution result
+     * @throws {never} Should never throw; errors should be returned as ToolResult with success: false
+     */
+    abstract execute(args: TArgs, context: ToolContext): Promise<ToolResult<TResult>>;
+    /**
+     * Validate tool arguments against the parameter schema
+     * @param {unknown} args - Arguments to validate
+     * @returns {{ valid: true } | { valid: false; errors: readonly string[] }} Validation result
+     */
+    validate(args: unknown): {
+        valid: true;
+    } | {
+        valid: false;
+        errors: readonly string[];
+    };
+    /**
+     * Get the JSON Schema representation of this tool
+     * @returns {ToolSchema} Complete JSON Schema for the tool
+     */
+    getSchema(): ToolSchema;
+    /**
+     * Validate a single parameter value against its schema
+     * @private
+     * @param {string} key - Parameter name
+     * @param {unknown} value - Parameter value
+     * @param {ToolParameterSchema} schema - Parameter schema
+     * @returns {string | null} Error message or null if valid
+     */
+    private validateType;
+    /**
+     * Execute with automatic validation (helper method)
+     * @param {unknown} args - Raw arguments to validate and execute
+     * @param {ToolContext} context - Execution context
+     * @returns {Promise<ToolResult<TResult>>} Tool execution result
+     */
+    executeWithValidation(args: unknown, context: ToolContext): Promise<ToolResult<TResult>>;
+}
+/**
+ * Type guard to check if a value is a ToolError
+ * @param {unknown} value - Value to check
+ * @returns {boolean} True if the value is a ToolError
+ */
+export declare function isToolError(value: unknown): value is ToolError;
+/**
+ * Create a successful tool result
+ * @template T
+ * @param {T} data - Result data
+ * @param {Partial<ToolResult<T>['metadata']>} metadata - Optional metadata
+ * @returns {ToolResult<T>} Successful tool result
+ */
+export declare function createSuccessResult<T>(data: T, metadata?: Partial<ToolResult<T>['metadata']>): ToolResult<T>;
+/**
+ * Create an error tool result
+ * @param {ToolErrorCode} code - Error code
+ * @param {string} message - Error message
+ * @param {Partial<ToolError>} details - Additional error details
+ * @returns {ToolResult<never>} Error tool result
+ */
+export declare function createErrorResult(code: ToolErrorCode, message: string, details?: Partial<ToolError>): ToolResult<never>;
+export default Tool;

package/src/runtime/tools/Tool.js

@@ -0,0 +1,285 @@
+/**
+ * @fileoverview Runtime tool base class and interfaces
+ * @module runtime/tools/Tool
+ *
+ * Defines the abstract base class for all runtime tools, providing
+ * a standardized interface for tool execution, validation, and schema generation.
+ * All tools in the gizzi-code runtime must extend this base class.
+ */
+/**
+ * Abstract base class for all runtime tools
+ * @abstract
+ * @class Tool
+ *
+ * @example
+ * ```typescript
+ * class MyTool extends Tool<{ input: string }, { output: string }> {
+ *   name = 'my_tool';
+ *   description = 'A sample tool';
+ *   parameters = {
+ *     input: {
+ *       type: 'string',
+ *       description: 'Input text',
+ *       required: true
+ *     }
+ *   };
+ *
+ *   async execute(args: { input: string }, context: ToolContext): Promise<ToolResult<{ output: string }>> {
+ *     return {
+ *       success: true,
+ *       data: { output: args.input.toUpperCase() },
+ *       metadata: { duration: 0, timestamp: new Date() }
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export class Tool {
+    /**
+     * Validate tool arguments against the parameter schema
+     * @param {unknown} args - Arguments to validate
+     * @returns {{ valid: true } | { valid: false; errors: readonly string[] }} Validation result
+     */
+    validate(args) {
+        if (args === null || typeof args !== 'object') {
+            return { valid: false, errors: ['Arguments must be an object'] };
+        }
+        const errors = [];
+        const argsRecord = args;
+        for (const [key, schema] of Object.entries(this.parameters)) {
+            const value = argsRecord[key];
+            // Check required fields
+            if (schema.required !== false && value === undefined) {
+                errors.push(`Missing required parameter: ${key}`);
+                continue;
+            }
+            // Skip validation for undefined optional fields
+            if (value === undefined) {
+                continue;
+            }
+            // Type validation
+            const typeError = this.validateType(key, value, schema);
+            if (typeError) {
+                errors.push(typeError);
+            }
+            // Enum validation
+            if (schema.enum && !schema.enum.includes(value)) {
+                errors.push(`Parameter ${key} must be one of: ${schema.enum.join(', ')}`);
+            }
+        }
+        // Check for unknown parameters
+        const knownKeys = Object.keys(this.parameters);
+        const unknownKeys = Object.keys(argsRecord).filter((k) => !knownKeys.includes(k));
+        if (unknownKeys.length > 0) {
+            errors.push(`Unknown parameters: ${unknownKeys.join(', ')}`);
+        }
+        return errors.length === 0 ? { valid: true } : { valid: false, errors };
+    }
+    /**
+     * Get the JSON Schema representation of this tool
+     * @returns {ToolSchema} Complete JSON Schema for the tool
+     */
+    getSchema() {
+        const required = Object.entries(this.parameters)
+            .filter(([, schema]) => schema.required !== false)
+            .map(([key]) => key);
+        return {
+            name: this.name,
+            description: this.description,
+            schema: 'http://json-schema.org/draft-07/schema#',
+            parameters: {
+                type: 'object',
+                properties: this.parameters,
+                required,
+                additionalProperties: false,
+            },
+        };
+    }
+    /**
+     * Validate a single parameter value against its schema
+     * @private
+     * @param {string} key - Parameter name
+     * @param {unknown} value - Parameter value
+     * @param {ToolParameterSchema} schema - Parameter schema
+     * @returns {string | null} Error message or null if valid
+     */
+    validateType(key, value, schema) {
+        const expectedType = schema.type;
+        switch (expectedType) {
+            case 'string':
+                if (typeof value !== 'string') {
+                    return `Parameter ${key} must be a string`;
+                }
+                break;
+            case 'number':
+            case 'integer':
+                if (typeof value !== 'number' || Number.isNaN(value)) {
+                    return `Parameter ${key} must be a number`;
+                }
+                if (expectedType === 'integer' && !Number.isInteger(value)) {
+                    return `Parameter ${key} must be an integer`;
+                }
+                break;
+            case 'boolean':
+                if (typeof value !== 'boolean') {
+                    return `Parameter ${key} must be a boolean`;
+                }
+                break;
+            case 'array':
+                if (!Array.isArray(value)) {
+                    return `Parameter ${key} must be an array`;
+                }
+                if (schema.items) {
+                    for (let i = 0; i < value.length; i++) {
+                        const itemError = this.validateType(`${key}[${i}]`, value[i], schema.items);
+                        if (itemError) {
+                            return itemError;
+                        }
+                    }
+                }
+                break;
+            case 'object':
+                if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+                    return `Parameter ${key} must be an object`;
+                }
+                if (schema.properties) {
+                    const objValue = value;
+                    for (const [propKey, propSchema] of Object.entries(schema.properties)) {
+                        const propValue = objValue[propKey];
+                        if (propValue !== undefined) {
+                            const propError = this.validateType(`${key}.${propKey}`, propValue, propSchema);
+                            if (propError) {
+                                return propError;
+                            }
+                        }
+                    }
+                }
+                break;
+            default:
+                return `Unknown type for parameter ${key}: ${expectedType}`;
+        }
+        return null;
+    }
+    /**
+     * Execute with automatic validation (helper method)
+     * @param {unknown} args - Raw arguments to validate and execute
+     * @param {ToolContext} context - Execution context
+     * @returns {Promise<ToolResult<TResult>>} Tool execution result
+     */
+    async executeWithValidation(args, context) {
+        const startTime = performance.now();
+        const timestamp = new Date();
+        // Validate arguments
+        const validation = this.validate(args);
+        if (!validation.valid) {
+            return {
+                success: false,
+                error: {
+                    code: 'validation_error',
+                    message: `Validation failed: ${validation.errors.join(', ')}`,
+                    details: { errors: validation.errors },
+                },
+                metadata: {
+                    duration: Math.round(performance.now() - startTime),
+                    timestamp,
+                },
+            };
+        }
+        // Check for cancellation before execution
+        if (context.signal?.aborted) {
+            return {
+                success: false,
+                error: {
+                    code: 'cancelled_error',
+                    message: 'Tool execution was cancelled',
+                },
+                metadata: {
+                    duration: Math.round(performance.now() - startTime),
+                    timestamp,
+                },
+            };
+        }
+        try {
+            const result = await this.execute(args, context);
+            // Add metadata if not present
+            if (!result.metadata) {
+                return {
+                    ...result,
+                    metadata: {
+                        duration: Math.round(performance.now() - startTime),
+                        timestamp,
+                    },
+                };
+            }
+            return result;
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: {
+                    code: 'execution_error',
+                    message: error instanceof Error ? error.message : 'Unknown error occurred',
+                    cause: error instanceof Error ? error : undefined,
+                },
+                metadata: {
+                    duration: Math.round(performance.now() - startTime),
+                    timestamp,
+                },
+            };
+        }
+    }
+}
+/**
+ * Type guard to check if a value is a ToolError
+ * @param {unknown} value - Value to check
+ * @returns {boolean} True if the value is a ToolError
+ */
+export function isToolError(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'code' in value &&
+        'message' in value &&
+        typeof value.code === 'string' &&
+        typeof value.message === 'string');
+}
+/**
+ * Create a successful tool result
+ * @template T
+ * @param {T} data - Result data
+ * @param {Partial<ToolResult<T>['metadata']>} metadata - Optional metadata
+ * @returns {ToolResult<T>} Successful tool result
+ */
+export function createSuccessResult(data, metadata) {
+    return {
+        success: true,
+        data,
+        metadata: {
+            duration: 0,
+            timestamp: new Date(),
+            ...metadata,
+        },
+    };
+}
+/**
+ * Create an error tool result
+ * @param {ToolErrorCode} code - Error code
+ * @param {string} message - Error message
+ * @param {Partial<ToolError>} details - Additional error details
+ * @returns {ToolResult<never>} Error tool result
+ */
+export function createErrorResult(code, message, details) {
+    return {
+        success: false,
+        error: {
+            code,
+            message,
+            ...details,
+        },
+        metadata: {
+            duration: 0,
+            timestamp: new Date(),
+        },
+    };
+}
+// Default export
+export default Tool;