@hashgraphonline/conversational-agent 0.1.204 → 0.1.206

package/src/context/ReferenceContextManager.ts

@@ -0,0 +1,345 @@
+import type { ContentReference, ReferenceId, ContentReferenceError } from '../types/content-reference';
+import type { ContentStorage } from '../memory/ContentStorage';
+import { Logger } from '@hashgraphonline/standards-sdk';
+
+export interface ReferenceContext {
+  reference: ContentReference;
+  displayedAt: Date;
+  lastAccessedAt: Date;
+  contextId: string;
+  conversationTurn: number;
+}
+
+export interface ReferenceDisplayOptions {
+  maxPreviewLength?: number;
+  showMetadata?: boolean;
+  showSize?: boolean;
+  includeActions?: boolean;
+  format?: 'inline' | 'card' | 'compact';
+}
+
+export interface DisplayResult {
+  displayText: string;
+  hasValidReference: boolean;
+  contextId?: string;
+  suggestedActions?: string[];
+}
+
+/**
+ * Manages content references within agent conversation context
+ * Tracks reference usage, provides display formatting, and handles reference validation
+ */
+export class ReferenceContextManager {
+  private activeReferences: Map<ReferenceId, ReferenceContext> = new Map();
+  private contentStorage: ContentStorage;
+  private logger: Logger;
+  private conversationTurn = 0;
+
+  constructor(contentStorage: ContentStorage, logger: Logger) {
+    this.contentStorage = contentStorage;
+    this.logger = logger;
+  }
+
+  /**
+   * Add a reference to the current conversation context
+   */
+  addReference(reference: ContentReference): string {
+    this.conversationTurn++;
+    const contextId = `ctx_${Date.now()}_${reference.referenceId.substring(0, 8)}`;
+    
+    const context: ReferenceContext = {
+      reference,
+      displayedAt: new Date(),
+      lastAccessedAt: new Date(),
+      contextId,
+      conversationTurn: this.conversationTurn
+    };
+
+    this.activeReferences.set(reference.referenceId, context);
+    
+    this.logger.debug(`Added reference to conversation context: ${reference.referenceId} (${contextId})`);
+    
+    return contextId;
+  }
+
+  /**
+   * Generate display text for a content reference
+   */
+  async displayReference(
+    reference: ContentReference,
+    options: ReferenceDisplayOptions = {}
+  ): Promise<DisplayResult> {
+    const {
+      maxPreviewLength = 150,
+      showMetadata = true,
+      showSize = true,
+      includeActions = true,
+      format = 'card'
+    } = options;
+
+    try {
+      const isValid = await this.contentStorage.hasReference(reference.referenceId);
+      if (!isValid) {
+        return {
+          displayText: this.formatInvalidReference(reference, includeActions),
+          hasValidReference: false,
+          suggestedActions: ['Request fresh content', 'Use alternative content source']
+        };
+      }
+
+      const contextId = this.addReference(reference);
+      
+      let displayText = '';
+      
+      switch (format) {
+        case 'inline':
+          displayText = this.formatInlineReference(reference, maxPreviewLength);
+          break;
+        case 'compact':
+          displayText = this.formatCompactReference(reference, showSize);
+          break;
+        case 'card':
+        default:
+          displayText = this.formatCardReference(reference, {
+            maxPreviewLength,
+            showMetadata,
+            showSize,
+            includeActions,
+            contextId
+          });
+          break;
+      }
+
+      return {
+        displayText,
+        hasValidReference: true,
+        contextId
+      };
+    } catch (error) {
+      this.logger.error('Error displaying reference:', error);
+      return {
+        displayText: this.formatErrorReference(reference, error),
+        hasValidReference: false,
+        suggestedActions: ['Check reference validity', 'Try again', 'Contact administrator']
+      };
+    }
+  }
+
+  /**
+   * Get the most recent reference for "inscribe it" commands
+   */
+  getMostRecentReference(): ContentReference | null {
+    if (this.activeReferences.size === 0) {
+      return null;
+    }
+
+    let mostRecent: ReferenceContext | null = null;
+    for (const context of this.activeReferences.values()) {
+      if (!mostRecent || context.displayedAt > mostRecent.displayedAt) {
+        mostRecent = context;
+      }
+    }
+
+    if (mostRecent) {
+      mostRecent.lastAccessedAt = new Date();
+      return mostRecent.reference;
+    }
+
+    return null;
+  }
+
+  /**
+   * Get reference by context ID
+   */
+  getReferenceByContextId(contextId: string): ContentReference | null {
+    for (const context of this.activeReferences.values()) {
+      if (context.contextId === contextId) {
+        context.lastAccessedAt = new Date();
+        return context.reference;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Validate all active references and remove invalid ones
+   */
+  async validateReferences(): Promise<{ valid: number; invalid: number; removed: ReferenceId[] }> {
+    const removed: ReferenceId[] = [];
+    let valid = 0;
+    let invalid = 0;
+
+    for (const [referenceId, context] of this.activeReferences.entries()) {
+      try {
+        const isValid = await this.contentStorage.hasReference(referenceId);
+        if (isValid) {
+          valid++;
+        } else {
+          invalid++;
+          removed.push(referenceId);
+          this.activeReferences.delete(referenceId);
+          this.logger.debug(`Removed invalid reference from context: ${referenceId}`);
+        }
+      } catch (error) {
+        invalid++;
+        removed.push(referenceId);
+        this.activeReferences.delete(referenceId);
+        this.logger.warn(`Error validating reference ${referenceId}:`, error);
+      }
+    }
+
+    return { valid, invalid, removed };
+  }
+
+  /**
+   * Clear old references based on age and usage
+   */
+  cleanupOldReferences(maxAgeMs: number = 30 * 60 * 1000): number {
+    const cutoffTime = new Date(Date.now() - maxAgeMs);
+    const toRemove: ReferenceId[] = [];
+
+    for (const [referenceId, context] of this.activeReferences.entries()) {
+      if (context.lastAccessedAt < cutoffTime) {
+        toRemove.push(referenceId);
+      }
+    }
+
+    toRemove.forEach(referenceId => {
+      this.activeReferences.delete(referenceId);
+    });
+
+    if (toRemove.length > 0) {
+      this.logger.debug(`Cleaned up ${toRemove.length} old references from context`);
+    }
+
+    return toRemove.length;
+  }
+
+  /**
+   * Get current context statistics
+   */
+  getContextStats() {
+    return {
+      activeReferences: this.activeReferences.size,
+      conversationTurn: this.conversationTurn,
+      oldestReference: this.getOldestReferenceAge(),
+      mostRecentReference: this.getMostRecentReferenceAge()
+    };
+  }
+
+  /**
+   * Clear all references from context
+   */
+  clear(): void {
+    this.activeReferences.clear();
+    this.conversationTurn = 0;
+    this.logger.debug('Cleared all references from context');
+  }
+
+  private formatCardReference(
+    reference: ContentReference,
+    options: {
+      maxPreviewLength: number;
+      showMetadata: boolean;
+      showSize: boolean;
+      includeActions: boolean;
+      contextId: string;
+    }
+  ): string {
+    const { maxPreviewLength, showMetadata, showSize, includeActions, contextId } = options;
+    
+    let display = `📄 **Large Content Reference**\n`;
+    display += `**Preview:** ${this.truncateText(reference.preview, maxPreviewLength)}\n`;
+    
+    if (showSize) {
+      const sizeKB = Math.round(reference.metadata.sizeBytes / 1024);
+      display += `**Size:** ${sizeKB}KB`;
+      if (reference.metadata.contentType !== 'binary') {
+        display += ` (${reference.metadata.contentType})`;
+      }
+      display += '\n';
+    }
+    
+    if (showMetadata) {
+      if (reference.metadata.fileName) {
+        display += `**File:** ${reference.metadata.fileName}\n`;
+      }
+      if (reference.metadata.source) {
+        display += `**Source:** ${reference.metadata.source}\n`;
+      }
+    }
+    
+    if (includeActions) {
+      display += `\n💡 You can say "inscribe it" to inscribe this content to the Hedera network.`;
+    }
+    
+    display += `\n\n*Reference ID: ${reference.referenceId.substring(0, 12)}...*`;
+    display += `\n*Context: ${contextId}*`;
+    
+    return display;
+  }
+
+  private formatInlineReference(reference: ContentReference, maxPreviewLength: number): string {
+    const sizeKB = Math.round(reference.metadata.sizeBytes / 1024);
+    return `📄 [${sizeKB}KB ${reference.metadata.contentType}] ${this.truncateText(reference.preview, maxPreviewLength)}`;
+  }
+
+  private formatCompactReference(reference: ContentReference, showSize: boolean): string {
+    const sizeKB = Math.round(reference.metadata.sizeBytes / 1024);
+    const sizeText = showSize ? ` (${sizeKB}KB)` : '';
+    return `📄 Referenced content${sizeText}: ${reference.metadata.fileName || 'large content'}`;
+  }
+
+  private formatInvalidReference(reference: ContentReference, includeActions: boolean): string {
+    let display = `❌ **Content Reference Expired**\n`;
+    display += `The referenced content is no longer available.\n`;
+    display += `**Original:** ${this.truncateText(reference.preview, 100)}\n`;
+    
+    if (includeActions) {
+      display += `\n💡 Please request fresh content from the original source.`;
+    }
+    
+    return display;
+  }
+
+  private formatErrorReference(reference: ContentReference, error: unknown): string {
+    const errorMsg = error instanceof Error ? error.message : 'Unknown error';
+    let display = `⚠️ **Reference Error**\n`;
+    display += `Error accessing referenced content: ${errorMsg}\n`;
+    display += `**Reference:** ${this.truncateText(reference.preview, 100)}\n`;
+    return display;
+  }
+
+  private truncateText(text: string, maxLength: number): string {
+    if (text.length <= maxLength) {
+      return text;
+    }
+    return text.substring(0, maxLength - 3) + '...';
+  }
+
+  private getOldestReferenceAge(): number | null {
+    if (this.activeReferences.size === 0) return null;
+    
+    let oldest: Date | null = null;
+    for (const context of this.activeReferences.values()) {
+      if (!oldest || context.displayedAt < oldest) {
+        oldest = context.displayedAt;
+      }
+    }
+    
+    return oldest ? Date.now() - oldest.getTime() : null;
+  }
+
+  private getMostRecentReferenceAge(): number | null {
+    if (this.activeReferences.size === 0) return null;
+    
+    let newest: Date | null = null;
+    for (const context of this.activeReferences.values()) {
+      if (!newest || context.displayedAt > newest) {
+        newest = context.displayedAt;
+      }
+    }
+    
+    return newest ? Date.now() - newest.getTime() : null;
+  }
+}

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);
+  }
+}