@hashgraphonline/conversational-agent 0.1.205 → 0.1.206

package/src/context/ReferenceResponseProcessor.ts

@@ -0,0 +1,296 @@
+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, position, 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;
+    
+    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;
+    
+    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 {
+        // Keep original if not valid JSON
+      }
+    }
+    
+    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/conversational-agent.ts

@@ -23,6 +23,7 @@ import type { IStateManager } from '@hashgraphonline/standards-agent-kit';
 import { PrivateKey } from '@hashgraph/sdk';
 import { getSystemMessage } from './config/system-message';
 import type { MCPServerConfig } from './mcp/types';
+import { ContentStoreManager } from './services/ContentStoreManager';
 
 const DEFAULT_MODEL_NAME = 'gpt-4o';
 const DEFAULT_TEMPERATURE = 0.1;
@@ -68,6 +69,7 @@ export class ConversationalAgent {
   public stateManager: IStateManager;
   private options: ConversationalAgentOptions;
   private logger: Logger;
+  private contentStoreManager?: ContentStoreManager;
 
   constructor(options: ConversationalAgentOptions) {
     this.options = options;
@@ -94,54 +96,24 @@ export class ConversationalAgent {
       network = DEFAULT_NETWORK,
       openAIApiKey,
       openAIModelName = DEFAULT_MODEL_NAME,
-      verbose = false,
-      operationalMode = DEFAULT_OPERATIONAL_MODE,
-      userAccountId,
-      customSystemMessagePreamble,
-      customSystemMessagePostamble,
-      additionalPlugins = [],
-      mirrorNodeConfig,
-      disableLogging,
-      scheduleUserTransactionsInBytesMode,
     } = this.options;
 
-    if (!accountId || !privateKey) {
-      throw new Error('Account ID and private key are required');
-    }
+    this.validateOptions(accountId, privateKey);
 
     try {
       const privateKeyInstance = await this.detectPrivateKeyType(
-        accountId,
-        privateKey,
+        accountId!,
+        privateKey!,
         network
       );
 
       const serverSigner = new ServerSigner(
-        accountId,
+        accountId!,
         privateKeyInstance,
         network as 'testnet' | 'mainnet' | 'previewnet'
       );
 
-      const standardPlugins = [
-        this.hcs10Plugin,
-        this.hcs2Plugin,
-        this.inscribePlugin,
-        this.hbarTransferPlugin,
-      ];
-
-      const corePlugins = getAllHederaCorePlugins();
-
-      let allPlugins: BasePlugin[];
-
-      if (this.options.enabledPlugins) {
-        const enabledSet = new Set(this.options.enabledPlugins);
-        const filteredPlugins = [...standardPlugins, ...corePlugins].filter(
-          (plugin) => enabledSet.has(plugin.id)
-        );
-        allPlugins = [...filteredPlugins, ...additionalPlugins];
-      } else {
-        allPlugins = [...standardPlugins, ...corePlugins, ...additionalPlugins];
-      }
+      const allPlugins = this.preparePlugins();
 
       const llm = new ChatOpenAI({
         apiKey: openAIApiKey,
@@ -149,59 +121,16 @@ export class ConversationalAgent {
         temperature: DEFAULT_TEMPERATURE,
       });
 
-      this.agent = createAgent({
-        framework: 'langchain',
-        signer: serverSigner,
-        execution: {
-          mode: operationalMode === 'autonomous' ? 'direct' : 'bytes',
-          operationalMode: operationalMode,
-          ...(userAccountId && { userAccountId }),
-          ...(scheduleUserTransactionsInBytesMode !== undefined && {
-            scheduleUserTransactions: scheduleUserTransactionsInBytesMode,
-          }),
-        },
-        ai: {
-          provider: new LangChainProvider(llm),
-          temperature: DEFAULT_TEMPERATURE,
-        },
-        filtering: {
-          toolPredicate: (tool) => {
-            if (tool.name === 'hedera-account-transfer-hbar') return false;
-            if (this.options.toolFilter && !this.options.toolFilter(tool)) {
-              return false;
-            }
-            return true;
-          },
-        },
-        messaging: {
-          systemPreamble:
-            customSystemMessagePreamble || getSystemMessage(accountId),
-          ...(customSystemMessagePostamble && { systemPostamble: customSystemMessagePostamble }),
-          conciseMode: true,
-        },
-        extensions: {
-          plugins: allPlugins,
-          ...(mirrorNodeConfig && {
-            mirrorConfig: mirrorNodeConfig as Record<string, unknown>,
-          }),
-        },
-        ...(this.options.mcpServers && {
-          mcp: {
-            servers: this.options.mcpServers,
-            autoConnect: true,
-          },
-        }),
-        debug: {
-          verbose,
-          silent: disableLogging ?? false,
-        },
-      });
+      const agentConfig = this.createAgentConfig(serverSigner, llm, allPlugins);
+      this.agent = createAgent(agentConfig);
 
-      const hcs10 = allPlugins.find((p) => p.id === 'hcs-10');
-      if (hcs10) {
-        (hcs10 as { appConfig?: Record<string, unknown> }).appConfig = {
-          stateManager: this.stateManager,
-        };
+      this.configureHCS10Plugin(allPlugins);
+
+      // Initialize ContentStoreManager if MCP servers are configured
+      if (this.options.mcpServers && this.options.mcpServers.length > 0) {
+        this.contentStoreManager = new ContentStoreManager();
+        await this.contentStoreManager.initialize();
+        this.logger.info('ContentStoreManager initialized for MCP content reference support');
       }
 
       await this.agent.boot();
@@ -266,11 +195,13 @@ export class ConversationalAgent {
       throw new Error('Agent not initialized. Call initialize() first.');
     }
 
-    const messages = chatHistory.map((msg) =>
-      msg.type === 'human'
-        ? new HumanMessage(msg.content)
-        : new AIMessage(msg.content)
-    );
+    const messages = chatHistory.map((msg) => {
+      if (msg.type === 'human') {
+        return new HumanMessage(msg.content);
+      } else {
+        return new AIMessage(msg.content);
+      }
+    });
 
     const context: ConversationContext = {
       messages,
@@ -279,6 +210,135 @@ export class ConversationalAgent {
     return this.agent.chat(message, context);
   }
 
+  /**
+   * Validates initialization options and throws if required fields are missing.
+   * 
+   * @param accountId - The Hedera account ID
+   * @param privateKey - The private key for the account
+   * @throws {Error} If required fields are missing
+   */
+  private validateOptions(accountId?: string, privateKey?: string): void {
+    if (!accountId || !privateKey) {
+      throw new Error('Account ID and private key are required');
+    }
+  }
+
+  /**
+   * Prepares the list of plugins to use based on configuration.
+   * 
+   * @returns Array of plugins to initialize with the agent
+   */
+  private preparePlugins(): BasePlugin[] {
+    const { additionalPlugins = [], enabledPlugins } = this.options;
+    
+    const standardPlugins = [
+      this.hcs10Plugin,
+      this.hcs2Plugin,
+      this.inscribePlugin,
+      this.hbarTransferPlugin,
+    ];
+    
+    const corePlugins = getAllHederaCorePlugins();
+    
+    if (enabledPlugins) {
+      const enabledSet = new Set(enabledPlugins);
+      const filteredPlugins = [...standardPlugins, ...corePlugins].filter(
+        (plugin) => enabledSet.has(plugin.id)
+      );
+      return [...filteredPlugins, ...additionalPlugins];
+    }
+    
+    return [...standardPlugins, ...corePlugins, ...additionalPlugins];
+  }
+
+  /**
+   * Creates the agent configuration object.
+   * 
+   * @param serverSigner - The server signer instance
+   * @param llm - The language model instance
+   * @param allPlugins - Array of plugins to use
+   * @returns Configuration object for creating the agent
+   */
+  private createAgentConfig(
+    serverSigner: ServerSigner,
+    llm: ChatOpenAI,
+    allPlugins: BasePlugin[]
+  ): Parameters<typeof createAgent>[0] {
+    const {
+      operationalMode = DEFAULT_OPERATIONAL_MODE,
+      userAccountId,
+      scheduleUserTransactionsInBytesMode,
+      customSystemMessagePreamble,
+      customSystemMessagePostamble,
+      verbose = false,
+      mirrorNodeConfig,
+      disableLogging,
+      accountId = '',
+    } = this.options;
+
+    return {
+      framework: 'langchain',
+      signer: serverSigner,
+      execution: {
+        mode: operationalMode === 'autonomous' ? 'direct' : 'bytes',
+        operationalMode: operationalMode,
+        ...(userAccountId && { userAccountId }),
+        ...(scheduleUserTransactionsInBytesMode !== undefined && {
+          scheduleUserTransactions: scheduleUserTransactionsInBytesMode,
+        }),
+      },
+      ai: {
+        provider: new LangChainProvider(llm),
+        temperature: DEFAULT_TEMPERATURE,
+      },
+      filtering: {
+        toolPredicate: (tool) => {
+          if (tool.name === 'hedera-account-transfer-hbar') return false;
+          if (this.options.toolFilter && !this.options.toolFilter(tool)) {
+            return false;
+          }
+          return true;
+        },
+      },
+      messaging: {
+        systemPreamble:
+          customSystemMessagePreamble || getSystemMessage(accountId),
+        ...(customSystemMessagePostamble && { systemPostamble: customSystemMessagePostamble }),
+        conciseMode: true,
+      },
+      extensions: {
+        plugins: allPlugins,
+        ...(mirrorNodeConfig && {
+          mirrorConfig: mirrorNodeConfig as Record<string, unknown>,
+        }),
+      },
+      ...(this.options.mcpServers && {
+        mcp: {
+          servers: this.options.mcpServers,
+          autoConnect: true,
+        },
+      }),
+      debug: {
+        verbose,
+        silent: disableLogging ?? false,
+      },
+    };
+  }
+
+  /**
+   * Configures the HCS-10 plugin with the state manager.
+   * 
+   * @param allPlugins - Array of all plugins
+   */
+  private configureHCS10Plugin(allPlugins: BasePlugin[]): void {
+    const hcs10 = allPlugins.find((p) => p.id === 'hcs-10');
+    if (hcs10) {
+      (hcs10 as { appConfig?: Record<string, unknown> }).appConfig = {
+        stateManager: this.stateManager,
+      };
+    }
+  }
+
   /**
    * Create a ConversationalAgent with specific plugins enabled
    */
@@ -408,4 +468,18 @@ export class ConversationalAgent {
       return PrivateKey.fromStringED25519(privateKey);
     }
   }
+
+  /**
+   * Clean up resources
+   */
+  async cleanup(): Promise<void> {
+    if (this.contentStoreManager) {
+      await this.contentStoreManager.dispose();
+      this.logger.info('ContentStoreManager cleaned up');
+    }
+    // Agent cleanup if needed
+    if (this.agent) {
+      // Add agent cleanup if available
+    }
+  }
 }