@hashgraphonline/conversational-agent 0.1.208 → 0.1.210

package/bin/conversational-agent-cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+/**
+ * CLI executable for Conversational Agent
+ * This file enables running the CLI via npx
+ */
+
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Run the actual CLI from the cli directory
+const cliPath = join(__dirname, '..', 'cli', 'dist', 'cli.js');
+
+const child = spawn('node', [cliPath, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  shell: false
+});
+
+child.on('exit', (code) => {
+  process.exit(code || 0);
+});
+
+child.on('error', (err) => {
+  console.error('Failed to start CLI:', err);
+  process.exit(1);
+});

package/cli/readme.md

@@ -0,0 +1,181 @@
+# Hedera Conversational Agent CLI
+
+A beautiful command-line interface for the Hedera Conversational Agent, built with [Ink](https://github.com/vadimdemedes/ink) and styled following Hashgraph Online design patterns.
+
+## Features
+
+- 🎨 **Beautiful Terminal UI** - Styled with HCS improvement proposals design patterns
+- 💬 **Interactive Chat** - Chat with your Hedera agent in a clean terminal interface
+- 🔐 **Secure Configuration** - Masked input for sensitive credentials
+- 🌈 **Gradient Text & Colors** - Brand-consistent color scheme
+- 🚀 **Fast & Responsive** - Built with React for smooth interactions
+- 📊 **Transaction Details** - See transaction IDs and network responses
+- 🎯 **HCS-10 Support** - Full support for agent connections and messaging
+- 🔧 **MCP Integration** - Configure Model Context Protocol servers for extended capabilities
+- 📁 **File Operations** - Built-in filesystem MCP server for file management
+- ⚙️ **Custom MCP Servers** - Add your own MCP servers for specialized tools
+
+## Installation
+
+For local development, the CLI uses the actual ConversationalAgent from the parent package:
+
+```bash
+# 1. Build the parent package first
+cd /path/to/conversational-agent
+pnpm install
+pnpm build
+
+# 2. The CLI will be built automatically via postinstall hook
+# Or build manually:
+cd cli
+pnpm install
+pnpm build
+```
+
+## Usage
+
+### Interactive Mode (Recommended)
+
+```bash
+# From the parent conversational-agent directory
+pnpm cli
+
+# This automatically builds if needed and runs the CLI
+```
+
+### With Command Line Arguments
+
+```bash
+conversational-agent \
+  --account-id=0.0.12345 \
+  --private-key=your-private-key \
+  --network=testnet \
+  --openai-api-key=sk-...
+```
+
+### Using Environment Variables
+
+The CLI automatically loads configuration from `.env` in the conversational-agent root:
+
+```bash
+# .env file in conversational-agent directory
+HEDERA_ACCOUNT_ID=0.0.12345
+HEDERA_PRIVATE_KEY=your-private-key
+HEDERA_NETWORK=testnet
+OPENAI_API_KEY=sk-...
+MCP_SERVERS=[{"name":"filesystem","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/tmp"]}]
+```
+
+Then simply run: `pnpm cli`
+
+## Interface Overview
+
+### Welcome Screen
+- Beautiful ASCII art logo with gradient colors
+- Simple menu navigation with arrow keys
+- Options: Start Chat, Configure, MCP Servers, Exit
+
+### Configuration Screen
+- Terminal-style window with macOS-like controls
+- Secure input masking for sensitive data
+- Tab navigation between fields
+- Real-time validation
+
+### MCP Servers Screen
+- Configure Model Context Protocol servers
+- Enable/disable filesystem server with custom path
+- Add custom MCP servers with command and arguments
+- Live preview of available tools
+- Save configuration to environment
+
+### Chat Interface
+- Clean terminal aesthetic with prompt symbols
+- Color-coded messages (user, assistant, system)
+- Loading indicators with spinners
+- Transaction ID display
+- MCP server status and available tools
+- Escape key to return to menu
+
+## Design Features
+
+The CLI follows Hashgraph Online's design system:
+
+- **Brand Colors**: Primary blue (#5599fe), Green (#48df7b), Purple (#b56cff)
+- **Hedera Colors**: Purple (#8259ef), Blue (#2d84eb), Green (#3ec878)
+- **Terminal Window**: Rounded borders with window control dots
+- **Status Badges**: Color-coded status indicators
+- **Typography**: Monospace throughout with clear hierarchy
+
+## Keyboard Shortcuts
+
+- `↑/↓` - Navigate menus
+- `Enter` - Select/Submit
+- `Tab` - Next field (in configuration)
+- `Escape` - Return to main menu (from chat)
+- `Ctrl+C` - Exit application
+
+## Development
+
+```bash
+# Watch mode for development
+pnpm dev
+
+# Run tests
+pnpm test
+
+# Build for production
+pnpm build
+```
+
+## Examples
+
+### Basic Chat Interaction
+
+```
+$ Find all AI agents on the network
+→ I'll search for AI agents registered on the Hedera network...
+
+[INFO] Found 5 agents with AI capabilities
+→ Here are the AI agents I found:
+1. Agent: 0.0.12345 - "GPT Assistant"
+2. Agent: 0.0.23456 - "Code Helper"
+...
+
+$ Connect to agent 0.0.12345
+→ Initiating connection to agent 0.0.12345...
+[INFO] Transaction ID: 0.0.98765@1234567890.123
+→ Successfully connected! You can now send messages to this agent.
+```
+
+### MCP File Operations
+
+With filesystem MCP server enabled:
+
+```
+$ Create a new file called notes.txt with my meeting notes
+→ I'll create a notes.txt file for you with meeting notes...
+
+[INFO] MCP servers enabled: filesystem
+→ I've created notes.txt in your configured directory with the meeting notes.
+
+$ List all files in the current directory
+→ Here are the files in /tmp:
+- notes.txt (created just now)
+- data.json
+- config.yaml
+```
+
+### Custom MCP Server
+
+```
+$ Add GitHub repository operations
+→ I can help you interact with GitHub repositories...
+
+[INFO] MCP servers enabled: filesystem, github
+→ I now have access to GitHub operations. I can help you create issues, 
+  manage repositories, and work with pull requests.
+```
+
+## License
+
+Apache-2.0

package/dist/cjs/base-agent.d.ts

@@ -4,7 +4,7 @@ import { TransactionReceipt } from '@hashgraph/sdk';
 import { HederaAgentKit, ServerSigner, TokenUsageCallbackHandler, TokenUsage, BasePlugin, CostCalculation } from 'hedera-agent-kit';
 import { AIProvider, VercelAIProvider, BAMLProvider } from './providers';
 import { Logger } from '@hashgraphonline/standards-sdk';
-import { MCPServerConfig } from './mcp/types';
+import { MCPServerConfig, MCPConnectionStatus } from './mcp/types';
 
 export interface ToolFilterConfig {
     namespaceWhitelist?: string[];
@@ -93,6 +93,8 @@ export declare abstract class BaseAgent {
     abstract getUsageStats(): UsageStats;
     abstract getUsageLog(): UsageStats[];
     abstract clearUsageStats(): void;
+    abstract connectMCPServers(): Promise<void>;
+    abstract getMCPConnectionStatus(): Map<string, MCPConnectionStatus>;
     getCore(): HederaAgentKit | undefined;
     protected filterTools(tools: StructuredTool[]): StructuredTool[];
     protected buildSystemPrompt(): string;

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

@@ -1,20 +1,33 @@
 import { BasePlugin, AgentOperationalMode, MirrorNodeConfig } from 'hedera-agent-kit';
-import { NetworkType } from '@hashgraphonline/standards-sdk';
+import { Logger, NetworkType } from '@hashgraphonline/standards-sdk';
 import { createAgent } from './agent-factory';
 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 } from './mcp/types';
+import { MCPServerConfig, MCPConnectionStatus } from './mcp/types';
+import { ContentStoreManager } from './services/ContentStoreManager';
+import { SmartMemoryManager, SmartMemoryConfig } from './memory';
 
+export type ToolDescriptor = {
+    name: string;
+    namespace?: string;
+};
+export type ChatHistoryItem = {
+    type: 'human' | 'ai';
+    content: string;
+};
+export type AgentInstance = ReturnType<typeof createAgent>;
+export type MirrorNetwork = 'testnet' | 'mainnet' | 'previewnet';
 export interface ConversationalAgentOptions {
     accountId: string;
     privateKey: string;
     network?: NetworkType;
     openAIApiKey: string;
     openAIModelName?: string;
+    llmProvider?: 'openai' | 'anthropic';
     verbose?: boolean;
     operationalMode?: AgentOperationalMode;
     userAccountId?: string;
@@ -31,6 +44,10 @@ export interface ConversationalAgentOptions {
         namespace?: string;
     }) => boolean;
     mcpServers?: MCPServerConfig[];
+    /** Enable automatic entity memory functionality (default: true) */
+    entityMemoryEnabled?: boolean;
+    /** Configuration for entity memory system */
+    entityMemoryConfig?: SmartMemoryConfig;
 }
 /**
  * The ConversationalAgent class is an optional wrapper around the HederaConversationalAgent class,
@@ -42,18 +59,20 @@ export interface ConversationalAgentOptions {
  * @returns A new instance of the ConversationalAgent class.
  */
 export declare class ConversationalAgent {
-    private agent?;
+    protected agent?: AgentInstance;
     hcs10Plugin: HCS10Plugin;
     hcs2Plugin: HCS2Plugin;
     inscribePlugin: InscribePlugin;
-    hbarTransferPlugin: HbarTransferPlugin;
+    hbarPlugin: HbarPlugin;
     stateManager: IStateManager;
     private options;
-    private logger;
-    private contentStoreManager?;
+    logger: Logger;
+    protected 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
      */
@@ -87,10 +106,7 @@ export declare class ConversationalAgent {
      * @returns {Promise<ChatResponse>} The agent's response
      * @throws {Error} If agent is not initialized
      */
-    processMessage(message: string, chatHistory?: {
-        type: 'human' | 'ai';
-        content: string;
-    }[]): Promise<ChatResponse>;
+    processMessage(message: string, chatHistory?: ChatHistoryItem[]): Promise<ChatResponse>;
     /**
      * Validates initialization options and throws if required fields are missing.
      *
@@ -172,12 +188,47 @@ 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 using LLM-based resolver
+     * @param content - Message content to resolve
+     * @returns Resolved message content with entity IDs replaced
+     */
+    private resolveEntitiesInMessage;
+    /**
+     * Extract and store entities from agent responses
+     * @param response - Agent response containing potential entity information
+     * @param originalMessage - Original user message for context
+     */
+    private extractAndStoreEntities;
+    /**
+     * Extract transaction ID from response if available
+     * @param response - Transaction response
+     * @returns Transaction ID or undefined
+     */
+    private extractTransactionId;
+    /**
+     * Connect to MCP servers asynchronously
+     * @private
+     */
+    private connectMCP;
+    /**
+     * Get MCP connection status for all servers
+     * @returns {Map<string, MCPConnectionStatus>} Connection status map
+     */
+    getMCPConnectionStatus(): Map<string, MCPConnectionStatus>;
+    /**
+     * Check if a specific MCP server is connected
+     * @param {string} serverName - Name of the server to check
+     * @returns {boolean} True if connected, false otherwise
+     */
+    isMCPServerConnected(serverName: string): boolean;
     /**
      * Clean up resources
      */
     cleanup(): Promise<void>;
+    private extractResponseText;
 }