@hashgraphonline/conversational-agent 0.1.217 → 0.1.218

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/constants/entity-references.d.ts

@@ -0,0 +1,18 @@
+import { EntityFormat } from '../services/formatters/types';
+/**
+ * Common entity reference patterns used across the application
+ */
+export declare const ENTITY_PATTERNS: {
+    readonly TOPIC_REFERENCE: "the topic";
+    readonly TOKEN_REFERENCE: "the token";
+    readonly ACCOUNT_REFERENCE: "the account";
+    readonly TRANSACTION_REFERENCE: "the transaction";
+    readonly CONTRACT_REFERENCE: "the contract";
+};
+export declare const ENTITY_TYPES: {
+    readonly TOPIC: EntityFormat.TOPIC_ID;
+    readonly TOKEN: EntityFormat.TOKEN_ID;
+    readonly ACCOUNT: EntityFormat.ACCOUNT_ID;
+    readonly TRANSACTION: "transaction";
+    readonly CONTRACT: EntityFormat.CONTRACT_ID;
+};

package/dist/cjs/constants/form-priorities.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Form field priorities for progressive disclosure
+ */
+export declare const FIELD_PRIORITIES: {
+    readonly ESSENTIAL: "essential";
+    readonly COMMON: "common";
+    readonly ADVANCED: "advanced";
+    readonly EXPERT: "expert";
+};
+/**
+ * Form field types
+ */
+export declare const FORM_FIELD_TYPES: {
+    readonly TEXT: "text";
+    readonly NUMBER: "number";
+    readonly SELECT: "select";
+    readonly CHECKBOX: "checkbox";
+    readonly TEXTAREA: "textarea";
+    readonly FILE: "file";
+    readonly ARRAY: "array";
+    readonly OBJECT: "object";
+    readonly CURRENCY: "currency";
+    readonly PERCENTAGE: "percentage";
+};

package/dist/cjs/constants/index.d.ts

@@ -0,0 +1,4 @@
+export { ERROR_MESSAGES, STATUS_MESSAGES } from './messages';
+export { ENTITY_PATTERNS, ENTITY_TYPES } from './entity-references';
+export { FIELD_PRIORITIES, FORM_FIELD_TYPES } from './form-priorities';
+export { TEST_ACCOUNT_IDS, TEST_NETWORK_CONFIGS, TEST_MESSAGES, TEST_TOOL_NAMES, TEST_KEYS, TEST_ERRORS, MOCK_FORM_DATA } from './test-constants';

package/dist/cjs/constants/messages.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Common error messages and user feedback strings
+ */
+export declare const ERROR_MESSAGES: {
+    readonly TOO_MANY_REQUESTS: "Too many requests. Please wait a moment and try again.";
+    readonly RATE_LIMITED: "I'm receiving too many requests right now. Please wait a moment and try again.";
+    readonly SYSTEM_ERROR: "System error occurred";
+    readonly INVALID_INPUT: "Invalid input provided";
+    readonly NETWORK_ERROR: "Network error occurred";
+};
+/**
+ * Common success and status messages
+ */
+export declare const STATUS_MESSAGES: {
+    readonly OPERATION_SUCCESSFUL: "Operation completed successfully";
+    readonly PROCESSING: "Processing your request...";
+    readonly READY: "Ready to process requests";
+    readonly INITIALIZING: "Initializing...";
+};

package/dist/cjs/constants/test-constants.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Common test constants to reduce string duplication in test files
+ */
+export declare const TEST_ACCOUNT_IDS: {
+    readonly OPERATOR: "0.0.12345";
+    readonly TARGET: "0.0.67890";
+    readonly SENDER: "0.0.800";
+    readonly RECEIVER: "0.0.801";
+};
+export declare const TEST_NETWORK_CONFIGS: {
+    readonly TESTNET: "testnet";
+    readonly MAINNET: "mainnet";
+    readonly PREVIEWNET: "previewnet";
+};
+export declare const TEST_MESSAGES: {
+    readonly SIMPLE_QUERY: "test message";
+    readonly AGENT_NOT_INITIALIZED: "Agent not initialized. Call boot() first.";
+    readonly PROCESSING_ERROR: "Error processing message";
+    readonly TEST_RESPONSE: "Test response";
+};
+export declare const TEST_TOOL_NAMES: {
+    readonly MOCK_TOOL: "mock-tool";
+    readonly HEDERA_GET_ACCOUNT: "hedera_get_account_info";
+    readonly HEDERA_TRANSFER: "hedera-account-transfer-hbar";
+    readonly INSCRIBE_HASHINAL: "inscribeHashinal";
+};
+export declare const TEST_KEYS: {
+    readonly OPENAI_API_KEY: "test-openai-key";
+    readonly PRIVATE_KEY: "mock-private-key";
+    readonly OPERATOR_KEY: "test-operator-key";
+};
+export declare const TEST_ERRORS: {
+    readonly INITIALIZATION_ERROR: "Initialization error";
+    readonly NETWORK_ERROR: "Network error";
+    readonly VALIDATION_ERROR: "Validation error";
+};
+export declare const MOCK_FORM_DATA: {
+    readonly FORM_ID: "mock-form-id";
+    readonly TOOL_NAME: "mock-tool";
+    readonly FIELD_NAME: "test-field";
+    readonly FIELD_TYPE: "text";
+};

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

@@ -8,7 +8,7 @@ import { InscribePlugin } from './plugins/inscribe/InscribePlugin';
 import { HbarPlugin } from './plugins/hbar/HbarPlugin';
 import { IStateManager } from '@hashgraphonline/standards-agent-kit';
 import { MCPServerConfig, MCPConnectionStatus } from './mcp/types';
-import { ContentStoreManager } from './services/ContentStoreManager';
+import { ContentStoreManager } from './services/content-store-manager';
 import { SmartMemoryManager, SmartMemoryConfig } from './memory';
 import { FormSubmission } from './forms/types';
 
@@ -17,7 +17,7 @@ export type ToolDescriptor = {
     namespace?: string;
 };
 export type ChatHistoryItem = {
-    type: 'human' | 'ai';
+    type: 'human' | 'ai' | 'system';
     content: string;
 };
 export type AgentInstance = ReturnType<typeof createAgent>;
@@ -60,6 +60,7 @@ export interface ConversationalAgentOptions {
  * @returns A new instance of the ConversationalAgent class.
  */
 export declare class ConversationalAgent {
+    private static readonly NOT_INITIALIZED_ERROR;
     protected agent?: AgentInstance;
     hcs10Plugin: HCS10Plugin;
     hcs2Plugin: HCS2Plugin;
@@ -192,12 +193,6 @@ export declare class ConversationalAgent {
      * Create a ConversationalAgent with MCP servers configured
      */
     static withMCP(options: ConversationalAgentOptions, mcpServers: MCPServerConfig[]): ConversationalAgent;
-    /**
-     * 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

package/dist/cjs/core/{ToolRegistry.d.ts → tool-registry.d.ts}

@@ -1,7 +1,5 @@
 import { StructuredTool } from '@langchain/core/tools';
-import { z } from 'zod';
 import { Logger } from '@hashgraphonline/standards-sdk';
-import { FormValidatingToolWrapper } from '../langchain/FormValidatingToolWrapper';
 
 /**
  * Tool capabilities configuration for registry entries
@@ -12,6 +10,15 @@ export interface ToolCapabilities {
     priority: 'low' | 'medium' | 'high' | 'critical';
     category: 'core' | 'extension' | 'mcp';
 }
+/**
+ * Entity resolution format preferences for tools
+ */
+export interface EntityResolutionPreferences {
+    inscription?: 'hrl' | 'topicId' | 'metadata' | 'any';
+    token?: 'tokenId' | 'address' | 'symbol' | 'any';
+    nft?: 'serialNumber' | 'metadata' | 'hrl' | 'any';
+    account?: 'accountId' | 'alias' | 'evmAddress' | 'any';
+}
 /**
  * Tool metadata for comprehensive tool information
  */
@@ -23,6 +30,7 @@ export interface ToolMetadata {
     capabilities: ToolCapabilities;
     dependencies: string[];
     schema: unknown;
+    entityResolutionPreferences?: EntityResolutionPreferences;
 }
 /**
  * Registry entry containing tool instance and metadata
@@ -30,7 +38,6 @@ export interface ToolMetadata {
 export interface ToolRegistryEntry {
     tool: StructuredTool;
     metadata: ToolMetadata;
-    wrapper?: FormValidatingToolWrapper<z.ZodObject<z.ZodRawShape>> | undefined;
     originalTool: StructuredTool;
 }
 /**
@@ -109,10 +116,6 @@ export declare class ToolRegistry {
      * Check if tool has render configuration
      */
     private hasRenderConfig;
-    /**
-     * Determine if tool should be wrapped
-     */
-    private shouldWrapTool;
     /**
      * Check if schema is ZodObject-like
      */

package/dist/{types/execution/ExecutionPipeline.d.ts → cjs/execution/execution-pipeline.d.ts}

@@ -1,7 +1,7 @@
 import { Logger } from '@hashgraphonline/standards-sdk';
-import { SmartMemoryManager } from '../memory/SmartMemoryManager';
-import { FormEngine, ToolExecutionResult } from '../forms/FormEngine';
-import { ToolRegistry, ToolRegistryEntry } from '../core/ToolRegistry';
+import { SmartMemoryManager } from '../memory/smart-memory-manager';
+import { FormEngine, ToolExecutionResult } from '../forms/form-engine';
+import { ToolRegistry, ToolRegistryEntry } from '../core/tool-registry';
 
 /**
  * Session context for tool execution

package/dist/cjs/forms/field-guidance-registry.d.ts

@@ -0,0 +1,108 @@
+import { FormFieldType, FieldOption } from './types';
+
+/**
+ * Field guidance configuration for providing contextual help and suggestions
+ */
+export interface FieldGuidance {
+    /**
+     * Suggestions to show as placeholder or examples
+     */
+    suggestions?: string[];
+    /**
+     * Predefined options for select fields
+     */
+    predefinedOptions?: FieldOption[];
+    /**
+     * Warning messages for specific patterns to avoid
+     */
+    warnings?: {
+        pattern: RegExp;
+        message: string;
+    }[];
+    /**
+     * Validation rules specific to the field context
+     */
+    validationRules?: {
+        /**
+         * Patterns that should be rejected
+         */
+        rejectPatterns?: {
+            pattern: RegExp;
+            reason: string;
+        }[];
+        /**
+         * Minimum quality requirements
+         */
+        qualityChecks?: {
+            minNonTechnicalWords?: number;
+            requireSpecificTerms?: string[];
+            forbidTechnicalTerms?: string[];
+        };
+    };
+    /**
+     * Field type override for specific contexts
+     */
+    fieldTypeOverride?: FormFieldType;
+    /**
+     * Help text specific to the tool context
+     */
+    contextualHelpText?: string;
+}
+/**
+ * Tool-specific field configurations
+ */
+export interface ToolFieldConfiguration {
+    /**
+     * Tool name or pattern to match
+     */
+    toolPattern: string | RegExp;
+    /**
+     * Field-specific guidance
+     */
+    fields: Record<string, FieldGuidance>;
+    /**
+     * Global guidance for all fields in this tool
+     */
+    globalGuidance?: {
+        /**
+         * General warnings to show
+         */
+        warnings?: string[];
+        /**
+         * Quality standards for this tool
+         */
+        qualityStandards?: string[];
+    };
+}
+/**
+ * Registry for field guidance configurations
+ */
+declare class FieldGuidanceRegistry {
+    private configurations;
+    /**
+     * Register field guidance for a specific tool
+     */
+    registerToolConfiguration(config: ToolFieldConfiguration): void;
+    /**
+     * Get field guidance for a specific tool and field
+     */
+    getFieldGuidance(toolName: string, fieldName: string): FieldGuidance | null;
+    /**
+     * Get global guidance for a tool
+     */
+    getGlobalGuidance(toolName: string): ToolFieldConfiguration['globalGuidance'] | null;
+    /**
+     * Validate field value against guidance rules
+     */
+    validateFieldValue(toolName: string, fieldName: string, value: unknown): {
+        isValid: boolean;
+        warnings: string[];
+        errors: string[];
+    };
+    /**
+     * Clear all configurations (useful for testing)
+     */
+    clear(): void;
+}
+export declare const fieldGuidanceRegistry: FieldGuidanceRegistry;
+export {};

package/dist/cjs/forms/form-generator.d.ts

@@ -112,12 +112,7 @@ export declare class FormGenerator {
      * @returns Object containing jsonSchema and uiSchema
      */
     generateJsonSchemaForm(zodSchema: z.ZodObject<z.ZodRawShape>, partialInput?: Record<string, unknown>, missingFields?: Set<string>): {
-        jsonSchema: import('zod-to-json-schema').JsonSchema7Type & {
-            $schema?: string | undefined;
-            definitions?: {
-                [key: string]: import('zod-to-json-schema').JsonSchema7Type;
-            } | undefined;
-        };
-        uiSchema: Record<string, Record<string, unknown>>;
+        jsonSchema: Record<string, unknown>;
+        uiSchema: Record<string, unknown>;
     };
 }

package/dist/cjs/forms/index.d.ts

@@ -1,2 +1,5 @@
 export * from './types';
 export * from './form-generator';
+export * from './form-engine';
+export * from './field-type-registry';
+export * from './field-guidance-registry';

package/dist/cjs/forms/types.d.ts

@@ -48,6 +48,13 @@ export interface FormField {
     options?: FieldOption[];
     renderConfig?: RenderConfigSchema;
     priority?: 'essential' | 'common' | 'advanced' | 'expert';
+    suggestions?: string[];
+    warnings?: string[];
+    contextualGuidance?: {
+        qualityStandards?: string[];
+        examples?: string[];
+        avoidPatterns?: string[];
+    };
 }
 /**
  * Form field types supported by the UI
@@ -71,6 +78,7 @@ export interface FieldOption {
     value: string;
     label: string;
     description?: string;
+    disabled?: boolean;
 }
 /**
  * Validation error from Zod
@@ -92,7 +100,7 @@ export interface FormSubmission {
         originalPrompt?: string;
         partialInput?: Record<string, unknown>;
         chatHistory?: Array<{
-            type: 'human' | 'ai';
+            type: 'human' | 'ai' | 'system';
             content: string;
         }>;
     };