@hashgraphonline/conversational-agent 0.1.214 → 0.1.217

package/src/core/ToolRegistry.ts

@@ -0,0 +1,358 @@
+import { StructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+import { Logger } from '@hashgraphonline/standards-sdk';
+import {
+  FormValidatingToolWrapper,
+  wrapToolWithFormValidation,
+} from '../langchain/FormValidatingToolWrapper';
+import { FormGenerator } from '../forms/form-generator';
+import { isFormValidatable } from '@hashgraphonline/standards-agent-kit';
+
+/**
+ * Tool capabilities configuration for registry entries
+ */
+export interface ToolCapabilities {
+  supportsFormValidation: boolean;
+  requiresWrapper: boolean;
+  priority: 'low' | 'medium' | 'high' | 'critical';
+  category: 'core' | 'extension' | 'mcp';
+}
+
+/**
+ * Tool metadata for comprehensive tool information
+ */
+export interface ToolMetadata {
+  name: string;
+  version: string;
+  category: ToolCapabilities['category'];
+  description: string;
+  capabilities: ToolCapabilities;
+  dependencies: string[];
+  schema: unknown;
+}
+
+/**
+ * Registry entry containing tool instance and metadata
+ */
+export interface ToolRegistryEntry {
+  tool: StructuredTool;
+  metadata: ToolMetadata;
+  wrapper?: FormValidatingToolWrapper<z.ZodObject<z.ZodRawShape>> | undefined;
+  originalTool: StructuredTool;
+}
+
+/**
+ * Options for tool registration
+ */
+export interface ToolRegistrationOptions {
+  forceWrapper?: boolean;
+  skipWrapper?: boolean;
+  wrapperConfig?: {
+    requireAllFields?: boolean;
+    skipFields?: string[];
+  };
+  metadata?: Partial<ToolMetadata>;
+}
+
+/**
+ * Query interface for finding tools
+ */
+export interface ToolQuery {
+  name?: string;
+  category?: ToolMetadata['category'];
+  capabilities?: Partial<ToolCapabilities>;
+}
+
+/**
+ * Centralized tool registry for managing tool lifecycle
+ */
+export class ToolRegistry {
+  private tools = new Map<string, ToolRegistryEntry>();
+  private formGenerator: FormGenerator;
+  private logger: Logger;
+
+  constructor(logger?: Logger) {
+    this.formGenerator = new FormGenerator();
+    this.logger = logger || new Logger({ module: 'ToolRegistry' });
+  }
+
+  /**
+   * Register a tool with the registry
+   */
+  registerTool(
+    tool: StructuredTool,
+    options: ToolRegistrationOptions = {}
+  ): void {
+    const capabilities = this.analyzeToolCapabilities(tool);
+    const metadata: ToolMetadata = {
+      name: tool.name,
+      version: '1.0.0',
+      category: options.metadata?.category || 'core',
+      description: tool.description,
+      capabilities,
+      dependencies: [],
+      schema: tool.schema,
+      ...options.metadata,
+    };
+
+    let finalTool: StructuredTool = tool;
+    let wrapper:
+      | FormValidatingToolWrapper<z.ZodObject<z.ZodRawShape>>
+      | undefined;
+
+    if (this.shouldWrapTool(tool, capabilities, options)) {
+      wrapper = wrapToolWithFormValidation(
+        tool as StructuredTool<z.ZodObject<z.ZodRawShape>>,
+        this.formGenerator,
+        {
+          requireAllFields: false,
+          skipFields: ['metaOptions'],
+          ...options.wrapperConfig,
+        }
+      ) as FormValidatingToolWrapper<z.ZodObject<z.ZodRawShape>>;
+      finalTool = wrapper as StructuredTool;
+    }
+
+    const entry: ToolRegistryEntry = {
+      tool: finalTool,
+      metadata,
+      wrapper,
+      originalTool: tool,
+    };
+
+    this.tools.set(tool.name, entry);
+  }
+
+  /**
+   * Get a tool by name
+   */
+  getTool(name: string): ToolRegistryEntry | null {
+    return this.tools.get(name) || null;
+  }
+
+  /**
+   * Get tools by capability
+   */
+  getToolsByCapability(
+    capability: keyof ToolCapabilities,
+    value?: unknown
+  ): ToolRegistryEntry[] {
+    const results: ToolRegistryEntry[] = [];
+
+    for (const entry of this.tools.values()) {
+      if (value !== undefined) {
+        if (entry.metadata.capabilities[capability] === value) {
+          results.push(entry);
+        }
+      } else if (entry.metadata.capabilities[capability]) {
+        results.push(entry);
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Get tools by query
+   */
+  getToolsByQuery(query: ToolQuery): ToolRegistryEntry[] {
+    const results: ToolRegistryEntry[] = [];
+
+    for (const entry of this.tools.values()) {
+      let matches = true;
+
+      if (query.name && entry.metadata.name !== query.name) {
+        matches = false;
+      }
+
+      if (query.category && entry.metadata.category !== query.category) {
+        matches = false;
+      }
+
+      if (query.capabilities) {
+        for (const [key, value] of Object.entries(query.capabilities)) {
+          if (
+            entry.metadata.capabilities[key as keyof ToolCapabilities] !== value
+          ) {
+            matches = false;
+            break;
+          }
+        }
+      }
+
+      if (matches) {
+        results.push(entry);
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Get all registered tools
+   */
+  getAllTools(): StructuredTool[] {
+    return Array.from(this.tools.values()).map((entry) => entry.tool);
+  }
+
+  /**
+   * Get all registry entries
+   */
+  getAllRegistryEntries(): ToolRegistryEntry[] {
+    return Array.from(this.tools.values());
+  }
+
+  /**
+   * Get all tool names
+   */
+  getToolNames(): string[] {
+    return Array.from(this.tools.keys());
+  }
+
+  /**
+   * Check if a tool is registered
+   */
+  hasTool(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  /**
+   * Unregister a tool
+   */
+  unregisterTool(name: string): boolean {
+    return this.tools.delete(name);
+  }
+
+  /**
+   * Clear all tools
+   */
+  clear(): void {
+    this.tools.clear();
+  }
+
+  /**
+   * Analyze tool capabilities
+   */
+  private analyzeToolCapabilities(tool: StructuredTool): ToolCapabilities {
+    const implementsFormValidatable = isFormValidatable(tool);
+    const hasRenderConfig = this.hasRenderConfig(tool);
+    const isZodObjectLike = this.isZodObjectLike(tool.schema);
+
+    const supportsFormValidation = implementsFormValidatable || hasRenderConfig;
+    const requiresWrapper = supportsFormValidation && isZodObjectLike;
+
+    let priority: ToolCapabilities['priority'] = 'medium';
+    let category: ToolCapabilities['category'] = 'core';
+
+    if (supportsFormValidation && requiresWrapper) {
+      priority = 'critical';
+    } else if (supportsFormValidation) {
+      priority = 'high';
+    } else if (
+      tool.description?.toLowerCase().includes('query') ||
+      tool.description?.toLowerCase().includes('search')
+    ) {
+      priority = 'low';
+    }
+
+    const toolAsAny = tool as unknown as Record<string, unknown>;
+    if (tool.constructor.name.includes('MCP') || toolAsAny.isMCPTool) {
+      category = 'mcp';
+    } else if (
+      toolAsAny.isExtension ||
+      tool.constructor.name.includes('Extension')
+    ) {
+      category = 'extension';
+    }
+
+    return {
+      supportsFormValidation,
+      requiresWrapper,
+      priority,
+      category,
+    };
+  }
+
+  /**
+   * Check if tool has render configuration
+   */
+  private hasRenderConfig(tool: StructuredTool): boolean {
+    const schema = tool.schema as Record<string, unknown>;
+    return !!(schema && schema._renderConfig);
+  }
+
+  /**
+   * Determine if tool should be wrapped
+   */
+  private shouldWrapTool(
+    tool: StructuredTool,
+    capabilities: ToolCapabilities,
+    options: ToolRegistrationOptions
+  ): boolean {
+    if (options.skipWrapper) {
+      return false;
+    }
+
+    if (options.forceWrapper) {
+      return true;
+    }
+
+    return capabilities.requiresWrapper;
+  }
+
+  /**
+   * Check if schema is ZodObject-like
+   */
+  private isZodObjectLike(schema: unknown): boolean {
+    if (!schema || typeof schema !== 'object') {
+      return false;
+    }
+
+    const schemaRecord = schema as Record<string, unknown>;
+    const schemaDef = schemaRecord._def as Record<string, unknown> | undefined;
+
+    return (
+      schema instanceof z.ZodObject ||
+      schemaDef?.typeName === 'ZodObject' ||
+      ('shape' in schemaRecord && typeof schemaRecord.shape === 'object')
+    );
+  }
+
+  /**
+   * Get statistics about the registry
+   */
+  getStatistics(): {
+    totalTools: number;
+    wrappedTools: number;
+    unwrappedTools: number;
+    categoryCounts: Record<ToolCapabilities['category'], number>;
+    priorityCounts: Record<ToolCapabilities['priority'], number>;
+  } {
+    const stats = {
+      totalTools: this.tools.size,
+      wrappedTools: 0,
+      unwrappedTools: 0,
+      categoryCounts: { core: 0, extension: 0, mcp: 0 } as Record<
+        ToolCapabilities['category'],
+        number
+      >,
+      priorityCounts: { low: 0, medium: 0, high: 0, critical: 0 } as Record<
+        ToolCapabilities['priority'],
+        number
+      >,
+    };
+
+    for (const entry of this.tools.values()) {
+      if (entry.wrapper) {
+        stats.wrappedTools++;
+      } else {
+        stats.unwrappedTools++;
+      }
+
+      stats.categoryCounts[entry.metadata.category]++;
+      stats.priorityCounts[entry.metadata.capabilities.priority]++;
+    }
+
+    return stats;
+  }
+}

package/src/execution/ExecutionPipeline.ts

@@ -0,0 +1,301 @@
+import { ZodError } from 'zod';
+import { Logger } from '@hashgraphonline/standards-sdk';
+import { SmartMemoryManager } from '../memory/SmartMemoryManager';
+import { FormEngine, ToolExecutionResult } from '../forms/FormEngine';
+import type { FormMessage, FormSubmission } from '../forms/types';
+import type { ToolRegistry, ToolRegistryEntry } from '../core/ToolRegistry';
+
+/**
+ * Session context for tool execution
+ */
+export interface SessionContext {
+  sessionId: string;
+  userId?: string;
+  timestamp: number;
+  conversationId?: string;
+}
+
+/**
+ * Context passed through execution pipeline
+ */
+export interface ExecutionContext {
+  toolName: string;
+  input: unknown;
+  session: SessionContext;
+  memory: SmartMemoryManager;
+  traceId: string;
+  toolEntry: ToolRegistryEntry;
+}
+
+/**
+ * Result of tool execution with metadata
+ */
+export interface ExecutionResult extends ToolExecutionResult {
+  traceId: string;
+  executionTime: number;
+}
+
+/**
+ * ExecutionPipeline handles tool execution coordination
+ */
+export class ExecutionPipeline {
+  private logger: Logger;
+  private toolRegistry: ToolRegistry;
+  private formEngine: FormEngine;
+  private memory: SmartMemoryManager;
+
+  constructor(
+    toolRegistry: ToolRegistry,
+    formEngine: FormEngine,
+    memory: SmartMemoryManager,
+    logger?: Logger
+  ) {
+    this.toolRegistry = toolRegistry;
+    this.formEngine = formEngine;
+    this.memory = memory;
+    this.logger = logger || new Logger({ module: 'ExecutionPipeline' });
+  }
+
+  /**
+   * Execute a tool through the pipeline
+   */
+  async execute(
+    toolName: string,
+    input: unknown,
+    sessionContext?: SessionContext
+  ): Promise<ExecutionResult> {
+    const traceId = `trace-${Date.now()}-${Math.random()
+      .toString(36)
+      .substr(2, 9)}`;
+    const startTime = Date.now();
+
+    const toolEntry = this.toolRegistry.getTool(toolName);
+    if (!toolEntry) {
+      throw new Error(`Tool not found in registry: ${toolName}`);
+    }
+
+    const context: ExecutionContext = {
+      toolName,
+      input,
+      session: sessionContext || this.buildDefaultSession(),
+      memory: this.memory,
+      traceId,
+      toolEntry,
+    };
+
+    try {
+      const shouldGenerateForm = await this.checkFormGeneration(context);
+      if (shouldGenerateForm.requiresForm && shouldGenerateForm.formMessage) {
+        return {
+          success: false,
+          output: 'Form generation required',
+          requiresForm: true,
+          formMessage: shouldGenerateForm.formMessage,
+          traceId,
+          executionTime: Date.now() - startTime,
+        };
+      }
+
+      const result = await this.executeToolDirect(context);
+
+      return {
+        success: true,
+        output: result,
+        traceId,
+        executionTime: Date.now() - startTime,
+      };
+    } catch (error) {
+      return this.handleExecutionError(
+        error,
+        context,
+        traceId,
+        Date.now() - startTime
+      );
+    }
+  }
+
+  /**
+   * Execute tool with validation
+   */
+  async executeWithValidation(
+    toolName: string,
+    input: unknown,
+    sessionContext?: SessionContext
+  ): Promise<ExecutionResult> {
+    return this.execute(toolName, input, sessionContext);
+  }
+
+  /**
+   * Process form submission
+   */
+  async processFormSubmission(
+    toolName: string,
+    formId: string,
+    parameters: Record<string, unknown>,
+    sessionContext?: SessionContext
+  ): Promise<ExecutionResult> {
+    const traceId = `form-${Date.now()}-${Math.random()
+      .toString(36)
+      .substr(2, 9)}`;
+    const startTime = Date.now();
+
+    try {
+      const formSubmission: FormSubmission = {
+        formId,
+        toolName,
+        parameters,
+        timestamp: Date.now(),
+      };
+
+      const processedInput = await this.formEngine.processSubmission(
+        formSubmission
+      );
+
+      return this.execute(toolName, processedInput, sessionContext);
+    } catch (error) {
+      return {
+        success: false,
+        output: 'Form submission processing failed',
+        error: error instanceof Error ? error.message : String(error),
+        traceId,
+        executionTime: Date.now() - startTime,
+      };
+    }
+  }
+
+  /**
+   * Check if form generation is required
+   */
+  private async checkFormGeneration(context: ExecutionContext): Promise<{
+    requiresForm: boolean;
+    formMessage?: FormMessage;
+  }> {
+    const inputRecord = context.input as Record<string, unknown>;
+    if (inputRecord?.__fromForm === true || inputRecord?.renderForm === false) {
+      return { requiresForm: false };
+    }
+
+    if (
+      !this.formEngine.shouldGenerateForm(context.toolEntry.tool, context.input)
+    ) {
+      return { requiresForm: false };
+    }
+
+    const formMessage = await this.formEngine.generateForm(
+      context.toolName,
+      context.toolEntry.tool,
+      context.input
+    );
+
+    if (formMessage) {
+      return { requiresForm: true, formMessage };
+    }
+
+    return { requiresForm: false };
+  }
+
+  /**
+   * Execute tool directly
+   */
+  private async executeToolDirect(context: ExecutionContext): Promise<string> {
+    const { toolEntry, input } = context;
+    const parameters = (input as Record<string, unknown>) || {};
+    const mergedArgs = { ...parameters, renderForm: false };
+
+    if (toolEntry.wrapper) {
+      return this.executeWrappedTool(toolEntry, mergedArgs);
+    }
+
+    return await toolEntry.tool.call(mergedArgs);
+  }
+
+  /**
+   * Execute wrapped tool
+   */
+  private async executeWrappedTool(
+    toolEntry: ToolRegistryEntry,
+    mergedArgs: Record<string, unknown>
+  ): Promise<string> {
+    const wrapper = toolEntry.wrapper;
+    if (!wrapper) {
+      throw new Error('Tool wrapper not found');
+    }
+
+    const wrapperAsAny = wrapper as unknown as {
+      executeOriginal?: (args: Record<string, unknown>) => Promise<string>;
+      originalTool?: {
+        call?: (args: Record<string, unknown>) => Promise<string>;
+      };
+    };
+
+    if (wrapperAsAny.executeOriginal) {
+      return await wrapperAsAny.executeOriginal(mergedArgs);
+    }
+
+    if (wrapperAsAny.originalTool?.call) {
+      return await wrapperAsAny.originalTool.call(mergedArgs);
+    }
+
+    return await toolEntry.originalTool.call(mergedArgs);
+  }
+
+  /**
+   * Handle execution error
+   */
+  private handleExecutionError(
+    error: unknown,
+    context: ExecutionContext,
+    traceId: string,
+    executionTime: number
+  ): ExecutionResult {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+
+    if (error instanceof ZodError) {
+      return {
+        success: false,
+        output: 'Validation error occurred',
+        error: errorMessage,
+        traceId,
+        executionTime,
+      };
+    }
+
+    this.logger.error(`Tool execution failed: ${context.toolName}`, {
+      traceId,
+      error: errorMessage,
+    });
+
+    return {
+      success: false,
+      output: 'Tool execution failed',
+      error: errorMessage,
+      traceId,
+      executionTime,
+    };
+  }
+
+  /**
+   * Build default session context
+   */
+  private buildDefaultSession(): SessionContext {
+    return {
+      sessionId: `session-${Date.now()}-${Math.random()
+        .toString(36)
+        .substr(2, 9)}`,
+      timestamp: Date.now(),
+    };
+  }
+
+  /**
+   * Get statistics about the pipeline
+   */
+  getStatistics(): {
+    totalMiddleware: number;
+    registeredMiddleware: string[];
+  } {
+    return {
+      totalMiddleware: 0,
+      registeredMiddleware: [],
+    };
+  }
+}