@hashgraphonline/conversational-agent 0.1.204 → 0.1.206

package/src/memory/TokenCounter.ts

@@ -0,0 +1,152 @@
+import { encoding_for_model } from 'tiktoken';
+import type { TiktokenModel } from 'tiktoken';
+import type { BaseMessage } from '@langchain/core/messages';
+
+/**
+ * Token counter utility for OpenAI models using tiktoken encoding
+ * Provides accurate token counting for text content and chat messages
+ */
+export class TokenCounter {
+  private encoding: ReturnType<typeof encoding_for_model>;
+  private modelName: TiktokenModel;
+
+  // Token overhead per message for chat completion format
+  private static readonly MESSAGE_OVERHEAD = 3; // <|start|>role<|end|>content<|end|>
+  private static readonly ROLE_OVERHEAD = 1; // Additional token for role specification
+
+  constructor(modelName: TiktokenModel = 'gpt-4o') {
+    this.modelName = modelName;
+    try {
+      this.encoding = encoding_for_model(modelName);
+    } catch (error) {
+      // Fallback to gpt-4o if specific model encoding is not available
+      console.warn(`Model ${modelName} not found, falling back to gpt-4o encoding`);
+      this.encoding = encoding_for_model('gpt-4o');
+      this.modelName = 'gpt-4o';
+    }
+  }
+
+  /**
+   * Count tokens in raw text content
+   * @param text - The text to count tokens for
+   * @returns Number of tokens
+   */
+  countTokens(text: string): number {
+    if (!text || text.trim() === '') {
+      return 0;
+    }
+
+    try {
+      const tokens = this.encoding.encode(text);
+      return tokens.length;
+    } catch (error) {
+      console.warn('Error counting tokens, falling back to word-based estimation:', error);
+      // Fallback: rough estimation based on words (typically 1.3 tokens per word)
+      return Math.ceil(text.split(/\s+/).length * 1.3);
+    }
+  }
+
+  /**
+   * Count tokens for a single chat message including role overhead
+   * @param message - The message to count tokens for
+   * @returns Number of tokens including message formatting overhead
+   */
+  countMessageTokens(message: BaseMessage): number {
+    const contentTokens = this.countTokens(message.content as string);
+    const roleTokens = this.countTokens(this.getMessageRole(message));
+    
+    // Add overhead for message structure and role
+    return contentTokens + roleTokens + TokenCounter.MESSAGE_OVERHEAD + TokenCounter.ROLE_OVERHEAD;
+  }
+
+  /**
+   * Count tokens for multiple messages
+   * @param messages - Array of messages to count
+   * @returns Total token count for all messages
+   */
+  countMessagesTokens(messages: BaseMessage[]): number {
+    if (!messages || messages.length === 0) {
+      return 0;
+    }
+
+    return messages.reduce((total, message) => {
+      return total + this.countMessageTokens(message);
+    }, 0);
+  }
+
+  /**
+   * Estimate tokens for system prompt
+   * System prompts have slightly different overhead in chat completions
+   * @param systemPrompt - The system prompt text
+   * @returns Estimated token count
+   */
+  estimateSystemPromptTokens(systemPrompt: string): number {
+    if (!systemPrompt || systemPrompt.trim() === '') {
+      return 0;
+    }
+
+    const contentTokens = this.countTokens(systemPrompt);
+    const roleTokens = this.countTokens('system');
+    
+    // System messages have similar overhead to regular messages
+    return contentTokens + roleTokens + TokenCounter.MESSAGE_OVERHEAD + TokenCounter.ROLE_OVERHEAD;
+  }
+
+  /**
+   * Get total context size estimate including system prompt and messages
+   * @param systemPrompt - System prompt text
+   * @param messages - Conversation messages
+   * @returns Total estimated token count
+   */
+  estimateContextSize(systemPrompt: string, messages: BaseMessage[]): number {
+    const systemTokens = this.estimateSystemPromptTokens(systemPrompt);
+    const messageTokens = this.countMessagesTokens(messages);
+    
+    // Add a small buffer for chat completion overhead
+    const completionOverhead = 10;
+    
+    return systemTokens + messageTokens + completionOverhead;
+  }
+
+  /**
+   * Get the role string for a message
+   * @param message - The message to get the role for
+   * @returns Role string ('user', 'assistant', 'system', etc.)
+   */
+  private getMessageRole(message: BaseMessage): string {
+    const messageType = message._getType();
+    switch (messageType) {
+      case 'human':
+        return 'user';
+      case 'ai':
+        return 'assistant';
+      case 'system':
+        return 'system';
+      case 'function':
+        return 'function';
+      case 'tool':
+        return 'tool';
+      default:
+        return 'user'; // Default fallback
+    }
+  }
+
+  /**
+   * Get the model name being used for token counting
+   * @returns The tiktoken model name
+   */
+  getModelName(): string {
+    return this.modelName;
+  }
+
+  /**
+   * Clean up encoding resources
+   */
+  dispose(): void {
+    try {
+      this.encoding.free();
+    } catch (error) {
+      console.warn('Error disposing encoding:', error);
+    }
+  }
+}

package/src/memory/index.ts

@@ -0,0 +1,8 @@
+export { TokenCounter } from './TokenCounter';
+export { MemoryWindow } from './MemoryWindow';
+export { ContentStorage } from './ContentStorage';
+export { SmartMemoryManager } from './SmartMemoryManager';
+
+export type { SmartMemoryConfig, SearchOptions, MemoryStats } from './SmartMemoryManager';
+export type { AddMessageResult } from './MemoryWindow';
+export type { StorageStats } from './ContentStorage';

package/src/plugins/hbar-transfer/TransferHbarTool.ts

@@ -10,7 +10,7 @@ const HbarTransferInputSchema = z.object({
   amount: z
     .union([z.number(), z.string()])
     .describe(
-      'HBAR amount. Positive for credit, negative for debit. Builder handles Hbar unit & sum validation.'
+      'HBAR amount in decimal format (e.g., 1 for 1 HBAR, 0.5 for 0.5 HBAR). Positive for credit, negative for debit. DO NOT multiply by 10^8 for tinybars - just use the HBAR amount directly.'
     ),
 });
 
@@ -24,6 +24,11 @@ const TransferHbarZodSchemaCore = z.object({
   memo: z.string().optional().describe('Optional. Memo for the transaction.'),
 });
 
+/**
+ * A Hedera transaction tool for transferring HBAR between accounts.
+ * Supports single and multi-party transfers with automatic balance validation.
+ * Extends BaseHederaTransactionTool to handle HBAR transfer transactions on the Hedera network.
+ */
 export class TransferHbarTool extends BaseHederaTransactionTool<
   typeof TransferHbarZodSchemaCore
 > {
@@ -34,10 +39,23 @@ export class TransferHbarTool extends BaseHederaTransactionTool<
   namespace = 'account';
 
 
+  /**
+   * Creates and returns the service builder for account operations.
+   * 
+   * @returns BaseServiceBuilder instance configured for account operations
+   */
   protected getServiceBuilder(): BaseServiceBuilder {
     return new AccountBuilder(this.hederaKit) as BaseServiceBuilder;
   }
 
+  /**
+   * Executes the HBAR transfer using the provided builder and arguments.
+   * Validates that all transfers sum to zero before execution.
+   * 
+   * @param builder - The service builder instance for executing transactions
+   * @param specificArgs - The validated transfer parameters including transfers array and optional memo
+   * @returns Promise that resolves when the transfer is complete
+   */
   protected async callBuilderMethod(
     builder: BaseServiceBuilder,
     specificArgs: z.infer<typeof TransferHbarZodSchemaCore>

package/src/plugins/hcs-10/HCS10Plugin.ts

@@ -91,7 +91,6 @@ export class HCS10Plugin extends BasePlugin {
         `Set current agent: ${accountId} with topics ${inboundTopicId}/${outboundTopicId}`
       );
 
-      // Initialize ConnectionsManager on the state manager if needed
       if (this.stateManager && !this.stateManager.getConnectionsManager()) {
         const privateKey = hederaKit.signer.getOperatorPrivateKey().toString();
         const hcs10Client = new HCS10Client({
@@ -100,9 +99,11 @@ export class HCS10Plugin extends BasePlugin {
           operatorPrivateKey: privateKey,
           logLevel: 'error',
         });
-        
-        this.stateManager.initializeConnectionsManager(hcs10Client);
-        this.context.logger.info('ConnectionsManager initialized in HCS10Plugin');
+
+        this.stateManager.initializeConnectionsManager(hcs10Client as any);
+        this.context.logger.info(
+          'ConnectionsManager initialized in HCS10Plugin'
+        );
       }
 
       this.initializeTools();

package/src/services/ContentStoreManager.ts

@@ -0,0 +1,199 @@
+import { ContentStorage } from '../memory/ContentStorage';
+import { 
+  ContentStoreService, 
+  extractReferenceId, 
+  shouldUseReference,
+  ContentResolverRegistry,
+  type ContentStoreInterface, 
+  type ContentResolverInterface, 
+  type ReferenceResolutionResult 
+} from '@hashgraphonline/standards-sdk';
+import type { ContentReferenceConfig } from '../types/content-reference';
+import { Logger } from '@hashgraphonline/standards-sdk';
+
+/**
+ * Adapter to make ContentStorage compatible with ContentStoreInterface
+ */
+class ContentStorageAdapter implements ContentStoreInterface {
+  constructor(private storage: ContentStorage) {}
+
+  async storeContent(content: Buffer, metadata: any) {
+    const contentRef = await this.storage.storeContent(content, metadata);
+    return contentRef.referenceId;
+  }
+
+  async resolveReference(referenceId: string): Promise<ReferenceResolutionResult> {
+    const result = await this.storage.resolveReference(referenceId);
+    // Convert to match the interface from standards-sdk
+    if (result.success && result.content) {
+      const response: ReferenceResolutionResult = {
+        content: result.content
+      };
+      if (result.metadata) {
+        response.metadata = {
+          ...(result.metadata.mimeType !== undefined && { mimeType: result.metadata.mimeType }),
+          ...(result.metadata.fileName !== undefined && { fileName: result.metadata.fileName }),
+          originalSize: result.metadata.sizeBytes
+        };
+      }
+      return response;
+    } else {
+      // If resolution fails, throw an error as the interface expects content to be present
+      throw new Error(result.error || 'Reference not found');
+    }
+  }
+
+  async hasReference(referenceId: string) {
+    return await this.storage.hasReference(referenceId);
+  }
+
+  async cleanupReference(referenceId: string) {
+    await this.storage.cleanupReference(referenceId);
+  }
+
+  async getStats() {
+    return await this.storage.getStats();
+  }
+
+  async updateConfig(config: any) {
+    return await this.storage.updateConfig(config);
+  }
+
+  async performCleanup() {
+    await this.storage.performCleanup();
+  }
+
+  async dispose() {
+    return Promise.resolve(this.storage.dispose());
+  }
+}
+
+/**
+ * Content resolver implementation for dependency injection
+ */
+class ContentResolver implements ContentResolverInterface {
+  constructor(private adapter: ContentStorageAdapter) {}
+
+  async resolveReference(referenceId: string): Promise<ReferenceResolutionResult> {
+    // The adapter already handles the conversion
+    return await this.adapter.resolveReference(referenceId);
+  }
+
+  shouldUseReference(content: string | Buffer): boolean {
+    return shouldUseReference(content);
+  }
+
+  extractReferenceId(input: string): string | null {
+    return extractReferenceId(input);
+  }
+}
+
+/**
+ * Manages content store lifecycle and cross-package registration
+ */
+export class ContentStoreManager {
+  private contentStorage: ContentStorage;
+  private adapter: ContentStorageAdapter;
+  private resolver: ContentResolver;
+  private logger: Logger;
+  private isRegistered = false;
+
+  constructor(
+    maxMessageStorage: number = 1000,
+    referenceConfig?: Partial<ContentReferenceConfig>,
+    logger?: Logger
+  ) {
+    this.logger = logger || {
+      info: console.log,
+      debug: console.log,
+      warn: console.warn,
+      error: console.error
+    } as Logger;
+
+    this.contentStorage = new ContentStorage(maxMessageStorage, referenceConfig);
+    this.adapter = new ContentStorageAdapter(this.contentStorage);
+    this.resolver = new ContentResolver(this.adapter);
+  }
+
+  /**
+   * Initialize and register content storage for cross-package access
+   */
+  async initialize(): Promise<void> {
+    if (this.isRegistered) {
+      this.logger.warn('ContentStoreManager is already initialized');
+      return;
+    }
+
+    try {
+      await ContentStoreService.setInstance(this.adapter);
+      ContentResolverRegistry.register(this.resolver);
+      this.isRegistered = true;
+      this.logger.info('ContentStoreManager initialized and registered for cross-package access');
+    } catch (error) {
+      this.logger.error('Failed to initialize ContentStoreManager:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get the underlying ContentStorage instance
+   */
+  getContentStorage(): ContentStorage {
+    return this.contentStorage;
+  }
+
+  /**
+   * Get storage statistics
+   */
+  async getStats() {
+    return await this.contentStorage.getStats();
+  }
+
+  /**
+   * Update configuration
+   */
+  async updateConfig(config: Partial<ContentReferenceConfig>) {
+    return await this.contentStorage.updateConfig(config);
+  }
+
+  /**
+   * Perform manual cleanup
+   */
+  async performCleanup() {
+    return await this.contentStorage.performCleanup();
+  }
+
+  /**
+   * Check if content should be stored as reference
+   */
+  shouldUseReference(content: Buffer | string): boolean {
+    return this.contentStorage.shouldUseReference(content);
+  }
+
+  /**
+   * Store content if it's large enough
+   */
+  async storeContentIfLarge(content: Buffer | string, metadata: any) {
+    return await this.contentStorage.storeContentIfLarge(content, metadata);
+  }
+
+  /**
+   * Cleanup and unregister
+   */
+  async dispose(): Promise<void> {
+    if (this.isRegistered) {
+      this.contentStorage.dispose();
+      ContentStoreService.dispose();
+      ContentResolverRegistry.unregister();
+      this.isRegistered = false;
+      this.logger.info('ContentStoreManager disposed and unregistered');
+    }
+  }
+
+  /**
+   * Check if the manager is initialized
+   */
+  isInitialized(): boolean {
+    return this.isRegistered;
+  }
+}

package/src/types/content-reference.ts

@@ -0,0 +1,281 @@
+/**
+ * Content Reference System Types
+ * 
+ * Shared interfaces for the Reference-Based Content System that handles
+ * large content storage with unique reference IDs to optimize context window usage.
+ */
+
+/**
+ * Unique identifier for stored content references
+ * Format: Cryptographically secure 32-byte identifier with base64url encoding
+ */
+export type ReferenceId = string;
+
+/**
+ * Lifecycle state of a content reference
+ */
+export type ReferenceLifecycleState = 'active' | 'expired' | 'cleanup_pending' | 'invalid';
+
+/**
+ * Content types supported by the reference system
+ */
+export type ContentType = 'text' | 'json' | 'html' | 'markdown' | 'binary' | 'unknown';
+
+/**
+ * Sources that created the content reference
+ */
+export type ContentSource = 'mcp_tool' | 'user_upload' | 'agent_generated' | 'system';
+
+/**
+ * Metadata associated with stored content
+ */
+export interface ContentMetadata {
+  /** Content type classification */
+  contentType: ContentType;
+  
+  /** MIME type of the original content */
+  mimeType?: string;
+  
+  /** Size in bytes of the stored content */
+  sizeBytes: number;
+  
+  /** When the content was originally stored */
+  createdAt: Date;
+  
+  /** Last time the content was accessed via reference resolution */
+  lastAccessedAt: Date;
+  
+  /** Source that created this content reference */
+  source: ContentSource;
+  
+  /** Name of the MCP tool that generated the content (if applicable) */
+  mcpToolName?: string;
+  
+  /** Original filename or suggested name for the content */
+  fileName?: string;
+  
+  /** Number of times this reference has been resolved */
+  accessCount: number;
+  
+  /** Tags for categorization and cleanup policies */
+  tags?: string[];
+  
+  /** Custom metadata from the source */
+  customMetadata?: Record<string, unknown>;
+}
+
+/**
+ * Core content reference object passed through agent context
+ * Designed to be lightweight (<100 tokens) while providing enough 
+ * information for agent decision-making
+ */
+export interface ContentReference {
+  /** Unique identifier for resolving the content */
+  referenceId: ReferenceId;
+  
+  /** Current lifecycle state */
+  state: ReferenceLifecycleState;
+  
+  /** Brief description or preview of the content (max 200 chars) */
+  preview: string;
+  
+  /** Essential metadata for agent decision-making */
+  metadata: Pick<ContentMetadata, 'contentType' | 'sizeBytes' | 'source' | 'fileName' | 'mimeType'>;
+  
+  /** When this reference was created */
+  createdAt: Date;
+  
+  /** Special format indicator for reference IDs in content */
+  readonly format: 'ref://{id}';
+}
+
+/**
+ * Result of attempting to resolve a content reference
+ */
+export interface ReferenceResolutionResult {
+  /** Whether the resolution was successful */
+  success: boolean;
+  
+  /** The resolved content if successful */
+  content?: Buffer;
+  
+  /** Complete metadata if successful */
+  metadata?: ContentMetadata;
+  
+  /** Error message if resolution failed */
+  error?: string;
+  
+  /** Specific error type for targeted error handling */
+  errorType?: 'not_found' | 'expired' | 'corrupted' | 'access_denied' | 'system_error';
+  
+  /** Suggested actions for recovery */
+  suggestedActions?: string[];
+}
+
+/**
+ * Configuration for content reference storage and lifecycle
+ */
+export interface ContentReferenceConfig {
+  /** Size threshold above which content should be stored as references (default: 10KB) */
+  sizeThresholdBytes: number;
+  
+  /** Maximum age for unused references before cleanup (default: 1 hour) */
+  maxAgeMs: number;
+  
+  /** Maximum number of references to store simultaneously */
+  maxReferences: number;
+  
+  /** Maximum total storage size for all references */
+  maxTotalStorageBytes: number;
+  
+  /** Whether to enable automatic cleanup */
+  enableAutoCleanup: boolean;
+  
+  /** Interval for cleanup checks in milliseconds */
+  cleanupIntervalMs: number;
+  
+  /** Whether to persist references across restarts */
+  enablePersistence: boolean;
+  
+  /** Storage backend configuration */
+  storageBackend: 'memory' | 'filesystem' | 'hybrid';
+  
+  /** Cleanup policies for different content types */
+  cleanupPolicies: {
+    /** Policy for content marked as "recent" from MCP tools */
+    recent: { maxAgeMs: number; priority: number };
+    
+    /** Policy for user-uploaded content */
+    userContent: { maxAgeMs: number; priority: number };
+    
+    /** Policy for agent-generated content */
+    agentGenerated: { maxAgeMs: number; priority: number };
+    
+    /** Default policy for other content */
+    default: { maxAgeMs: number; priority: number };
+  };
+}
+
+/**
+ * Default configuration values
+ */
+export const DEFAULT_CONTENT_REFERENCE_CONFIG: ContentReferenceConfig = {
+  sizeThresholdBytes: 10 * 1024, // 10KB
+  maxAgeMs: 60 * 60 * 1000, // 1 hour
+  maxReferences: 100,
+  maxTotalStorageBytes: 100 * 1024 * 1024, // 100MB
+  enableAutoCleanup: true,
+  cleanupIntervalMs: 5 * 60 * 1000, // 5 minutes
+  enablePersistence: false,
+  storageBackend: 'memory',
+  cleanupPolicies: {
+    recent: { maxAgeMs: 30 * 60 * 1000, priority: 1 }, // 30 minutes, highest priority
+    userContent: { maxAgeMs: 2 * 60 * 60 * 1000, priority: 2 }, // 2 hours
+    agentGenerated: { maxAgeMs: 60 * 60 * 1000, priority: 3 }, // 1 hour
+    default: { maxAgeMs: 60 * 60 * 1000, priority: 4 } // 1 hour, lowest priority
+  }
+};
+
+/**
+ * Statistics about content reference usage and storage
+ */
+export interface ContentReferenceStats {
+  /** Total number of active references */
+  activeReferences: number;
+  
+  /** Total storage used by all references in bytes */
+  totalStorageBytes: number;
+  
+  /** Number of references cleaned up in last cleanup cycle */
+  recentlyCleanedUp: number;
+  
+  /** Number of successful reference resolutions since startup */
+  totalResolutions: number;
+  
+  /** Number of failed resolution attempts */
+  failedResolutions: number;
+  
+  /** Average content size in bytes */
+  averageContentSize: number;
+  
+  /** Most frequently accessed reference ID */
+  mostAccessedReferenceId?: ReferenceId;
+  
+  /** Storage utilization percentage */
+  storageUtilization: number;
+  
+  /** Performance metrics */
+  performanceMetrics: {
+    /** Average time to create a reference in milliseconds */
+    averageCreationTimeMs: number;
+    
+    /** Average time to resolve a reference in milliseconds */
+    averageResolutionTimeMs: number;
+    
+    /** Average cleanup time in milliseconds */
+    averageCleanupTimeMs: number;
+  };
+}
+
+/**
+ * Error types for content reference operations
+ */
+export class ContentReferenceError extends Error {
+  constructor(
+    message: string,
+    public readonly type: ReferenceResolutionResult['errorType'],
+    public readonly referenceId?: ReferenceId,
+    public readonly suggestedActions?: string[]
+  ) {
+    super(message);
+    this.name = 'ContentReferenceError';
+  }
+}
+
+/**
+ * Interface for content reference storage implementations
+ */
+export interface ContentReferenceStore {
+  /**
+   * Store content and return a reference
+   */
+  storeContent(
+    content: Buffer,
+    metadata: Omit<ContentMetadata, 'createdAt' | 'lastAccessedAt' | 'accessCount'>
+  ): Promise<ContentReference>;
+  
+  /**
+   * Resolve a reference to its content
+   */
+  resolveReference(referenceId: ReferenceId): Promise<ReferenceResolutionResult>;
+  
+  /**
+   * Check if a reference exists and is valid
+   */
+  hasReference(referenceId: ReferenceId): Promise<boolean>;
+  
+  /**
+   * Mark a reference for cleanup
+   */
+  cleanupReference(referenceId: ReferenceId): Promise<boolean>;
+  
+  /**
+   * Get current storage statistics
+   */
+  getStats(): Promise<ContentReferenceStats>;
+  
+  /**
+   * Update configuration
+   */
+  updateConfig(config: Partial<ContentReferenceConfig>): Promise<void>;
+  
+  /**
+   * Perform cleanup based on current policies
+   */
+  performCleanup(): Promise<{ cleanedUp: number; errors: string[] }>;
+  
+  /**
+   * Dispose of resources
+   */
+  dispose(): Promise<void>;
+}