@hashgraphonline/conversational-agent 0.1.217 → 0.1.218

package/src/context/ReferenceResponseProcessor.ts

@@ -1,295 +0,0 @@
-import type { ContentReference, ReferenceId, ContentMetadata } from '../types/content-reference';
-import type { ReferenceContextManager, ReferenceDisplayOptions } from './ReferenceContextManager';
-import { Logger } from '@hashgraphonline/standards-sdk';
-
-export interface ResponseProcessingOptions {
-  autoDisplayReferences?: boolean;
-  displayOptions?: ReferenceDisplayOptions;
-  includeReferenceInstructions?: boolean;
-  contextualizeReferences?: boolean;
-}
-
-export interface ProcessedResponse {
-  content: string;
-  hasReferences: boolean;
-  referenceCount: number;
-  contextIds: string[];
-  suggestedActions: string[];
-}
-
-export interface ReferenceDetectionResult {
-  hasReferences: boolean;
-  references: Array<{
-    reference: ContentReference;
-    position: number;
-    originalText: string;
-  }>;
-  plainReferences: Array<{
-    referenceId: ReferenceId;
-    position: number;
-    originalText: string;
-  }>;
-}
-
-/**
- * Processes agent responses to detect and display content references
- * Handles both structured references and plain reference IDs
- */
-export class ReferenceResponseProcessor {
-  private contextManager: ReferenceContextManager;
-  private logger: Logger;
-
-  constructor(contextManager: ReferenceContextManager, logger: Logger) {
-    this.contextManager = contextManager;
-    this.logger = logger;
-  }
-
-  /**
-   * Process an agent response to handle content references
-   */
-  async processResponse(
-    responseContent: string,
-    options: ResponseProcessingOptions = {}
-  ): Promise<ProcessedResponse> {
-    const {
-      autoDisplayReferences = true,
-      displayOptions = {},
-      includeReferenceInstructions = true,
-      contextualizeReferences = true
-    } = options;
-
-    try {
-      const detection = this.detectReferences(responseContent);
-      
-      if (!detection.hasReferences) {
-        return {
-          content: responseContent,
-          hasReferences: false,
-          referenceCount: 0,
-          contextIds: [],
-          suggestedActions: []
-        };
-      }
-
-      let processedContent = responseContent;
-      const contextIds: string[] = [];
-      const suggestedActions: string[] = [];
-
-      if (autoDisplayReferences) {
-        for (const { reference, originalText } of detection.references) {
-          const displayResult = await this.contextManager.displayReference(reference, displayOptions);
-          
-          processedContent = processedContent.replace(originalText, displayResult.displayText);
-          
-          if (displayResult.contextId) {
-            contextIds.push(displayResult.contextId);
-          }
-          
-          if (displayResult.suggestedActions) {
-            suggestedActions.push(...displayResult.suggestedActions);
-          }
-        }
-
-        for (const { referenceId, originalText } of detection.plainReferences) {
-          try {
-            const resolution = await this.contextManager['contentStorage'].resolveReference(referenceId);
-            if (resolution.success && resolution.metadata) {
-              const referenceMetadata: Pick<ContentMetadata, 'contentType' | 'sizeBytes' | 'source' | 'fileName' | 'mimeType'> = {
-                contentType: resolution.metadata.contentType,
-                sizeBytes: resolution.metadata.sizeBytes,
-                source: resolution.metadata.source
-              };
-              
-              if (resolution.metadata.fileName !== undefined) {
-                referenceMetadata.fileName = resolution.metadata.fileName;
-              }
-              if (resolution.metadata.mimeType !== undefined) {
-                referenceMetadata.mimeType = resolution.metadata.mimeType;
-              }
-              
-              const reference: ContentReference = {
-                referenceId,
-                state: 'active',
-                preview: this.createPreviewFromContent(resolution.content!, resolution.metadata.contentType),
-                metadata: referenceMetadata,
-                createdAt: resolution.metadata.createdAt,
-                format: 'ref://{id}' as const
-              };
-
-              const displayResult = await this.contextManager.displayReference(reference, displayOptions);
-              processedContent = processedContent.replace(originalText, displayResult.displayText);
-              
-              if (displayResult.contextId) {
-                contextIds.push(displayResult.contextId);
-              }
-            } else {
-              processedContent = processedContent.replace(
-                originalText,
-                `❌ Reference unavailable: ${referenceId.substring(0, 12)}...`
-              );
-              suggestedActions.push('Request fresh content');
-            }
-          } catch (error) {
-            this.logger.warn(`Failed to resolve plain reference ${referenceId}:`, error);
-            processedContent = processedContent.replace(
-              originalText,
-              `⚠️ Reference error: ${referenceId.substring(0, 12)}...`
-            );
-          }
-        }
-      }
-
-      if (includeReferenceInstructions && (detection.references.length > 0 || detection.plainReferences.length > 0)) {
-        if (contextualizeReferences && contextIds.length === 1) {
-          processedContent += `\n\n💡 To inscribe this content, say "inscribe it" or "inscribe the content".`;
-        } else if (contextualizeReferences && contextIds.length > 1) {
-          processedContent += `\n\n💡 To inscribe any of this content, say "inscribe it" (uses most recent) or specify the reference.`;
-        } else {
-          processedContent += `\n\n💡 Referenced content can be inscribed using the "inscribe it" command.`;
-        }
-      }
-
-      return {
-        content: processedContent,
-        hasReferences: true,
-        referenceCount: detection.references.length + detection.plainReferences.length,
-        contextIds,
-        suggestedActions: [...new Set(suggestedActions)]
-      };
-    } catch (error) {
-      this.logger.error('Error processing response references:', error);
-      return {
-        content: responseContent,
-        hasReferences: false,
-        referenceCount: 0,
-        contextIds: [],
-        suggestedActions: ['Check reference system', 'Try again']
-      };
-    }
-  }
-
-  /**
-   * Detect references in response content
-   */
-  private detectReferences(content: string): ReferenceDetectionResult {
-    const references: Array<{
-      reference: ContentReference;
-      position: number;
-      originalText: string;
-    }> = [];
-    
-    const plainReferences: Array<{
-      referenceId: ReferenceId;
-      position: number;
-      originalText: string;
-    }> = [];
-
-    const contentReferenceRegex = /"type":\s*"content_reference"[^}]*"referenceId":\s*"([^"]+)"[^}]*}/g;
-    let match: RegExpExecArray | null;
-    
-    while ((match = contentReferenceRegex.exec(content)) !== null) {
-      try {
-        const refObject = JSON.parse(match[0]);
-        if (refObject.type === 'content_reference' && refObject.referenceId) {
-          const reference: ContentReference = {
-            referenceId: refObject.referenceId,
-            state: refObject.state || 'active',
-            preview: refObject.preview || '',
-            metadata: refObject.metadata || {},
-            createdAt: new Date(refObject.createdAt || Date.now()),
-            format: 'ref://{id}' as const
-          };
-          
-          references.push({
-            reference,
-            position: match.index,
-            originalText: match[0]
-          });
-        }
-      } catch (error) {
-        this.logger.warn('Failed to parse content reference:', error);
-      }
-    }
-
-    const plainRefRegex = /ref:\/\/([A-Za-z0-9_-]{43})|(?:^|\s)([A-Za-z0-9_-]{43})(?=\s|$)/g;
-    let plainMatch: RegExpExecArray | null;
-    
-    while ((plainMatch = plainRefRegex.exec(content)) !== null) {
-      const referenceId = plainMatch[1] || plainMatch[2];
-      if (referenceId && this.isValidReferenceId(referenceId)) {
-        plainReferences.push({
-          referenceId,
-          position: plainMatch.index,
-          originalText: plainMatch[0]
-        });
-      }
-    }
-
-    return {
-      hasReferences: references.length > 0 || plainReferences.length > 0,
-      references,
-      plainReferences
-    };
-  }
-
-  /**
-   * Create a preview from content buffer
-   */
-  private createPreviewFromContent(content: Buffer, contentType: string): string {
-    const maxLength = 200;
-    let preview = content.toString('utf8', 0, Math.min(content.length, maxLength * 2));
-    
-    if (contentType === 'html') {
-      preview = preview.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ');
-    } else if (contentType === 'json') {
-      try {
-        const parsed = JSON.parse(preview);
-        preview = JSON.stringify(parsed, null, 0);
-      } catch {
-      }
-    }
-    
-    preview = preview.trim();
-    if (preview.length > maxLength) {
-      preview = preview.substring(0, maxLength) + '...';
-    }
-    
-    return preview || '[Binary content]';
-  }
-
-  /**
-   * Validate reference ID format
-   */
-  private isValidReferenceId(id: string): boolean {
-    if (!id || typeof id !== 'string') {
-      return false;
-    }
-    
-    if (id.length !== 43) {
-      return false;
-    }
-    
-    return /^[A-Za-z0-9_-]+$/.test(id);
-  }
-
-  /**
-   * Get reference context statistics
-   */
-  getContextStats() {
-    return this.contextManager.getContextStats();
-  }
-
-  /**
-   * Validate all references in context
-   */
-  async validateAllReferences() {
-    return await this.contextManager.validateReferences();
-  }
-
-  /**
-   * Clean up old references
-   */
-  cleanupOldReferences(maxAgeMs?: number) {
-    return this.contextManager.cleanupOldReferences(maxAgeMs);
-  }
-}

package/src/langchain/FormValidatingToolWrapper.ts

@@ -1,355 +0,0 @@
-import { StructuredTool } from '@langchain/core/tools';
-import { z } from 'zod';
-import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
-import { Logger } from '@hashgraphonline/standards-sdk';
-import { FormGenerator } from '../forms/form-generator';
-import { isFormValidatable } from '@hashgraphonline/standards-agent-kit';
-
-export interface FormValidationConfig {
-  requireAllFields?: boolean;
-  skipFields?: string[];
-  customValidation?: (input: unknown) => boolean;
-}
-
-/**
- * Generic wrapper for StructuredTools that intercepts execution to check for missing required fields
- * and generates forms when validation would benefit from user input.
- *
- * Tools can implement the FormValidatable interface to provide custom validation logic.
- * Otherwise, falls back to schema-based validation.
- */
-export class FormValidatingToolWrapper<
-  TSchema extends z.ZodObject<z.ZodRawShape, z.UnknownKeysParam, z.ZodTypeAny>
-> extends StructuredTool<TSchema> {
-  private originalTool: StructuredTool<TSchema>;
-  private formGenerator: FormGenerator;
-  private validationConfig: FormValidationConfig;
-  private logger: Logger;
-
-  name: string;
-  description: string;
-  schema: TSchema;
-
-  constructor(
-    originalTool: StructuredTool<TSchema>,
-    formGenerator: FormGenerator,
-    config: FormValidationConfig = {}
-  ) {
-    super();
-    this.originalTool = originalTool;
-    this.formGenerator = formGenerator;
-    this.validationConfig = config;
-    this.logger = new Logger({ module: 'FormValidatingToolWrapper' });
-
-    this.name = originalTool.name;
-    this.description = originalTool.description;
-    this.schema = originalTool.schema;
-    
-    this.logger.info(`🔧 FormValidatingToolWrapper created for tool: ${this.name}`, {
-      originalToolName: originalTool.name,
-      originalToolType: originalTool.constructor.name,
-      wrapperType: this.constructor.name
-    });
-  }
-
-  /**
-   * Validate the input against the schema
-   */
-  private validateInput(input: Record<string, unknown>): { isValid: boolean; errors?: string[] } {
-    try {
-      this.schema.parse(input);
-      return { isValid: true };
-    } catch (error) {
-      if (error instanceof z.ZodError) {
-        const errors = error.errors
-          .filter(err => {
-            const fieldName = err.path[0] as string;
-            return !this.validationConfig.skipFields?.includes(fieldName);
-          })
-          .map(err => `${err.path.join('.')}: ${err.message}`);
-        return { isValid: false, errors };
-      }
-      return { isValid: false, errors: ['Validation failed'] };
-    }
-  }
-
-  /**
-   * Gets the shape keys from the schema if it's a ZodObject
-   */
-  private getSchemaShape(): string[] {
-    if (this.isZodObject(this.schema)) {
-      return Object.keys(this.schema.shape);
-    }
-    return [];
-  }
-
-  /**
-   * Executes the wrapped tool's original implementation directly, bypassing wrapper logic.
-   */
-  public async executeOriginal(
-    input: Record<string, unknown>,
-    runManager?: CallbackManagerForToolRun
-  ): Promise<string> {
-    type CallableMethod = (
-      args: Record<string, unknown>,
-      runManager?: CallbackManagerForToolRun
-    ) => Promise<string>;
-    
-    const tool = this.originalTool as unknown as Record<string, unknown>;
-    
-    if ('_call' in tool && typeof tool._call === 'function') {
-      return (tool._call as CallableMethod)(input, runManager);
-    }
-    if ('call' in tool && typeof tool.call === 'function') {
-      return (tool.call as CallableMethod)(input, runManager);
-    }
-    throw new Error('Original tool has no callable implementation');
-  }
-
-  /**
-   * Provides access to the wrapped tool instance for executors that want to bypass the wrapper.
-   */
-  public getOriginalTool(): StructuredTool<TSchema> {
-    return this.originalTool;
-  }
-
-  /**
-   * Checks if tool implements FormValidatable method
-   */
-  private hasFormValidatableMethod<T>(
-    tool: unknown,
-    methodName: string
-  ): tool is Record<string, T> {
-    return (
-      tool !== null &&
-      typeof tool === 'object' &&
-      methodName in tool &&
-      typeof (tool as Record<string, unknown>)[methodName] === 'function'
-    );
-  }
-
-  /**
-   * Expose FormValidatable methods by delegating to the underlying tool when available.
-   */
-  public getFormSchema(): z.ZodSchema {
-    if (this.hasFormValidatableMethod<() => z.ZodSchema>(this.originalTool, 'getFormSchema')) {
-      return this.originalTool.getFormSchema();
-    }
-    return this.schema as z.ZodSchema;
-  }
-
-  public getEssentialFields(): string[] {
-    if (this.hasFormValidatableMethod<() => string[]>(this.originalTool, 'getEssentialFields')) {
-      return this.originalTool.getEssentialFields();
-    }
-    return [];
-  }
-
-  public isFieldEmpty(fieldName: string, value: unknown): boolean {
-    if (this.hasFormValidatableMethod<(n: string, v: unknown) => boolean>(this.originalTool, 'isFieldEmpty')) {
-      return this.originalTool.isFieldEmpty(fieldName, value);
-    }
-    if (value === undefined || value === null || value === '') {
-      return true;
-    }
-    if (Array.isArray(value) && value.length === 0) {
-      return true;
-    }
-    return false;
-  }
-
-  /**
-   * Calculates which fields are missing from the input
-   */
-  private calculateMissingFields(
-    input: Record<string, unknown>,
-    isCustom: boolean
-  ): Set<string> {
-    const missingFields = new Set<string>();
-    
-    if (!isCustom) {
-      return missingFields;
-    }
-
-    const essentialFields = this.getEssentialFields();
-    for (const fieldName of essentialFields) {
-      const value = input[fieldName];
-      if (this.isFieldEmpty(fieldName, value)) {
-        missingFields.add(fieldName);
-      }
-    }
-    
-    return missingFields;
-  }
-
-  /**
-   * Creates a form message with optional JSON schema
-   */
-  private async createFormMessage(
-    schema: z.ZodSchema,
-    input: Record<string, unknown>,
-    missingFields: Set<string>
-  ) {
-    let formMessage = await this.formGenerator.generateFormFromSchema(
-      schema,
-      input,
-      {
-        toolName: this.name,
-        toolDescription: this.description
-      },
-      missingFields
-    );
-
-    if (this.isZodObject(schema)) {
-      try {
-        const { jsonSchema, uiSchema } = this.formGenerator.generateJsonSchemaForm(
-          schema,
-          input,
-          missingFields
-        );
-        formMessage = {
-          ...formMessage,
-          jsonSchema,
-          uiSchema
-        };
-      } catch (error) {
-        this.logger.warn('Failed to generate JSON Schema for RJSF:', error);
-      }
-    }
-
-    formMessage.partialInput = input;
-    return formMessage;
-  }
-
-  /**
-   * Type guard to check if a schema is a ZodObject
-   */
-  private isZodObject(schema: z.ZodSchema): schema is z.ZodObject<z.ZodRawShape> {
-    const def = (schema as z.ZodType)._def as { typeName?: string };
-    return !!(def && def.typeName === 'ZodObject');
-  }
-
-  /**
-   * Check if we should generate a form for this tool invocation
-   */
-  private shouldGenerateForm(input: Record<string, unknown>): boolean {
-    this.logger.info(`shouldGenerateForm called for ${this.name}/${this.originalTool.name}`, {
-      input,
-      hasCustomValidation: !!this.validationConfig.customValidation
-    });
-
-    if (this.validationConfig.customValidation) {
-      const result = !this.validationConfig.customValidation(input);
-      this.logger.info(`Custom validation result: ${result}`);
-      return result;
-    }
-
-    if (isFormValidatable(this.originalTool)) {
-      this.logger.info(`Tool ${this.originalTool.name} implements FormValidatable, using custom logic`);
-      return this.originalTool.shouldGenerateForm(input);
-    }
-
-    this.logger.info(`Tool ${this.originalTool.name} using schema validation only`);
-    const validation = this.validateInput(input);
-    this.logger.info(`Schema validation for ${this.originalTool.name}:`, {
-      isValid: validation.isValid,
-      errors: validation.errors
-    });
-    return !validation.isValid;
-  }
-
-  /**
-   * Checks if input has bypass flags that skip form generation
-   */
-  private hasFormBypassFlags(input: Record<string, unknown>): boolean {
-    return (
-      (input.__fromForm === true) ||
-      (input.renderForm === false)
-    );
-  }
-
-  /**
-   * Override _call to intercept tool execution
-   */
-  protected async _call(
-    input: z.infer<TSchema>,
-    runManager?: CallbackManagerForToolRun
-  ): Promise<string> {
-    this.logger.info(`🚨🚨🚨 FormValidatingToolWrapper._call INTERCEPTING ${this.name} 🚨🚨🚨`, {
-      input,
-      inputKeys: Object.keys(input as Record<string, unknown>),
-      schemaShape: this.getSchemaShape(),
-      stackTrace: new Error().stack?.split('\n').slice(0, 5)
-    });
-
-    const inputRecord = input as unknown as Record<string, unknown>;
-    
-    if (this.hasFormBypassFlags(inputRecord)) {
-      this.logger.info('Bypassing form generation and executing original tool due to submission flags');
-      return this.executeOriginal(inputRecord, runManager);
-    }
-
-    const shouldGenerate = this.shouldGenerateForm(input as Record<string, unknown>);
-    this.logger.info(`FormValidatingToolWrapper decision for ${this.name}:`, {
-      shouldGenerateForm: shouldGenerate,
-      toolName: this.name,
-      originalToolName: this.originalTool.name
-    });
-
-    if (shouldGenerate) {
-      this.logger.info(`Generating form for incomplete input in ${this.name}`);
-
-      try {
-        const isCustom = isFormValidatable(this.originalTool);
-        const schemaToUse = isCustom ? this.getFormSchema() : this.schema;
-        const missingFields = this.calculateMissingFields(
-          input as Record<string, unknown>,
-          isCustom
-        );
-
-        const schemaFields = this.isZodObject(schemaToUse) 
-          ? Object.keys(schemaToUse.shape)
-          : [];
-        
-        this.logger.info(`Using ${isCustom ? 'CUSTOM' : 'DEFAULT'} schema for form generation`, {
-          toolName: this.originalTool.name,
-          schemaType: schemaToUse.constructor?.name,
-          schemaFields,
-          isCustomSchema: isCustom
-        });
-
-        const formMessage = await this.createFormMessage(
-          schemaToUse,
-          input as Record<string, unknown>,
-          missingFields
-        );
-
-        const result = {
-          requiresForm: true,
-          formMessage,
-          message: `Please complete the form to provide the required information for ${this.name}.`
-        };
-
-        this.logger.info(`FormValidatingToolWrapper returning form result for ${this.name}`);
-        return JSON.stringify(result);
-      } catch (error) {
-        this.logger.error('Failed to generate form:', error);
-      }
-    }
-
-    this.logger.info(`FormValidatingToolWrapper passing through to original tool ${this.name}`);
-    return this.executeOriginal(input as Record<string, unknown>, runManager);
-  }
-
-}
-
-/**
- * Wrap a tool with form validation capabilities
- */
-export function wrapToolWithFormValidation<TSchema extends z.ZodObject<z.ZodRawShape, z.UnknownKeysParam, z.ZodTypeAny>>(
-  tool: StructuredTool<TSchema>,
-  formGenerator: FormGenerator,
-  config: FormValidationConfig = {}
-): FormValidatingToolWrapper<TSchema> {
-  return new FormValidatingToolWrapper(tool, formGenerator, config);
-}