@allternit/gizzi-code 1.0.0 → 1.0.1

package/src/runtime/tools/Tool.ts

@@ -1,524 +0,0 @@
-/**
- * @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 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[] } {
-    if (args === null || typeof args !== 'object') {
-      return { valid: false, errors: ['Arguments must be an object'] };
-    }
-
-    const errors: string[] = [];
-    const argsRecord = args as Record<string, unknown>;
-
-    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(): ToolSchema {
-    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
-   */
-  private validateType(
-    key: string,
-    value: unknown,
-    schema: ToolParameterSchema
-  ): string | null {
-    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 as Record<string, unknown>;
-          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: unknown,
-    context: ToolContext
-  ): Promise<ToolResult<TResult>> {
-    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 as TArgs, 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: unknown): value is ToolError {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'code' in value &&
-    'message' in value &&
-    typeof (value as ToolError).code === 'string' &&
-    typeof (value as ToolError).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<T>(
-  data: T,
-  metadata?: Partial<ToolResult<T>['metadata']>
-): ToolResult<T> {
-  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: ToolErrorCode,
-  message: string,
-  details?: Partial<ToolError>
-): ToolResult<never> {
-  return {
-    success: false,
-    error: {
-      code,
-      message,
-      ...details,
-    },
-    metadata: {
-      duration: 0,
-      timestamp: new Date(),
-    },
-  };
-}
-
-// Default export
-export default Tool;

package/src/scheduler/TaskScheduler.d.ts

@@ -1,98 +0,0 @@
-/**
- * Gizzi Task Scheduler
- *
- * Manages recurring tasks from HEARTBEAT.md
- * - Daily tasks: Run every 24 hours
- * - Weekly tasks: Run every 7 days
- * - Monthly tasks: Run every 30 days
- */
-export type TaskFrequency = 'startup' | 'daily' | 'weekly' | 'monthly';
-export interface ScheduledTask {
-    id: string;
-    action: string;
-    frequency: TaskFrequency;
-    completed: boolean;
-    lastRun?: Date;
-    nextRun?: Date;
-}
-export interface SchedulerJob {
-    id: string;
-    taskId: string;
-    agentId: string;
-    frequency: TaskFrequency;
-    nextRunAt: number;
-    lastRunAt?: number;
-    enabled: boolean;
-}
-/**
- * Task Scheduler for Gizzi
- */
-export declare class TaskScheduler {
-    private jobs;
-    private intervalId;
-    private checkIntervalMs;
-    private isRunning;
-    private onTaskExecute?;
-    constructor(options?: {
-        checkIntervalMs?: number;
-        onTaskExecute?: (task: SchedulerJob) => Promise<void>;
-    });
-    /**
-     * Start the scheduler
-     */
-    start(): void;
-    /**
-     * Stop the scheduler
-     */
-    stop(): void;
-    /**
-     * Register tasks from HEARTBEAT.md
-     */
-    registerTasks(agentId: string, tasks: ScheduledTask[]): void;
-    /**
-     * Unregister all tasks for an agent
-     */
-    unregisterAgentTasks(agentId: string): void;
-    /**
-     * Get all jobs
-     */
-    getJobs(): SchedulerJob[];
-    /**
-     * Get jobs for a specific agent
-     */
-    getJobsForAgent(agentId: string): SchedulerJob[];
-    /**
-     * Get jobs that are due for execution
-     */
-    getDueJobs(): SchedulerJob[];
-    /**
-     * Get scheduler status
-     */
-    getStatus(): {
-        isRunning: boolean;
-        totalJobs: number;
-        dueJobs: number;
-        nextJob: SchedulerJob | null;
-    };
-    /**
-     * Enable a job
-     */
-    enableJob(jobId: string): void;
-    /**
-     * Disable a job
-     */
-    disableJob(jobId: string): void;
-    /**
-     * Record job execution
-     */
-    recordExecution(jobId: string, success: boolean): void;
-    /**
-     * Check and execute due jobs
-     */
-    private checkAndExecuteJobs;
-    /**
-     * Execute a single job
-     */
-    private executeJob;
-}
-export declare const taskScheduler: TaskScheduler;