@hashgraphonline/conversational-agent 0.2.107 → 0.2.110

package/README.md

@@ -133,7 +133,7 @@ When using `returnBytes` mode:
 
 - **Automatic Key Detection**: Smart detection of ED25519 and ECDSA key types via mirror node
 - **Multiple HCS Standards**: Built-in support for HCS-10, HCS-2, and inscription standards
-- **Three Plugin System**: HCS10Plugin, HCS2Plugin, and InscribePlugin
+- **Core Plugin Suite**: HCS10Plugin, HCS2Plugin, InscribePlugin, and HbarPlugin
 - **TypeScript Support**: Full type definitions for all components
 - **State Management**: Integrated state management for agent operations
 - **CLI Interface**: Beautiful terminal interface for interactive agent communication
@@ -188,16 +188,19 @@ The Conversational Agent includes all tools from the `hedera-agent-kit` v2 packa
 This package includes a beautiful terminal interface built with [Ink](https://github.com/vadimdemedes/ink) that follows Hashgraph Consensus Standards design patterns.
 
 ```bash
-# Run the interactive CLI
+# Run the interactive CLI from the source workspace
 pnpm cli
 
-# Or with environment variables
+# Or invoke the published binary with npx (no local build required)
+npx @hashgraphonline/conversational-agent
+
+# Provide credentials via environment variables (works for pnpm cli and npx)
 export HEDERA_ACCOUNT_ID=0.0.12345
 export HEDERA_PRIVATE_KEY=your-private-key
 export OPENAI_API_KEY=sk-your-openai-key
 pnpm cli
 
-# Or with command line arguments
+# Supply configuration through CLI flags
 pnpm cli -- --account-id=0.0.12345 --private-key=... --openai-api-key=sk-...
 ```
 
@@ -210,13 +213,34 @@ pnpm cli -- --account-id=0.0.12345 --private-key=... --openai-api-key=sk-...
 - 🚀 **Fast & Responsive** - Built with React for smooth interactions
 - 📊 **Transaction Details** - See transaction IDs and network responses
 
+### Headless Mode
+
+Use the same executable to run a single command without the interactive UI. Headless mode activates automatically when you pass a command argument or when the CLI receives non-interactive input.
+
+```bash
+# Pass the command immediately after the binary
+npx @hashgraphonline/conversational-agent "Register me as an AI agent named TestBot"
+
+# Or use the explicit flag (useful when the command contains leading dashes)
+npx @hashgraphonline/conversational-agent \
+  --account-id=0.0.12345 \
+  --private-key=... \
+  --openai-api-key=sk-... \
+  --command "Transfer 1 HBAR to 0.0.800"
+
+# From the workspace helper script
+pnpm cli -- --command "Find my pending connection requests"
+```
+
+Headless execution prints structured output prefixed with the speaker (for example `[assistant]`, `[error]`, `[transaction]`) and returns a non-zero exit code when an error occurs. This makes it suitable for automation, CI tasks, or scripting flows that need machine-readable responses.
+
 ## Creating Custom Plugins
 
 You can extend the conversational agent with custom plugins. Here's how to create one:
 
 ### Plugin Structure
 
-See our comprehensive [Plugin Development Guide](docs/PLUGIN_DEVELOPMENT.md) for detailed instructions.
+See the [Conversational Agent documentation](https://hashgraphonline.com/docs/libraries/conversational-agent/) for detailed plugin development guidance.
 
 ```typescript
 import {
@@ -320,28 +344,39 @@ const response = await agent.processMessage(
 4. **State Management**: If your plugin needs state, consider implementing a custom state manager
 5. **Documentation**: Provide clear descriptions for your plugin and tools
 
-For more details, see our [Plugin Development Guide](docs/PLUGIN_DEVELOPMENT.md).
+For more details, see the [Conversational Agent documentation](https://hashgraphonline.com/docs/libraries/conversational-agent/).
 
 ## Configuration Options
 
-| Option                                | Type                 | Default         | Description                                    |
-| ------------------------------------- | -------------------- | --------------- | ---------------------------------------------- |
-| `accountId`                           | string               | **required**    | Hedera account ID (e.g., '0.0.12345')          |
-| `privateKey`                          | string               | **required**    | Private key for the account                    |
-| `network`                             | NetworkType          | 'testnet'       | Network to connect to ('mainnet' or 'testnet') |
-| `openAIApiKey`                        | string               | **required**    | OpenAI API key for the LLM                     |
-| `openAIModelName`                     | string               | 'gpt-4o'        | OpenAI model to use                            |
-| `verbose`                             | boolean              | false           | Enable verbose logging                         |
-| `operationalMode`                     | AgentOperationalMode | 'autonomous'    | 'autonomous' or 'returnBytes'                  |
-| `userAccountId`                       | string               | undefined       | User's account ID for transaction context      |
-| `customSystemMessagePreamble`         | string               | instructions    | Custom system message prefix                   |
-| `customSystemMessagePostamble`        | string               | undefined       | Custom system message suffix                   |
-| `additionalPlugins`                   | BasePlugin[]         | []              | Additional plugins to load                     |
-| `stateManager`                        | IStateManager        | OpenConvaiState | Custom state manager                           |
-| `scheduleUserTransactionsInBytesMode` | boolean              | false           | Schedule transactions in bytes mode            |
-| `mirrorNodeConfig`                    | MirrorNodeConfig     | undefined       | Custom mirror node configuration               |
-| `disableLogging`                      | boolean              | false           | Disable all logging                            |
-| `enabledPlugins`                      | string[]             | undefined       | Filter which plugins to enable by ID           |
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `accountId` | string | **required** | Hedera account ID (e.g., `0.0.12345`) |
+| `privateKey` | string | **required** | Private key for the account |
+| `network` | `NetworkType` | `'testnet'` | Network to connect to (`'mainnet'`, `'testnet'`, or `'previewnet'`) |
+| `openAIApiKey` | string | **required** | API key used for the default LLM provider and entity memory |
+| `openAIModelName` | string | `'gpt-4o'` | Preferred OpenAI model when `llmProvider` is `openai` |
+| `llmProvider` | `'openai' \| 'anthropic' \| 'openrouter'` | `'openai'` | Primary LLM provider for conversational responses |
+| `verbose` | boolean | false | Enable verbose logging |
+| `operationalMode` | `AgentOperationalMode` | `'autonomous'` | `'autonomous'` or `'returnBytes'` |
+| `userAccountId` | string | undefined | Account ID applied to scheduled transactions in returnBytes mode |
+| `customSystemMessagePreamble` | string | Hashgraph Online system prompt | Custom system message prefix |
+| `customSystemMessagePostamble` | string | undefined | Custom system message suffix |
+| `additionalPlugins` | `BasePlugin[]` | [] | Additional plugins to load |
+| `stateManager` | `IStateManager` | `OpenConvaiState` | Custom state manager |
+| `scheduleUserTransactionsInBytesMode` | boolean | false | Schedule transactions automatically in returnBytes mode |
+| `mirrorNodeConfig` | `MirrorNodeConfig` | undefined | Custom mirror node configuration |
+| `disableLogging` | boolean | false | Disable all logging |
+| `enabledPlugins` | string[] | undefined | Filter which plugins to enable by ID |
+| `toolFilter` | `(tool: { name: string; namespace?: string }) => boolean` | undefined | Predicate to include or exclude tools dynamically |
+| `mcpServers` | `MCPServerConfig[]` | undefined | Configure MCP servers for Model Context Protocol support |
+| `walletExecutor` | `(base64, network) => Promise<{ transactionId: string }>` | undefined | Custom executor for wallet-driven transaction submission |
+| `customSignerFactory` | `(args) => AbstractSigner` | undefined | Override signer selection when initializing the agent |
+| `entityMemoryEnabled` | boolean | true | Enable automatic entity extraction and storage |
+| `entityMemoryConfig` | `SmartMemoryConfig` | undefined | Custom configuration for entity memory |
+| `entityMemoryProvider` | `'openai' \| 'anthropic' \| 'openrouter'` | Matches `llmProvider` | Provider used for entity extraction and resolution |
+| `entityMemoryModelName` | string | Provider-specific default | Override model used for entity memory operations |
+| `openRouterApiKey` | string | undefined | API key when using OpenRouter (falls back to `openAIApiKey`) |
+| `openRouterBaseURL` | string | `'https://openrouter.ai/api/v1'` | Base URL for OpenRouter requests |
 
 ## Environment Variables
 
@@ -369,6 +404,7 @@ await agent.initialize();
 const hcs10Plugin = agent.hcs10Plugin;
 const hcs2Plugin = agent.hcs2Plugin;
 const inscribePlugin = agent.inscribePlugin;
+const hbarPlugin = agent.hbarPlugin;
 
 // Access the underlying Hedera agent
 const hederaAgent = agent.getConversationalAgent();
@@ -421,6 +457,7 @@ const hcs2Agent = ConversationalAgent.withHCS2({
 // ConversationalAgent.withSmartContract() - Only smart contract tools
 // ConversationalAgent.withAllStandards() - All HCS standards plugins (HCS-10, HCS-2, Inscribe)
 // ConversationalAgent.minimal() - Only basic account tools
+// ConversationalAgent.withMCP(options, mcpServers) - Configure Model Context Protocol servers
 ```
 
 ### Plugin Filtering
@@ -441,7 +478,7 @@ const agent = new ConversationalAgent({
 Available plugin IDs:
 
 - Standard plugins: `hcs-10`, `hcs-2`, `inscribe`
-- Core Hedera plugins: `hts-token`, `account`, `file-service`, `consensus-service`, `smart-contract`, `network`
+- Core Hedera plugins: `hts-token`, `account`, `file-service`, `consensus-service`, `smart-contract`, `network`, `hbar`
 
 ### Legacy Plugin Usage (hedera-agent-kit 2.0.3 only)
 
@@ -490,7 +527,7 @@ If you've created a plugin that extends the Conversational Agent's capabilities,
 
 2. **Create Your Plugin**
    - Place your plugin in `src/plugins/community/[your-plugin-name]/`
-   - Follow the plugin structure outlined in the [Plugin Development Guide](docs/PLUGIN_DEVELOPMENT.md)
+   - Follow the plugin structure outlined in the [Conversational Agent documentation](https://hashgraphonline.com/docs/libraries/conversational-agent/)
    - Include comprehensive tests in `src/plugins/community/[your-plugin-name]/__tests__/`
    - Add documentation in `src/plugins/community/[your-plugin-name]/README.md`
 
@@ -545,7 +582,7 @@ src/plugins/community/your-plugin/
 
 ### Getting Help
 
-- Join our [Discord community](https://discord.gg/hashgraphonline) for discussions
+- Join our [Telegram community](https://t.me/hashinals) for discussions
 - Check existing issues and PRs before starting work
 - Ask questions in the #development channel
 - Review the [HCS Standards](https://hashgraphonline.com/docs/standards) for protocol details

package/dist/cjs/config/system-message.d.ts

@@ -1 +1 @@
-export declare const getSystemMessage: (accountId: string) => string;
+export declare const getSystemMessage: (accountId?: string) => string;

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

@@ -244,5 +244,21 @@ export declare class ConversationalAgent {
      * Clean up resources
      */
     cleanup(): Promise<void>;
+    /**
+     * Switch operational mode
+     */
+    switchMode(mode?: AgentOperationalMode): void;
+    /**
+     * Get usage statistics
+     */
+    getUsageStats(): unknown;
+    /**
+     * Clear usage statistics
+     */
+    clearUsageStats(): void;
+    /**
+     * Shutdown the agent
+     */
+    shutdown(): Promise<void>;
     private extractResponseText;
 }

package/dist/cjs/core/tool-registry.d.ts

@@ -45,6 +45,12 @@ export interface ToolRegistryEntry {
     metadata: ToolMetadata;
     wrapper?: FormValidatingToolWrapper<z.ZodObject<z.ZodRawShape>> | undefined;
     originalTool: StructuredTool;
+    options?: {
+        priority?: ToolCapabilities['priority'];
+        capability?: string;
+        enabled?: boolean;
+        namespace?: string;
+    };
 }
 /**
  * Options for tool registration
@@ -102,6 +108,26 @@ export declare class ToolRegistry {
      * Get all tool names
      */
     getToolNames(): string[];
+    /**
+     * Get tools by priority
+     */
+    getToolsByPriority(priority: ToolCapabilities['priority']): ToolRegistryEntry[];
+    /**
+     * Get enabled tools (all tools are considered enabled by default)
+     */
+    getEnabledTools(): ToolRegistryEntry[];
+    /**
+     * Get tools by namespace/category
+     */
+    getToolsByNamespace(namespace?: string): ToolRegistryEntry[];
+    /**
+     * Check if registry has capability
+     */
+    hasCapability(capability: keyof ToolCapabilities): boolean;
+    /**
+     * Update tool options (metadata)
+     */
+    updateToolOptions(name: string, options: Partial<ToolMetadata>): boolean;
     /**
      * Check if a tool is registered
      */