@hashgraphonline/conversational-agent 0.1.209 → 0.1.211

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

@@ -5,10 +5,11 @@ import { ChatResponse } from './base-agent';
 import { HCS10Plugin } from './plugins/hcs-10/HCS10Plugin';
 import { HCS2Plugin } from './plugins/hcs-2/HCS2Plugin';
 import { InscribePlugin } from './plugins/inscribe/InscribePlugin';
-import { HbarTransferPlugin } from './plugins/hbar-transfer/HbarTransferPlugin';
+import { HbarPlugin } from './plugins/hbar/HbarPlugin';
 import { IStateManager } from '@hashgraphonline/standards-agent-kit';
 import { MCPServerConfig, MCPConnectionStatus } from './mcp/types';
-import { SmartMemoryConfig } from './memory';
+import { ContentStoreManager } from './services/ContentStoreManager';
+import { SmartMemoryManager, SmartMemoryConfig } from './memory';
 
 export type ToolDescriptor = {
     name: string;
@@ -26,6 +27,7 @@ export interface ConversationalAgentOptions {
     network?: NetworkType;
     openAIApiKey: string;
     openAIModelName?: string;
+    llmProvider?: 'openai' | 'anthropic';
     verbose?: boolean;
     operationalMode?: AgentOperationalMode;
     userAccountId?: string;
@@ -61,16 +63,16 @@ export declare class ConversationalAgent {
     hcs10Plugin: HCS10Plugin;
     hcs2Plugin: HCS2Plugin;
     inscribePlugin: InscribePlugin;
-    hbarTransferPlugin: HbarTransferPlugin;
+    hbarPlugin: HbarPlugin;
     stateManager: IStateManager;
     private options;
-    protected logger: Logger;
-    private contentStoreManager?;
-    private memoryManager?;
-    private mcpConnectionStatus;
+    logger: Logger;
+    contentStoreManager?: ContentStoreManager;
+    memoryManager?: SmartMemoryManager | undefined;
+    private entityTools?;
     constructor(options: ConversationalAgentOptions);
     /**
-     * Initialize the conversational agent with Hedera network connection and AI configuration
+     * Initialize the conversational agent with Hedera Hashgraph connection and AI configuration
      * @throws {Error} If account ID or private key is missing
      * @throws {Error} If initialization fails
      */
@@ -186,18 +188,18 @@ export declare class ConversationalAgent {
      * Detect the private key type by querying the account info from mirror node
      * @param {string} accountId - The Hedera account ID
      * @param {string} privateKey - The private key string
-     * @param {NetworkType} network - The Hedera network
+     * @param {NetworkType} network - The Hedera Hashgraph
      * @returns {Promise<PrivateKey>} The appropriate PrivateKey instance
      */
     private detectPrivateKeyType;
     /**
-     * Resolve entity references in the message content
+     * Resolve entity references using LLM-based resolver
      * @param content - Message content to resolve
      * @returns Resolved message content with entity IDs replaced
      */
     private resolveEntitiesInMessage;
     /**
-     * Extract and store entity associations from transaction responses
+     * Extract and store entities from agent responses
      * @param response - Agent response containing potential entity information
      * @param originalMessage - Original user message for context
      */
@@ -213,17 +215,6 @@ export declare class ConversationalAgent {
      * @private
      */
     private connectMCP;
-    /**
-     * Start MCP connections without blocking initialization
-     * @private
-     */
-    private startConnections;
-    /**
-     * Connect to a single MCP server
-     * @param {MCPServerConfig} server - Server configuration
-     * @private
-     */
-    private connectServer;
     /**
      * Get MCP connection status for all servers
      * @returns {Map<string, MCPConnectionStatus>} Connection status map
@@ -239,4 +230,5 @@ export declare class ConversationalAgent {
      * Clean up resources
      */
     cleanup(): Promise<void>;
+    private extractResponseText;
 }

package/dist/types/index.d.ts

@@ -1,7 +1,7 @@
 export { HCS10Plugin } from './plugins/hcs-10/HCS10Plugin';
 export { HCS2Plugin } from './plugins/hcs-2/HCS2Plugin';
 export { InscribePlugin } from './plugins/inscribe/InscribePlugin';
-export { HbarTransferPlugin } from './plugins/hbar-transfer/HbarTransferPlugin';
+export { HbarPlugin } from './plugins/hbar/HbarPlugin';
 export { HCS10Plugin as OpenConvAIPlugin } from './plugins/hcs-10/HCS10Plugin';
 export { ConversationalAgent } from './conversational-agent';
 export type { ConversationalAgentOptions } from './conversational-agent';
@@ -11,6 +11,8 @@ export { createAgent } from './agent-factory';
 export { LangChainProvider, type AIProvider, type VercelAIProvider, type BAMLProvider, } from './providers';
 export * from 'hedera-agent-kit';
 export type { IStateManager } from '@hashgraphonline/standards-agent-kit';
-export type { MCPServerConfig, MCPConnectionStatus, MCPToolInfo } from './mcp/types';
-export { MCPServers, createMCPConfig, validateServerConfig } from './mcp/helpers';
+export type { MCPServerConfig, MCPConnectionStatus, MCPToolInfo, } from './mcp/types';
+export { MCPServers, createMCPConfig, validateServerConfig, } from './mcp/helpers';
 export * from './memory';
+export { createEntityTools, ResolveEntitiesTool, ExtractEntitiesTool, } from './tools/EntityResolverTool';
+export { ContentStoreManager } from './services/ContentStoreManager';

package/dist/types/langchain-agent.d.ts

@@ -1,10 +1,12 @@
 import { BaseAgent, ConversationContext, ChatResponse, OperationalMode, UsageStats } from './base-agent';
+import { MCPConnectionStatus } from './mcp/types';
 
 export declare class LangChainAgent extends BaseAgent {
     private executor;
     private systemMessage;
     private mcpManager?;
     private smartMemory;
+    private mcpConnectionStatus;
     boot(): Promise<void>;
     chat(message: string, context?: ConversationContext): Promise<ChatResponse>;
     shutdown(): Promise<void>;
@@ -12,18 +14,19 @@ export declare class LangChainAgent extends BaseAgent {
     getUsageStats(): UsageStats;
     getUsageLog(): UsageStats[];
     clearUsageStats(): void;
+    getMCPConnectionStatus(): Map<string, MCPConnectionStatus>;
     private createAgentKit;
     private createExecutor;
     private handleError;
     private initializeMCP;
     /**
-     * Connect to MCP servers asynchronously after agent boot
+     * Connect to MCP servers asynchronously after agent boot with background timeout pattern
      */
     connectMCPServers(): Promise<void>;
     /**
-     * Connect to a single MCP server
+     * Connect to a single MCP server in background with timeout
      */
-    private connectServer;
+    private connectServerInBackground;
     /**
      * Check if a string is valid JSON
      */

package/dist/types/memory/SmartMemoryManager.d.ts

@@ -69,16 +69,22 @@ export interface MemoryStats {
     usagePercentage: number;
 }
 /**
+ * TODO: investigate using chroma / rag for long term memory
  * Smart memory manager that combines active memory window with long-term storage
  * Provides context-aware memory management with automatic pruning and searchable history
  */
 export declare class SmartMemoryManager {
     private memoryWindow;
-    private contentStorage;
+    private _contentStorage;
     private tokenCounter;
     private config;
     private static readonly DEFAULT_CONFIG;
     constructor(config?: SmartMemoryConfig);
+    /**
+     * Get the content storage instance for file/content reference operations
+     * @returns ContentStorage instance
+     */
+    get contentStorage(): ContentStorage;
     /**
      * Add a message to the active memory window
      * Automatically handles pruning and storage of displaced messages

package/dist/types/memory/TokenCounter.d.ts

@@ -10,7 +10,7 @@ export declare class TokenCounter {
     private modelName;
     private static readonly MESSAGE_OVERHEAD;
     private static readonly ROLE_OVERHEAD;
-    constructor(modelName?: TiktokenModel);
+    constructor(modelName?: string | TiktokenModel);
     /**
      * Count tokens in raw text content
      * @param text - The text to count tokens for

package/dist/types/plugins/hbar/AirdropToolWrapper.d.ts

@@ -0,0 +1,43 @@
+import { StructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+
+export declare class AirdropToolWrapper extends StructuredTool {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        tokenId: z.ZodString;
+        recipients: z.ZodArray<z.ZodObject<{
+            accountId: z.ZodString;
+            amount: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+        }, "strip", z.ZodTypeAny, {
+            accountId: string;
+            amount: string | number;
+        }, {
+            accountId: string;
+            amount: string | number;
+        }>, "many">;
+        memo: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        tokenId: string;
+        recipients: {
+            accountId: string;
+            amount: string | number;
+        }[];
+        memo?: string | undefined;
+    }, {
+        tokenId: string;
+        recipients: {
+            accountId: string;
+            amount: string | number;
+        }[];
+        memo?: string | undefined;
+    }>;
+    private originalTool;
+    private agentKit;
+    private logger;
+    constructor(originalTool: StructuredTool, agentKit: unknown);
+    _call(input: z.infer<typeof this.schema>): Promise<string>;
+    private convertToSmallestUnits;
+    private getTokenInfo;
+    private queryTokenInfo;
+}

package/dist/{cjs/plugins/hbar-transfer/HbarTransferPlugin.d.ts → types/plugins/hbar/HbarPlugin.d.ts}

@@ -1,6 +1,6 @@
 import { GenericPluginContext, HederaTool, BasePlugin } from 'hedera-agent-kit';
 
-export declare class HbarTransferPlugin extends BasePlugin {
+export declare class HbarPlugin extends BasePlugin {
     id: string;
     name: string;
     description: string;
@@ -8,6 +8,7 @@ export declare class HbarTransferPlugin extends BasePlugin {
     author: string;
     namespace: string;
     private tools;
+    private originalAirdropTool;
     initialize(context: GenericPluginContext): Promise<void>;
     private initializeTools;
     getTools(): HederaTool[];

package/dist/{cjs/plugins/hbar-transfer → types/plugins/hbar}/TransferHbarTool.d.ts

@@ -29,7 +29,7 @@ declare const TransferHbarZodSchemaCore: z.ZodObject<{
 /**
  * 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.
+ * Extends BaseHederaTransactionTool to handle HBAR transfer transactions on the Hedera Hashgraph.
  */
 export declare class TransferHbarTool extends BaseHederaTransactionTool<typeof TransferHbarZodSchemaCore> {
     name: string;

package/dist/types/plugins/hbar/index.d.ts

@@ -0,0 +1,3 @@
+export * from './TransferHbarTool';
+export * from './AccountBuilder';
+export * from './types';

package/dist/types/plugins/index.d.ts

@@ -1,4 +1,5 @@
 export { HCS10Plugin } from './hcs-10';
 export { HCS2Plugin } from './hcs-2';
 export { InscribePlugin } from './inscribe';
-export { HbarTransferPlugin } from './hbar-transfer';
+export { HbarPlugin } from './hbar/HbarPlugin';
+export * from './hbar';

package/dist/types/services/EntityResolver.d.ts

@@ -0,0 +1,26 @@
+import { EntityAssociation } from '../memory/SmartMemoryManager';
+
+export interface EntityResolverConfig {
+    apiKey: string;
+    modelName?: string;
+}
+/**
+ * LLM-based entity resolver that replaces brittle regex patterns
+ */
+export declare class EntityResolver {
+    private llm;
+    constructor(config: EntityResolverConfig);
+    /**
+     * Resolve entity references using LLM instead of regex
+     */
+    resolveReferences(message: string, entities: EntityAssociation[]): Promise<string>;
+    /**
+     * Extract entities from agent response using LLM
+     */
+    extractEntities(response: unknown, userMessage: string): Promise<Array<{
+        id: string;
+        name: string;
+        type: string;
+        transactionId?: string;
+    }>>;
+}

package/dist/types/tools/EntityResolverTool.d.ts

@@ -0,0 +1,104 @@
+import { StructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+
+declare const ResolveEntitiesSchema: z.ZodObject<{
+    message: z.ZodString;
+    entities: z.ZodArray<z.ZodObject<{
+        entityId: z.ZodString;
+        entityName: z.ZodString;
+        entityType: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        entityId: string;
+        entityName: string;
+        entityType: string;
+    }, {
+        entityId: string;
+        entityName: string;
+        entityType: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    entities: {
+        entityId: string;
+        entityName: string;
+        entityType: string;
+    }[];
+}, {
+    message: string;
+    entities: {
+        entityId: string;
+        entityName: string;
+        entityType: string;
+    }[];
+}>;
+declare const ExtractEntitiesSchema: z.ZodObject<{
+    response: z.ZodString;
+    userMessage: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    response: string;
+    userMessage: string;
+}, {
+    response: string;
+    userMessage: string;
+}>;
+export declare class ResolveEntitiesTool extends StructuredTool {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        message: z.ZodString;
+        entities: z.ZodArray<z.ZodObject<{
+            entityId: z.ZodString;
+            entityName: z.ZodString;
+            entityType: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            entityId: string;
+            entityName: string;
+            entityType: string;
+        }, {
+            entityId: string;
+            entityName: string;
+            entityType: string;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        message: string;
+        entities: {
+            entityId: string;
+            entityName: string;
+            entityType: string;
+        }[];
+    }, {
+        message: string;
+        entities: {
+            entityId: string;
+            entityName: string;
+            entityType: string;
+        }[];
+    }>;
+    private llm;
+    constructor(apiKey: string, modelName?: string);
+    _call(input: z.infer<typeof ResolveEntitiesSchema>): Promise<string>;
+    private groupEntitiesByType;
+    private buildEntityContext;
+}
+export declare class ExtractEntitiesTool extends StructuredTool {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        response: z.ZodString;
+        userMessage: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        response: string;
+        userMessage: string;
+    }, {
+        response: string;
+        userMessage: string;
+    }>;
+    private llm;
+    constructor(apiKey: string, modelName?: string);
+    _call(input: z.infer<typeof ExtractEntitiesSchema>): Promise<string>;
+}
+export declare function createEntityTools(apiKey: string, modelName?: string): {
+    resolveEntities: ResolveEntitiesTool;
+    extractEntities: ExtractEntitiesTool;
+};
+export {};

package/dist/types/types/inscription.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Inscription quote response from standards-agent-kit
+ */
+export interface InscriptionQuote {
+    totalCostHbar: string;
+    validUntil: string;
+    breakdown: {
+        transfers: Array<{
+            type: string;
+            amount: string;
+            description: string;
+        }>;
+    };
+}
+/**
+ * Parameters for inscription tool calls with quote support
+ */
+export interface InscriptionToolParams {
+    [key: string]: unknown;
+    quoteOnly?: boolean;
+}
+/**
+ * Result from inscription tool execution
+ */
+export interface InscriptionResult {
+    success: boolean;
+    transactionId?: string;
+    message: string;
+    quote?: InscriptionQuote;
+}
+/**
+ * User confirmation status for inscription
+ */
+export interface InscriptionConfirmation {
+    confirmed: boolean;
+    reason?: string;
+}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@hashgraphonline/conversational-agent",
-  "version": "0.1.209",
+  "version": "0.1.211",
   "type": "module",
   "main": "./dist/cjs/index.cjs",
   "module": "./dist/esm/index.js",
   "types": "./dist/types/index.d.ts",
+  "bin": {
+    "conversational-agent": "./bin/conversational-agent-cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
@@ -18,6 +21,8 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "bin",
+    "cli/dist",
     "dist",
     "src",
     "LICENSE",
@@ -31,6 +36,7 @@
     "build:cjs": "BUILD_FORMAT=cjs vite build",
     "build:umd": "BUILD_FORMAT=umd vite build",
     "build": "pnpm run clean && pnpm run build:es && pnpm run build:cjs",
+    "build:all": "pnpm run build && pnpm run cli:build",
     "prepublishOnly": "pnpm run build",
     "release": "pnpm publish --access public",
     "release:canary": "pnpm run prepublishOnly && pnpm publish --tag canary --access public",
@@ -39,7 +45,7 @@
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "typecheck": "tsc --noEmit",
-    "cli:build": "pnpm run build && cd cli && pnpm install && pnpm build",
+    "cli:build": "cd cli && pnpm install && pnpm build",
     "cli": "tsx cli/scripts/run-cli.ts",
     "cli:dev": "cd cli && pnpm dev",
     "example:mcp-filesystem": "tsx examples/mcp-filesystem-demo.ts",
@@ -86,13 +92,16 @@
   },
   "dependencies": {
     "@hashgraph/sdk": "^2.69.0",
-    "@hashgraphonline/standards-agent-kit": "0.2.122",
-    "@hashgraphonline/standards-sdk": "0.0.170",
+    "@hashgraphonline/standards-agent-kit": "0.2.125",
+    "@langchain/anthropic": "^0.3.26",
+    "@hashgraphonline/standards-sdk": "^0.0.180",
     "@langchain/core": "^0.3.66",
     "@langchain/openai": "^0.6.3",
     "@modelcontextprotocol/sdk": "^1.17.0",
+    "axios": "^1.11.0",
     "bignumber.js": "^9.3.1",
     "electron-log": "^5.4.2",
+    "ethers": "^6.15.0",
     "hedera-agent-kit": "^2.0.3",
     "langchain": "^0.3.3",
     "tiktoken": "^1.0.21",

package/src/base-agent.ts

@@ -11,7 +11,7 @@ import {
 import type { CostCalculation } from 'hedera-agent-kit';
 import type { AIProvider, VercelAIProvider, BAMLProvider } from './providers';
 import { Logger } from '@hashgraphonline/standards-sdk';
-import type { MCPServerConfig } from './mcp/types';
+import type { MCPServerConfig, MCPConnectionStatus } from './mcp/types';
 
 export interface ToolFilterConfig {
   namespaceWhitelist?: string[];
@@ -115,16 +115,17 @@ export abstract class BaseAgent {
   abstract getUsageStats(): UsageStats;
   abstract getUsageLog(): UsageStats[];
   abstract clearUsageStats(): void;
+  abstract connectMCPServers(): Promise<void>;
+  abstract getMCPConnectionStatus(): Map<string, MCPConnectionStatus>;
 
-  getCore(): HederaAgentKit | undefined {
+  public getCore(): HederaAgentKit | undefined {
     return this.agentKit;
   }
 
-  protected filterTools(
-    tools: StructuredTool[]
-  ): StructuredTool[] {
+  protected filterTools(tools: StructuredTool[]): StructuredTool[] {
     let filtered = [...tools];
     const filter = this.config.filtering;
+
     if (!filter) return filtered;
 
     if (filter.namespaceWhitelist?.length) {
@@ -160,7 +161,7 @@ export abstract class BaseAgent {
 
     parts.push(
       `You are a helpful Hedera assistant. Your primary operator account is ${operatorId}. ` +
-        `You have tools to interact with the Hedera network. ` +
+        `You have tools to interact with the Hedera Hashgraph. ` +
         `When using any tool, provide all necessary parameters as defined by that tool's schema and description.`
     );
 
@@ -198,11 +199,15 @@ export abstract class BaseAgent {
         );
       } else {
         parts.push(
-          `\nOPERATIONAL MODE: 'returnBytes'. Your goal is to provide transaction bytes directly. ` +
+          `\nOPERATIONAL MODE: 'returnBytes'. Your goal is to provide transaction bytes when possible. ` +
             `When a user asks for a transaction to be prepared (e.g., for them to sign, or for scheduling without the default scheduling flow), ` +
-            `you MUST call the appropriate tool. If you want raw bytes for the user to sign for their own account ${
+            `you MUST call the appropriate tool. ` +
+            `IMPORTANT: Only use metaOption 'returnBytes: true' for tools that explicitly support it (like HBAR transfers, token operations). ` +
+            `Many tools (inscriptions, HCS-2, HCS-20, etc.) do NOT support returnBytes and will execute directly - this is expected behavior. ` +
+            `For tools without returnBytes support, simply call them with their standard parameters. ` +
+            `If you need raw bytes for the user to sign for their own account ${
               userAccId || 'if specified'
-            }, ensure the tool constructs the transaction body accordingly and use metaOption 'returnBytes: true' if available, or ensure the builder is configured for the user.`
+            }, ensure the tool constructs the transaction body accordingly when returnBytes IS supported.`
         );
       }
     }

package/src/config/system-message.ts

@@ -1,12 +1,21 @@
-export const getSystemMessage = (accountId: string): string => `You are a helpful assistant managing Hashgraph Online HCS-10 connections, messages, HCS-2 registries, and content inscription.
+export const getSystemMessage = (
+  accountId: string
+): string => `You are a helpful assistant managing Hashgraph Online HCS-10 connections, messages, HCS-2 registries, content inscription, and Hedera Hashgraph operations.
 
 You have access to tools for:
 - HCS-10: registering agents, finding registered agents, initiating connections, listing active connections, sending messages over connections, and checking for new messages
 - HCS-2: creating registries, registering entries, updating entries, deleting entries, migrating registries, and querying registry contents
 - Inscription: inscribing content from URLs, files, or buffers, creating Hashinal NFTs, and retrieving inscriptions
+- Hedera Token Service (HTS): creating tokens, transferring tokens, airdropping tokens, and managing token operations
 
 *** IMPORTANT CONTEXT ***
 You are currently operating as agent: ${accountId} on the Hashgraph Online network
 When users ask about "my profile", "my account", "my connections", etc., use this account ID: ${accountId}
 
-Remember the connection numbers when listing connections, as users might refer to them.`
+*** CRITICAL ENTITY HANDLING RULES ***
+- When users refer to entities (tokens, topics, accounts) with pronouns like "it", "that", "the token/topic", etc., ALWAYS use the most recently created entity of that type
+- Entity IDs look like "0.0.XXXXXX" and are stored in memory after creation
+- NEVER use example or placeholder IDs like "0.0.123456" - always use actual created entity IDs
+- Account ID ${accountId} is NOT a token - tokens and accounts are different entities
+
+Remember the connection numbers when listing connections, as users might refer to them.`;

package/src/context/ReferenceContextManager.ts

@@ -275,7 +275,7 @@ export class ReferenceContextManager {
     }
     
     if (includeActions) {
-      display += `\n💡 You can say "inscribe it" to inscribe this content to the Hedera network.`;
+      display += `\n💡 You can say "inscribe it" to inscribe this content to the Hedera Hashgraph.`;
     }
     
     display += `\n\n*Reference ID: ${reference.referenceId.substring(0, 12)}...*`;