@hashgraphonline/conversational-agent 0.0.1 → 0.1.0

package/dist/types/mcp/types.d.ts

@@ -0,0 +1,27 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+export interface MCPServerConfig {
+    name: string;
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+    transport?: 'stdio' | 'http' | 'websocket';
+    autoConnect?: boolean;
+    /**
+     * Additional context to help the AI understand when to use this server's tools
+     */
+    additionalContext?: string;
+    /**
+     * Tool-specific descriptions to enhance or override default tool descriptions
+     */
+    toolDescriptions?: Record<string, string>;
+}
+export interface MCPToolInfo extends Tool {
+    serverName: string;
+}
+export interface MCPConnectionStatus {
+    serverName: string;
+    connected: boolean;
+    error?: string;
+    tools: MCPToolInfo[];
+}

package/dist/types/plugins/hbar-transfer/AccountBuilder.d.ts

@@ -0,0 +1,13 @@
+import { HederaAgentKit, BaseServiceBuilder } from 'hedera-agent-kit';
+import { HbarTransferParams } from './types';
+
+/**
+ * Custom AccountBuilder that properly handles HBAR decimal conversion
+ */
+export declare class AccountBuilder extends BaseServiceBuilder {
+    constructor(hederaKit: HederaAgentKit);
+    /**
+     * Transfers HBAR between accounts with proper decimal handling
+     */
+    transferHbar(params: HbarTransferParams, isUserInitiated?: boolean): this;
+}

package/dist/types/plugins/hbar-transfer/HbarTransferPlugin.d.ts

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

package/dist/types/plugins/hbar-transfer/TransferHbarTool.d.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { BaseHederaTransactionTool, BaseServiceBuilder } from 'hedera-agent-kit';
+
+declare const TransferHbarZodSchemaCore: z.ZodObject<{
+    transfers: 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, {
+    transfers: {
+        accountId: string;
+        amount: string | number;
+    }[];
+    memo?: string | undefined;
+}, {
+    transfers: {
+        accountId: string;
+        amount: string | number;
+    }[];
+    memo?: string | undefined;
+}>;
+export declare class TransferHbarTool extends BaseHederaTransactionTool<typeof TransferHbarZodSchemaCore> {
+    name: string;
+    description: string;
+    specificInputSchema: z.ZodObject<{
+        transfers: 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, {
+        transfers: {
+            accountId: string;
+            amount: string | number;
+        }[];
+        memo?: string | undefined;
+    }, {
+        transfers: {
+            accountId: string;
+            amount: string | number;
+        }[];
+        memo?: string | undefined;
+    }>;
+    namespace: string;
+    protected getServiceBuilder(): BaseServiceBuilder;
+    protected callBuilderMethod(builder: BaseServiceBuilder, specificArgs: z.infer<typeof TransferHbarZodSchemaCore>): Promise<void>;
+}
+export {};

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

@@ -0,0 +1 @@
+export { HbarTransferPlugin } from './HbarTransferPlugin';

package/dist/types/plugins/hbar-transfer/types.d.ts

@@ -0,0 +1,10 @@
+import { AccountId, Hbar } from '@hashgraph/sdk';
+
+export interface HbarTransferInput {
+    accountId: string | AccountId;
+    amount: string | number | Hbar;
+}
+export interface HbarTransferParams {
+    transfers: HbarTransferInput[];
+    memo?: string;
+}

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

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

package/dist/types/providers.d.ts

@@ -0,0 +1,48 @@
+import { BaseLanguageModelCallOptions } from '@langchain/core/language_models/base';
+import { BaseChatModel } from '@langchain/core/language_models/chat_models';
+
+/**
+ * Framework-agnostic AI provider interface for multi-framework support
+ */
+export interface AIProvider {
+    /**
+     * Generate a response from the AI model
+     */
+    generate(prompt: string, options?: BaseLanguageModelCallOptions): Promise<string>;
+    /**
+     * Stream a response from the AI model
+     */
+    stream?(prompt: string, options?: BaseLanguageModelCallOptions): AsyncGenerator<string>;
+    /**
+     * Get the underlying model if available
+     */
+    getModel?(): BaseChatModel | unknown;
+}
+/**
+ * LangChain AI provider implementation
+ */
+export declare class LangChainProvider implements AIProvider {
+    private model;
+    constructor(model: BaseChatModel);
+    generate(prompt: string, options?: BaseLanguageModelCallOptions): Promise<string>;
+    stream(prompt: string, options?: BaseLanguageModelCallOptions): AsyncGenerator<string>;
+    getModel(): BaseChatModel;
+}
+/**
+ * Vercel AI SDK provider interface (forward-thinking)
+ */
+export interface VercelAIProvider extends AIProvider {
+    /**
+     * Use Vercel AI SDK's streamText function
+     */
+    streamText?(prompt: string, options?: unknown): Promise<unknown>;
+}
+/**
+ * BAML provider interface (forward-thinking)
+ */
+export interface BAMLProvider extends AIProvider {
+    /**
+     * Execute a BAML function
+     */
+    executeFunction?(name: string, args: Record<string, unknown>): Promise<unknown>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hashgraphonline/conversational-agent",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "type": "module",
   "main": "./dist/cjs/index.cjs",
   "module": "./dist/esm/index.js",
@@ -23,6 +23,29 @@
     "LICENSE",
     "README.md"
   ],
+  "scripts": {
+    "test": "vitest run",
+    "test:integration": "vitest run tests/integration",
+    "clean": "rimraf dist",
+    "build:es": "BUILD_FORMAT=es vite build",
+    "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",
+    "prepublishOnly": "pnpm run build",
+    "release": "pnpm publish --access public",
+    "release:canary": "pnpm run prepublishOnly && pnpm publish --tag canary --access public",
+    "version:canary": "pnpm version prerelease --preid canary --no-git-tag-version",
+    "publish:canary": "pnpm run version:canary && pnpm run release:canary",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc --noEmit",
+    "cli:build": "pnpm run 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",
+    "example:mcp-multi": "tsx examples/mcp-multi-server-demo.ts",
+    "postinstall": "cd cli && pnpm install --silent 2>/dev/null || true"
+  },
   "keywords": [
     "hedera",
     "hashgraph",
@@ -47,8 +70,8 @@
     "@typescript-eslint/eslint-plugin": "^8.38.0",
     "@typescript-eslint/parser": "^8.38.0",
     "dotenv": "^17.2.1",
-    "eslint": "^8.57.1",
-    "eslint-config-next": "14.1.0",
+    "eslint": "^9.3",
+    "eslint-config-next": "15.4.0",
     "eslint-plugin-sonarjs": "^3.0.4",
     "rimraf": "^6.0.1",
     "rollup-plugin-polyfill-node": "^0.13.0",
@@ -63,11 +86,15 @@
   },
   "dependencies": {
     "@hashgraph/sdk": "^2.69.0",
-    "@hashgraphonline/standards-agent-kit": "^0.2.102",
-    "@hashgraphonline/standards-sdk": "^0.0.155",
+    "@hashgraphonline/standards-agent-kit": "0.2.105",
+    "@hashgraphonline/standards-sdk": "^0.0.156",
     "@langchain/core": "^0.3.66",
+    "@langchain/openai": "^0.6.3",
+    "@modelcontextprotocol/sdk": "^1.17.0",
+    "bignumber.js": "^9.3.1",
     "hedera-agent-kit": "^2.0.3",
-    "zod": "^3.25.76"
+    "langchain": "^0.3.3",
+    "zod": "^3.23.8"
   },
   "repository": {
     "type": "git",
@@ -80,24 +107,5 @@
     "url": "https://github.com/hashgraph-online/conversational-agent/issues"
   },
   "homepage": "https://github.com/hashgraph-online/conversational-agent#readme",
-  "scripts": {
-    "test": "vitest run",
-    "test:integration": "vitest run tests/integration",
-    "clean": "rimraf dist",
-    "build:es": "BUILD_FORMAT=es vite build",
-    "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",
-    "release": "pnpm publish --access public",
-    "release:canary": "pnpm run prepublishOnly && pnpm publish --tag canary --access public",
-    "version:canary": "pnpm version prerelease --preid canary --no-git-tag-version",
-    "publish:canary": "pnpm run version:canary && pnpm run release:canary",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "typecheck": "tsc --noEmit",
-    "cli:build": "pnpm run build && cd cli && pnpm install && pnpm build",
-    "cli": "tsx cli/scripts/run-cli.ts",
-    "cli:dev": "cd cli && pnpm dev",
-    "postinstall": "cd cli && pnpm install --silent 2>/dev/null || true"
-  }
-}
+  "packageManager": "pnpm@10.11.1+sha512.e519b9f7639869dc8d5c3c5dfef73b3f091094b0a006d7317353c72b124e80e1afd429732e28705ad6bfa1ee879c1fce46c128ccebd3192101f43dd67c667912"
+}

package/src/agent-factory.ts

@@ -0,0 +1,21 @@
+import { BaseAgent, type HederaAgentConfiguration } from './base-agent';
+import { LangChainAgent } from './langchain-agent';
+
+export function createAgent(
+  config: HederaAgentConfiguration & {
+    framework?: 'langchain' | 'vercel' | 'baml';
+  }
+): BaseAgent {
+  const framework = config.framework || 'langchain';
+
+  switch (framework) {
+    case 'langchain':
+      return new LangChainAgent(config);
+    case 'vercel':
+      throw new Error('Vercel AI SDK support coming soon');
+    case 'baml':
+      throw new Error('BAML support coming soon');
+    default:
+      throw new Error(`Unknown framework: ${framework}`);
+  }
+}

package/src/base-agent.ts

@@ -0,0 +1,222 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type { StructuredTool } from '@langchain/core/tools';
+import type { TransactionReceipt } from '@hashgraph/sdk';
+import {
+  HederaAgentKit,
+  ServerSigner,
+  TokenUsageCallbackHandler,
+  TokenUsage,
+  BasePlugin,
+} from 'hedera-agent-kit';
+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';
+
+export interface ToolFilterConfig {
+  namespaceWhitelist?: string[];
+  toolBlacklist?: string[];
+  toolPredicate?: (tool: StructuredTool) => boolean;
+}
+
+export type ExecutionMode = 'direct' | 'bytes';
+export type OperationalMode = 'autonomous' | 'returnBytes';
+
+export interface HederaAgentConfiguration {
+  signer: ServerSigner;
+  execution?: {
+    mode?: ExecutionMode;
+    operationalMode?: OperationalMode;
+    userAccountId?: string;
+    scheduleUserTransactions?: boolean;
+    scheduleUserTransactionsInBytesMode?: boolean;
+  };
+  ai?: {
+    provider?: AIProvider;
+    llm?: unknown;
+    apiKey?: string;
+    modelName?: string;
+    temperature?: number;
+  };
+  filtering?: ToolFilterConfig;
+  messaging?: {
+    systemPreamble?: string;
+    systemPostamble?: string;
+    conciseMode?: boolean;
+  };
+  extensions?: {
+    plugins?: BasePlugin[];
+    mirrorConfig?: Record<string, unknown>;
+    modelCapability?: string;
+  };
+  mcp?: {
+    servers?: MCPServerConfig[];
+    autoConnect?: boolean;
+  };
+  debug?: {
+    verbose?: boolean;
+    silent?: boolean;
+  };
+}
+
+export interface ConversationContext {
+  messages: BaseMessage[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface ChatResponse {
+  output: string;
+  message?: string;
+  transactionBytes?: string;
+  receipt?: TransactionReceipt | object;
+  scheduleId?: string;
+  transactionId?: string;
+  notes?: string[];
+  error?: string;
+  intermediateSteps?: unknown;
+  rawToolOutput?: unknown;
+  tokenUsage?: TokenUsage;
+  cost?: CostCalculation;
+  metadata?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface UsageStats extends TokenUsage {
+  cost: CostCalculation;
+}
+
+export abstract class BaseAgent {
+  protected logger: Logger;
+  protected agentKit: HederaAgentKit | undefined;
+  protected tools: StructuredTool[] = [];
+  protected initialized = false;
+  protected tokenTracker: TokenUsageCallbackHandler | undefined;
+
+  constructor(protected config: HederaAgentConfiguration) {
+    this.logger = new Logger({
+      module: 'BaseAgent',
+      silent: config.debug?.silent || false,
+    });
+  }
+
+  abstract boot(): Promise<void>;
+  abstract chat(
+    message: string,
+    context?: ConversationContext
+  ): Promise<ChatResponse>;
+  abstract shutdown(): Promise<void>;
+  abstract switchMode(mode: OperationalMode): void;
+  abstract getUsageStats(): UsageStats;
+  abstract getUsageLog(): UsageStats[];
+  abstract clearUsageStats(): void;
+
+  getCore(): HederaAgentKit | undefined {
+    return this.agentKit;
+  }
+
+  protected filterTools(
+    tools: StructuredTool[]
+  ): StructuredTool[] {
+    let filtered = [...tools];
+    const filter = this.config.filtering;
+    if (!filter) return filtered;
+
+    if (filter.namespaceWhitelist?.length) {
+      filtered = filtered.filter((tool) => {
+        const namespace = (tool as StructuredTool & { namespace?: string })
+          .namespace;
+        return !namespace || filter.namespaceWhitelist!.includes(namespace);
+      });
+    }
+
+    if (filter.toolBlacklist?.length) {
+      filtered = filtered.filter(
+        (tool) => !filter.toolBlacklist!.includes(tool.name)
+      );
+    }
+
+    if (filter.toolPredicate) {
+      filtered = filtered.filter(filter.toolPredicate);
+    }
+
+    this.logger.debug(`Filtered tools: ${tools.length} → ${filtered.length}`);
+    return filtered;
+  }
+
+  protected buildSystemPrompt(): string {
+    const parts: string[] = [];
+    const operatorId = this.config.signer.getAccountId().toString();
+    const userAccId = this.config.execution?.userAccountId;
+
+    if (this.config.messaging?.systemPreamble) {
+      parts.push(this.config.messaging.systemPreamble);
+    }
+
+    parts.push(
+      `You are a helpful Hedera assistant. Your primary operator account is ${operatorId}. ` +
+        `You have tools to interact with the Hedera network. ` +
+        `When using any tool, provide all necessary parameters as defined by that tool's schema and description.`
+    );
+
+    if (userAccId) {
+      parts.push(
+        `The user you are assisting has a personal Hedera account ID: ${userAccId}. ` +
+          `IMPORTANT: When the user says things like "I want to send HBAR" or "transfer my tokens", you MUST use ${userAccId} as the sender/from account. ` +
+          `For example, if user says "I want to send 2 HBAR to 0.0.800", you must set up a transfer where ${userAccId} sends the HBAR, not your operator account.`
+      );
+    }
+
+    const operationalMode =
+      this.config.execution?.operationalMode || 'returnBytes';
+    if (operationalMode === 'autonomous') {
+      parts.push(
+        `\nOPERATIONAL MODE: 'autonomous'. Your goal is to execute transactions directly using your tools. ` +
+          `Your account ${operatorId} will be the payer for these transactions. ` +
+          `Even if the user's account (${
+            userAccId || 'a specified account'
+          }) is the actor in the transaction body (e.g., sender of HBAR), ` +
+          `you (the agent with operator ${operatorId}) are still executing and paying. For HBAR transfers, ensure the amounts in the 'transfers' array sum to zero (as per tool schema), balancing with your operator account if necessary.`
+      );
+    } else {
+      if (
+        this.config.execution?.scheduleUserTransactionsInBytesMode &&
+        userAccId
+      ) {
+        parts.push(
+          `\nOPERATIONAL MODE: 'returnBytes' with scheduled transactions for user actions. ` +
+            `When a user asks for a transaction to be prepared (e.g., creating a token, topic, transferring assets for them to sign, etc), ` +
+            `you MUST default to creating a Scheduled Transaction using the appropriate tool with the metaOption 'schedule: true'. ` +
+            `The user (with account ID ${userAccId}) will be the one to ultimately pay for and (if needed) sign the inner transaction. ` +
+            `Your operator account (${operatorId}) will pay for creating the schedule entity itself. ` +
+            `You MUST return the ScheduleId and details of the scheduled operation in a structured JSON format with these fields: success, op, schedule_id, description, payer_account_id_scheduled_tx, and scheduled_transaction_details.`
+        );
+      } else {
+        parts.push(
+          `\nOPERATIONAL MODE: 'returnBytes'. Your goal is to provide transaction bytes directly. ` +
+            `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 ${
+              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.`
+        );
+      }
+    }
+
+    if (this.config.messaging?.conciseMode !== false) {
+      parts.push(
+        '\nAlways be concise. If the tool provides a JSON string as its primary output (especially in returnBytes mode), make your accompanying text brief. If the tool does not provide JSON output or an error occurs, your narrative becomes primary; if notes were generated by the tool in such cases, append them to your textual response.'
+      );
+    }
+
+    if (this.config.messaging?.systemPostamble) {
+      parts.push(this.config.messaging.systemPostamble);
+    }
+
+    return parts.join('\n');
+  }
+
+  isReady(): boolean {
+    return this.initialized;
+  }
+}
+
+export type { AIProvider, VercelAIProvider, BAMLProvider };

package/src/config/system-message.ts

@@ -1,4 +1,4 @@
-export const SYSTEM_MESSAGE = `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, and content inscription.
 
 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