@hashgraphonline/conversational-agent 0.1.215 → 0.1.217

package/dist/cjs/conversational-agent.d.ts

@@ -10,6 +10,7 @@ import { IStateManager } from '@hashgraphonline/standards-agent-kit';
 import { MCPServerConfig, MCPConnectionStatus } from './mcp/types';
 import { ContentStoreManager } from './services/ContentStoreManager';
 import { SmartMemoryManager, SmartMemoryConfig } from './memory';
+import { FormSubmission } from './forms/types';
 
 export type ToolDescriptor = {
     name: string;
@@ -107,6 +108,13 @@ export declare class ConversationalAgent {
      * @throws {Error} If agent is not initialized
      */
     processMessage(message: string, chatHistory?: ChatHistoryItem[]): Promise<ChatResponse>;
+    /**
+     * Process form submission through the conversational agent
+     * @param {FormSubmission} submission - The form submission data
+     * @returns {Promise<ChatResponse>} The agent's response after processing the form
+     * @throws {Error} If agent is not initialized or doesn't support form processing
+     */
+    processFormSubmission(submission: FormSubmission): Promise<ChatResponse>;
     /**
      * Validates initialization options and throws if required fields are missing.
      *

package/dist/cjs/core/ToolRegistry.d.ts

@@ -0,0 +1,130 @@
+import { StructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+import { Logger } from '@hashgraphonline/standards-sdk';
+import { FormValidatingToolWrapper } from '../langchain/FormValidatingToolWrapper';
+
+/**
+ * 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 declare class ToolRegistry {
+    private tools;
+    private formGenerator;
+    private logger;
+    constructor(logger?: Logger);
+    /**
+     * Register a tool with the registry
+     */
+    registerTool(tool: StructuredTool, options?: ToolRegistrationOptions): void;
+    /**
+     * Get a tool by name
+     */
+    getTool(name: string): ToolRegistryEntry | null;
+    /**
+     * Get tools by capability
+     */
+    getToolsByCapability(capability: keyof ToolCapabilities, value?: unknown): ToolRegistryEntry[];
+    /**
+     * Get tools by query
+     */
+    getToolsByQuery(query: ToolQuery): ToolRegistryEntry[];
+    /**
+     * Get all registered tools
+     */
+    getAllTools(): StructuredTool[];
+    /**
+     * Get all registry entries
+     */
+    getAllRegistryEntries(): ToolRegistryEntry[];
+    /**
+     * Get all tool names
+     */
+    getToolNames(): string[];
+    /**
+     * Check if a tool is registered
+     */
+    hasTool(name: string): boolean;
+    /**
+     * Unregister a tool
+     */
+    unregisterTool(name: string): boolean;
+    /**
+     * Clear all tools
+     */
+    clear(): void;
+    /**
+     * Analyze tool capabilities
+     */
+    private analyzeToolCapabilities;
+    /**
+     * Check if tool has render configuration
+     */
+    private hasRenderConfig;
+    /**
+     * Determine if tool should be wrapped
+     */
+    private shouldWrapTool;
+    /**
+     * Check if schema is ZodObject-like
+     */
+    private isZodObjectLike;
+    /**
+     * Get statistics about the registry
+     */
+    getStatistics(): {
+        totalTools: number;
+        wrappedTools: number;
+        unwrappedTools: number;
+        categoryCounts: Record<ToolCapabilities['category'], number>;
+        priorityCounts: Record<ToolCapabilities['priority'], number>;
+    };
+}

package/dist/cjs/execution/ExecutionPipeline.d.ts

@@ -0,0 +1,81 @@
+import { Logger } from '@hashgraphonline/standards-sdk';
+import { SmartMemoryManager } from '../memory/SmartMemoryManager';
+import { FormEngine, ToolExecutionResult } from '../forms/FormEngine';
+import { 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 declare class ExecutionPipeline {
+    private logger;
+    private toolRegistry;
+    private formEngine;
+    private memory;
+    constructor(toolRegistry: ToolRegistry, formEngine: FormEngine, memory: SmartMemoryManager, logger?: Logger);
+    /**
+     * Execute a tool through the pipeline
+     */
+    execute(toolName: string, input: unknown, sessionContext?: SessionContext): Promise<ExecutionResult>;
+    /**
+     * Execute tool with validation
+     */
+    executeWithValidation(toolName: string, input: unknown, sessionContext?: SessionContext): Promise<ExecutionResult>;
+    /**
+     * Process form submission
+     */
+    processFormSubmission(toolName: string, formId: string, parameters: Record<string, unknown>, sessionContext?: SessionContext): Promise<ExecutionResult>;
+    /**
+     * Check if form generation is required
+     */
+    private checkFormGeneration;
+    /**
+     * Execute tool directly
+     */
+    private executeToolDirect;
+    /**
+     * Execute wrapped tool
+     */
+    private executeWrappedTool;
+    /**
+     * Handle execution error
+     */
+    private handleExecutionError;
+    /**
+     * Build default session context
+     */
+    private buildDefaultSession;
+    /**
+     * Get statistics about the pipeline
+     */
+    getStatistics(): {
+        totalMiddleware: number;
+        registeredMiddleware: string[];
+    };
+}

package/dist/cjs/forms/FormEngine.d.ts

@@ -0,0 +1,121 @@
+import { StructuredTool } from '@langchain/core/tools';
+import { ZodError, z } from 'zod';
+import { Logger } from '@hashgraphonline/standards-sdk';
+import { FormMessage, FormSubmission } from './types';
+
+/**
+ * Tool execution result with optional form requirement
+ */
+export interface ToolExecutionResult {
+    success: boolean;
+    output: string;
+    metadata?: Record<string, unknown>;
+    requiresForm?: boolean;
+    formMessage?: FormMessage;
+    error?: string;
+}
+/**
+ * Context for form generation operations
+ */
+export interface FormGenerationContext {
+    tool: StructuredTool;
+    input: unknown;
+    sessionId?: string;
+    userId?: string;
+    missingFields?: Set<string>;
+}
+/**
+ * FormEngine handles all form generation and validation logic
+ */
+export declare class FormEngine {
+    private formGenerator;
+    private logger;
+    constructor(logger?: Logger);
+    /**
+     * Generate a form for a tool with the given input
+     */
+    generateForm(toolName: string, tool: StructuredTool, input: unknown, context?: Partial<FormGenerationContext>): Promise<FormMessage | null>;
+    /**
+     * Process a form submission
+     */
+    processSubmission(submission: FormSubmission, context?: {
+        originalInput?: Record<string, unknown>;
+        schema?: unknown;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Check if a tool requires form generation based on input
+     */
+    shouldGenerateForm(tool: StructuredTool, input: unknown): boolean;
+    /**
+     * Generate form from error context
+     */
+    generateFormFromError(error: ZodError, toolName: string, toolSchema: z.ZodSchema, originalPrompt: string): Promise<FormMessage>;
+    /**
+     * Generate form for FormValidatable tools
+     */
+    private generateFormValidatableForm;
+    /**
+     * Generate form based on schema validation
+     */
+    private generateSchemaBasedForm;
+    /**
+     * Generate form based on render config
+     */
+    private generateRenderConfigForm;
+    /**
+     * Generate form from Zod validation error
+     */
+    private generateErrorBasedForm;
+    /**
+     * Validate input against tool schema
+     */
+    private validateInput;
+    /**
+     * Check if schema is ZodObject
+     */
+    private isZodObject;
+    /**
+     * Check if tool has render configuration
+     */
+    private hasRenderConfig;
+    /**
+     * Extract render configuration from tool
+     */
+    private extractRenderConfig;
+    /**
+     * Resolve form schema for FormValidatable tools
+     */
+    private resolveFormSchema;
+    /**
+     * Determine missing fields for form generation
+     */
+    private determineMissingFields;
+    /**
+     * Generate form with resolved schema
+     */
+    private generateFormWithSchema;
+    /**
+     * Validate form submission
+     */
+    private validateSubmission;
+    /**
+     * Extract base tool input from context
+     */
+    private extractBaseToolInput;
+    /**
+     * Extract submission data
+     */
+    private extractSubmissionData;
+    /**
+     * Merge input data
+     */
+    private mergeInputData;
+    /**
+     * Get registered strategies
+     */
+    getRegisteredStrategies(): string[];
+    /**
+     * Get registered middleware
+     */
+    getRegisteredMiddleware(): string[];
+}

package/dist/cjs/forms/form-generator.d.ts

@@ -21,12 +21,13 @@ export declare class FormGenerator {
      * @param schema The Zod schema to generate a form from
      * @param partialInput Any partial input already provided
      * @param context Additional context about the tool
+     * @param preCalculatedMissingFields Optional pre-calculated missing fields set. If undefined, includes all fields from schema.
      * @returns FormMessage to send to the chat UI
      */
-    generateFormFromSchema(schema: z.ZodSchema, partialInput: any, context: {
+    generateFormFromSchema(schema: z.ZodSchema, partialInput: unknown, context: {
         toolName: string;
         toolDescription?: string;
-    }): Promise<FormMessage>;
+    }, preCalculatedMissingFields?: Set<string>): Promise<FormMessage>;
     /**
      * Extracts validation errors from ZodError
      */
@@ -47,6 +48,22 @@ export declare class FormGenerator {
      * Safely generates field ordering from schema
      */
     private generateFieldOrderingSafely;
+    /**
+     * Determines field priority for progressive disclosure
+     */
+    private getFieldPriority;
+    /**
+     * Determines which fields should be included in the form
+     */
+    private determineFieldsToInclude;
+    /**
+     * Includes required fields that are missing
+     */
+    private includeRequiredMissingFields;
+    /**
+     * Creates form fields from ordered field names
+     */
+    private createOrderedFields;
     /**
      * Generates form fields from schema and validation errors
      */
@@ -67,6 +84,10 @@ export declare class FormGenerator {
      * Generates a title for the form
      */
     private generateFormTitle;
+    /**
+     * Safely extracts ZodObject from a schema, returns null if not an object schema
+     */
+    private extractZodObject;
     /**
      * Extracts field names from Zod schema structure
      */
@@ -83,4 +104,20 @@ export declare class FormGenerator {
      * Generates a description for the form
      */
     private generateFormDescription;
+    /**
+     * Generates JSON Schema and uiSchema from a Zod schema for use with @rjsf/core
+     * @param zodSchema The Zod schema to convert
+     * @param partialInput Existing input data to filter out fields that already have values
+     * @param missingFields Set of fields that are missing and should be shown
+     * @returns Object containing jsonSchema and uiSchema
+     */
+    generateJsonSchemaForm(zodSchema: z.ZodObject<z.ZodRawShape>, partialInput?: Record<string, unknown>, missingFields?: Set<string>): {
+        jsonSchema: import('zod-to-json-schema').JsonSchema7Type & {
+            $schema?: string | undefined;
+            definitions?: {
+                [key: string]: import('zod-to-json-schema').JsonSchema7Type;
+            } | undefined;
+        };
+        uiSchema: Record<string, Record<string, unknown>>;
+    };
 }

package/dist/cjs/forms/types.d.ts

@@ -1,5 +1,13 @@
 import { RenderConfigSchema } from '@hashgraphonline/standards-agent-kit';
 
+/**
+ * JSON Schema definition for form rendering
+ */
+export type JSONSchemaDefinition = Record<string, unknown>;
+/**
+ * UI Schema configuration for form rendering customization
+ */
+export type UISchemaDefinition = Record<string, unknown>;
 /**
  * Represents a form message that can be sent to the chat UI
  */
@@ -10,7 +18,9 @@ export interface FormMessage {
     originalPrompt: string;
     toolName: string;
     validationErrors?: ValidationError[];
-    partialInput?: any;
+    partialInput?: unknown;
+    jsonSchema?: JSONSchemaDefinition;
+    uiSchema?: UISchemaDefinition;
 }
 /**
  * Configuration for generating a form from Zod schema
@@ -75,8 +85,17 @@ export interface ValidationError {
  */
 export interface FormSubmission {
     formId: string;
-    data: Record<string, unknown>;
+    toolName: string;
+    parameters: Record<string, unknown>;
     timestamp: number;
+    context?: {
+        originalPrompt?: string;
+        partialInput?: Record<string, unknown>;
+        chatHistory?: Array<{
+            type: 'human' | 'ai';
+            content: string;
+        }>;
+    };
 }
 /**
  * Response after form submission