@hashgraphonline/conversational-agent 0.1.208 → 0.1.210

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (117) hide show
  1. package/bin/conversational-agent-cli.js +30 -0
  2. package/cli/readme.md +181 -0
  3. package/dist/cjs/base-agent.d.ts +3 -1
  4. package/dist/cjs/conversational-agent.d.ts +64 -13
  5. package/dist/cjs/index.cjs +1 -1
  6. package/dist/cjs/index.cjs.map +1 -1
  7. package/dist/cjs/index.d.ts +6 -3
  8. package/dist/cjs/langchain-agent.d.ts +11 -0
  9. package/dist/cjs/memory/SmartMemoryManager.d.ts +65 -22
  10. package/dist/cjs/memory/TokenCounter.d.ts +1 -1
  11. package/dist/cjs/memory/index.d.ts +1 -1
  12. package/dist/cjs/plugins/hbar/AirdropToolWrapper.d.ts +43 -0
  13. package/dist/{types/plugins/hbar-transfer/HbarTransferPlugin.d.ts → cjs/plugins/hbar/HbarPlugin.d.ts} +2 -1
  14. package/dist/{types/plugins/hbar-transfer → cjs/plugins/hbar}/TransferHbarTool.d.ts +1 -1
  15. package/dist/cjs/plugins/hbar/index.d.ts +3 -0
  16. package/dist/cjs/plugins/index.d.ts +2 -1
  17. package/dist/cjs/services/EntityResolver.d.ts +26 -0
  18. package/dist/cjs/tools/EntityResolverTool.d.ts +104 -0
  19. package/dist/cjs/types/inscription.d.ts +37 -0
  20. package/dist/esm/index.js +16 -2
  21. package/dist/esm/index.js.map +1 -1
  22. package/dist/esm/index12.js +121 -46
  23. package/dist/esm/index12.js.map +1 -1
  24. package/dist/esm/index13.js +177 -13
  25. package/dist/esm/index13.js.map +1 -1
  26. package/dist/esm/index14.js +599 -100
  27. package/dist/esm/index14.js.map +1 -1
  28. package/dist/esm/index15.js +426 -9
  29. package/dist/esm/index15.js.map +1 -1
  30. package/dist/esm/index16.js +119 -160
  31. package/dist/esm/index16.js.map +1 -1
  32. package/dist/esm/index17.js +140 -150
  33. package/dist/esm/index17.js.map +1 -1
  34. package/dist/esm/index18.js +44 -231
  35. package/dist/esm/index18.js.map +1 -1
  36. package/dist/esm/index19.js +86 -643
  37. package/dist/esm/index19.js.map +1 -1
  38. package/dist/esm/index2.js +22 -13
  39. package/dist/esm/index2.js.map +1 -1
  40. package/dist/esm/index20.js +20 -230
  41. package/dist/esm/index20.js.map +1 -1
  42. package/dist/esm/index21.js +9 -179
  43. package/dist/esm/index21.js.map +1 -1
  44. package/dist/esm/index22.js +140 -89
  45. package/dist/esm/index22.js.map +1 -1
  46. package/dist/esm/index23.js +141 -81
  47. package/dist/esm/index23.js.map +1 -1
  48. package/dist/esm/index24.js +4 -4
  49. package/dist/esm/index24.js.map +1 -1
  50. package/dist/esm/index25.js +0 -8
  51. package/dist/esm/index25.js.map +1 -1
  52. package/dist/esm/index26.js +95 -0
  53. package/dist/esm/index26.js.map +1 -0
  54. package/dist/esm/index27.js +242 -0
  55. package/dist/esm/index27.js.map +1 -0
  56. package/dist/esm/index5.js +32 -19
  57. package/dist/esm/index5.js.map +1 -1
  58. package/dist/esm/index6.js +276 -37
  59. package/dist/esm/index6.js.map +1 -1
  60. package/dist/esm/index7.js +2 -2
  61. package/dist/esm/index7.js.map +1 -1
  62. package/dist/esm/index8.js +124 -18
  63. package/dist/esm/index8.js.map +1 -1
  64. package/dist/types/base-agent.d.ts +3 -1
  65. package/dist/types/conversational-agent.d.ts +64 -13
  66. package/dist/types/index.d.ts +6 -3
  67. package/dist/types/langchain-agent.d.ts +11 -0
  68. package/dist/types/memory/SmartMemoryManager.d.ts +65 -22
  69. package/dist/types/memory/TokenCounter.d.ts +1 -1
  70. package/dist/types/memory/index.d.ts +1 -1
  71. package/dist/types/plugins/hbar/AirdropToolWrapper.d.ts +43 -0
  72. package/dist/{cjs/plugins/hbar-transfer/HbarTransferPlugin.d.ts → types/plugins/hbar/HbarPlugin.d.ts} +2 -1
  73. package/dist/{cjs/plugins/hbar-transfer → types/plugins/hbar}/TransferHbarTool.d.ts +1 -1
  74. package/dist/types/plugins/hbar/index.d.ts +3 -0
  75. package/dist/types/plugins/index.d.ts +2 -1
  76. package/dist/types/services/EntityResolver.d.ts +26 -0
  77. package/dist/types/tools/EntityResolverTool.d.ts +104 -0
  78. package/dist/types/types/inscription.d.ts +37 -0
  79. package/package.json +13 -4
  80. package/src/base-agent.ts +14 -9
  81. package/src/config/system-message.ts +11 -2
  82. package/src/context/ReferenceContextManager.ts +10 -5
  83. package/src/context/ReferenceResponseProcessor.ts +3 -4
  84. package/src/conversational-agent.ts +372 -57
  85. package/src/index.ts +19 -3
  86. package/src/langchain/ContentAwareAgentExecutor.ts +0 -1
  87. package/src/langchain-agent.ts +168 -33
  88. package/src/mcp/ContentProcessor.ts +11 -3
  89. package/src/mcp/adapters/langchain.ts +1 -10
  90. package/src/memory/ContentStorage.ts +2 -55
  91. package/src/memory/MemoryWindow.ts +4 -17
  92. package/src/memory/ReferenceIdGenerator.ts +4 -8
  93. package/src/memory/SmartMemoryManager.ts +375 -47
  94. package/src/memory/TokenCounter.ts +15 -22
  95. package/src/memory/index.ts +1 -1
  96. package/src/plugins/hbar/AirdropToolWrapper.ts +157 -0
  97. package/src/plugins/hbar/HbarPlugin.ts +86 -0
  98. package/src/plugins/{hbar-transfer → hbar}/TransferHbarTool.ts +3 -3
  99. package/src/plugins/hbar/index.ts +3 -0
  100. package/src/plugins/hcs-10/HCS10Plugin.ts +44 -14
  101. package/src/plugins/index.ts +2 -1
  102. package/src/services/ContentStoreManager.ts +0 -3
  103. package/src/services/EntityResolver.ts +135 -0
  104. package/src/tools/EntityResolverTool.ts +170 -0
  105. package/src/types/content-reference.ts +8 -8
  106. package/src/types/index.ts +0 -1
  107. package/src/types/inscription.ts +40 -0
  108. package/dist/cjs/plugins/hbar-transfer/index.d.ts +0 -1
  109. package/dist/types/plugins/hbar-transfer/index.d.ts +0 -1
  110. package/src/plugins/hbar-transfer/HbarTransferPlugin.ts +0 -66
  111. package/src/plugins/hbar-transfer/index.ts +0 -1
  112. /package/dist/cjs/plugins/{hbar-transfer → hbar}/AccountBuilder.d.ts +0 -0
  113. /package/dist/cjs/plugins/{hbar-transfer → hbar}/types.d.ts +0 -0
  114. /package/dist/types/plugins/{hbar-transfer → hbar}/AccountBuilder.d.ts +0 -0
  115. /package/dist/types/plugins/{hbar-transfer → hbar}/types.d.ts +0 -0
  116. /package/src/plugins/{hbar-transfer → hbar}/AccountBuilder.ts +0 -0
  117. /package/src/plugins/{hbar-transfer → hbar}/types.ts +0 -0
@@ -1,5 +1,32 @@
1
1
  import { BaseMessage } from '@langchain/core/messages';
2
+ import { ContentStorage } from './ContentStorage';
2
3
 
4
+ /**
5
+ * Entity association for storing blockchain entity contexts
6
+ */
7
+ export interface EntityAssociation {
8
+ /** The blockchain entity ID (e.g., tokenId, accountId, topicId) */
9
+ entityId: string;
10
+ /** User-provided or derived friendly name */
11
+ entityName: string;
12
+ /** Type of entity (token, account, topic, schedule, etc.) */
13
+ entityType: string;
14
+ /** When the entity was created/associated */
15
+ createdAt: Date;
16
+ /** Transaction ID that created this entity */
17
+ transactionId?: string;
18
+ }
19
+ /**
20
+ * Options for resolving entity references
21
+ */
22
+ export interface EntityResolutionOptions {
23
+ /** Filter by specific entity type */
24
+ entityType?: string;
25
+ /** Maximum number of results to return */
26
+ limit?: number;
27
+ /** Whether to use fuzzy matching for natural language queries */
28
+ fuzzyMatch?: boolean;
29
+ }
3
30
  /**
4
31
  * Configuration for SmartMemoryManager
5
32
  */
@@ -42,16 +69,22 @@ export interface MemoryStats {
42
69
  usagePercentage: number;
43
70
  }
44
71
  /**
72
+ * TODO: investigate using chroma / rag for long term memory
45
73
  * Smart memory manager that combines active memory window with long-term storage
46
74
  * Provides context-aware memory management with automatic pruning and searchable history
47
75
  */
48
76
  export declare class SmartMemoryManager {
49
77
  private memoryWindow;
50
- private contentStorage;
78
+ private _contentStorage;
51
79
  private tokenCounter;
52
80
  private config;
53
81
  private static readonly DEFAULT_CONFIG;
54
82
  constructor(config?: SmartMemoryConfig);
83
+ /**
84
+ * Get the content storage instance for file/content reference operations
85
+ * @returns ContentStorage instance
86
+ */
87
+ get contentStorage(): ContentStorage;
55
88
  /**
56
89
  * Add a message to the active memory window
57
90
  * Automatically handles pruning and storage of displaced messages
@@ -106,14 +139,14 @@ export declare class SmartMemoryManager {
106
139
  * Get statistics about the content storage
107
140
  * @returns Storage usage statistics
108
141
  */
109
- getStorageStats(): import('./ContentStorage').StorageStats;
142
+ getStorageStats(): ReturnType<ContentStorage['getStorageStats']>;
110
143
  /**
111
144
  * Get combined statistics for both active memory and storage
112
145
  * @returns Combined memory and storage statistics
113
146
  */
114
147
  getOverallStats(): {
115
148
  activeMemory: MemoryStats;
116
- storage: import('./ContentStorage').StorageStats;
149
+ storage: ReturnType<ContentStorage['getStorageStats']>;
117
150
  totalMessagesManaged: number;
118
151
  activeMemoryUtilization: number;
119
152
  storageUtilization: number;
@@ -154,19 +187,14 @@ export declare class SmartMemoryManager {
154
187
  */
155
188
  exportState(): {
156
189
  config: Required<SmartMemoryConfig>;
157
- activeMessages: {
158
- content: import('@langchain/core/messages').MessageContent;
159
- type: import('@langchain/core/messages').MessageType;
160
- }[];
190
+ activeMessages: Array<{
191
+ content: unknown;
192
+ type: string;
193
+ }>;
161
194
  systemPrompt: string;
162
195
  memoryStats: MemoryStats;
163
- storageStats: import('./ContentStorage').StorageStats;
164
- storedMessages: {
165
- content: import('@langchain/core/messages').MessageContent;
166
- type: import('@langchain/core/messages').MessageType;
167
- storedAt: string;
168
- id: string;
169
- }[];
196
+ storageStats: ReturnType<ContentStorage['getStorageStats']>;
197
+ storedMessages: ReturnType<ContentStorage['exportMessages']>;
170
198
  };
171
199
  /**
172
200
  * Get a summary of conversation context for external use
@@ -180,20 +208,35 @@ export declare class SmartMemoryManager {
180
208
  recentMessages: BaseMessage[];
181
209
  memoryUtilization: number;
182
210
  hasStoredHistory: boolean;
183
- } | {
184
- recentStoredMessages: BaseMessage[];
185
- storageStats: import('./ContentStorage').StorageStats;
186
- activeMessageCount: number;
187
- systemPrompt: string;
188
- recentMessages: BaseMessage[];
189
- memoryUtilization: number;
190
- hasStoredHistory: boolean;
211
+ recentStoredMessages?: BaseMessage[];
212
+ storageStats?: ReturnType<ContentStorage['getStorageStats']>;
191
213
  };
192
214
  /**
193
215
  * Perform maintenance operations
194
216
  * Optimizes storage and cleans up resources
195
217
  */
196
218
  performMaintenance(): void;
219
+ /**
220
+ * Store an entity association for later resolution
221
+ * @param entityId - The blockchain entity ID
222
+ * @param entityName - User-provided or derived friendly name
223
+ * @param entityType - Type of entity (token, account, topic, etc.)
224
+ * @param transactionId - Optional transaction ID that created this entity
225
+ */
226
+ storeEntityAssociation(entityId: string, entityName: string, entityType: string, transactionId?: string): void;
227
+ /**
228
+ * Resolve entity references from natural language queries
229
+ * @param query - Search query (entity name or natural language reference)
230
+ * @param options - Resolution options for filtering and fuzzy matching
231
+ * @returns Array of matching entity associations
232
+ */
233
+ resolveEntityReference(query: string, options?: EntityResolutionOptions): EntityAssociation[];
234
+ /**
235
+ * Get all entity associations, optionally filtered by type
236
+ * @param entityType - Optional filter by entity type
237
+ * @returns Array of entity associations
238
+ */
239
+ getEntityAssociations(entityType?: string): EntityAssociation[];
197
240
  /**
198
241
  * Clean up resources and dispose of components
199
242
  */
@@ -10,7 +10,7 @@ export declare class TokenCounter {
10
10
  private modelName;
11
11
  private static readonly MESSAGE_OVERHEAD;
12
12
  private static readonly ROLE_OVERHEAD;
13
- constructor(modelName?: TiktokenModel);
13
+ constructor(modelName?: string | TiktokenModel);
14
14
  /**
15
15
  * Count tokens in raw text content
16
16
  * @param text - The text to count tokens for
@@ -2,6 +2,6 @@ export { TokenCounter } from './TokenCounter';
2
2
  export { MemoryWindow } from './MemoryWindow';
3
3
  export { ContentStorage } from './ContentStorage';
4
4
  export { SmartMemoryManager } from './SmartMemoryManager';
5
- export type { SmartMemoryConfig, SearchOptions, MemoryStats } from './SmartMemoryManager';
5
+ export type { SmartMemoryConfig, SearchOptions, MemoryStats, EntityAssociation, EntityResolutionOptions } from './SmartMemoryManager';
6
6
  export type { AddMessageResult } from './MemoryWindow';
7
7
  export type { StorageStats } from './ContentStorage';
@@ -0,0 +1,43 @@
1
+ import { StructuredTool } from '@langchain/core/tools';
2
+ import { z } from 'zod';
3
+
4
+ export declare class AirdropToolWrapper extends StructuredTool {
5
+ name: string;
6
+ description: string;
7
+ schema: z.ZodObject<{
8
+ tokenId: z.ZodString;
9
+ recipients: z.ZodArray<z.ZodObject<{
10
+ accountId: z.ZodString;
11
+ amount: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
12
+ }, "strip", z.ZodTypeAny, {
13
+ accountId: string;
14
+ amount: string | number;
15
+ }, {
16
+ accountId: string;
17
+ amount: string | number;
18
+ }>, "many">;
19
+ memo: z.ZodOptional<z.ZodString>;
20
+ }, "strip", z.ZodTypeAny, {
21
+ tokenId: string;
22
+ recipients: {
23
+ accountId: string;
24
+ amount: string | number;
25
+ }[];
26
+ memo?: string | undefined;
27
+ }, {
28
+ tokenId: string;
29
+ recipients: {
30
+ accountId: string;
31
+ amount: string | number;
32
+ }[];
33
+ memo?: string | undefined;
34
+ }>;
35
+ private originalTool;
36
+ private agentKit;
37
+ private logger;
38
+ constructor(originalTool: StructuredTool, agentKit: unknown);
39
+ _call(input: z.infer<typeof this.schema>): Promise<string>;
40
+ private convertToSmallestUnits;
41
+ private getTokenInfo;
42
+ private queryTokenInfo;
43
+ }
@@ -1,6 +1,6 @@
1
1
  import { GenericPluginContext, HederaTool, BasePlugin } from 'hedera-agent-kit';
2
2
 
3
- export declare class HbarTransferPlugin extends BasePlugin {
3
+ export declare class HbarPlugin extends BasePlugin {
4
4
  id: string;
5
5
  name: string;
6
6
  description: string;
@@ -8,6 +8,7 @@ export declare class HbarTransferPlugin extends BasePlugin {
8
8
  author: string;
9
9
  namespace: string;
10
10
  private tools;
11
+ private originalAirdropTool;
11
12
  initialize(context: GenericPluginContext): Promise<void>;
12
13
  private initializeTools;
13
14
  getTools(): HederaTool[];
@@ -29,7 +29,7 @@ declare const TransferHbarZodSchemaCore: z.ZodObject<{
29
29
  /**
30
30
  * A Hedera transaction tool for transferring HBAR between accounts.
31
31
  * Supports single and multi-party transfers with automatic balance validation.
32
- * Extends BaseHederaTransactionTool to handle HBAR transfer transactions on the Hedera network.
32
+ * Extends BaseHederaTransactionTool to handle HBAR transfer transactions on the Hedera Hashgraph.
33
33
  */
34
34
  export declare class TransferHbarTool extends BaseHederaTransactionTool<typeof TransferHbarZodSchemaCore> {
35
35
  name: string;
@@ -0,0 +1,3 @@
1
+ export * from './TransferHbarTool';
2
+ export * from './AccountBuilder';
3
+ export * from './types';
@@ -1,4 +1,5 @@
1
1
  export { HCS10Plugin } from './hcs-10';
2
2
  export { HCS2Plugin } from './hcs-2';
3
3
  export { InscribePlugin } from './inscribe';
4
- export { HbarTransferPlugin } from './hbar-transfer';
4
+ export { HbarPlugin } from './hbar/HbarPlugin';
5
+ export * from './hbar';
@@ -0,0 +1,26 @@
1
+ import { EntityAssociation } from '../memory/SmartMemoryManager';
2
+
3
+ export interface EntityResolverConfig {
4
+ apiKey: string;
5
+ modelName?: string;
6
+ }
7
+ /**
8
+ * LLM-based entity resolver that replaces brittle regex patterns
9
+ */
10
+ export declare class EntityResolver {
11
+ private llm;
12
+ constructor(config: EntityResolverConfig);
13
+ /**
14
+ * Resolve entity references using LLM instead of regex
15
+ */
16
+ resolveReferences(message: string, entities: EntityAssociation[]): Promise<string>;
17
+ /**
18
+ * Extract entities from agent response using LLM
19
+ */
20
+ extractEntities(response: unknown, userMessage: string): Promise<Array<{
21
+ id: string;
22
+ name: string;
23
+ type: string;
24
+ transactionId?: string;
25
+ }>>;
26
+ }
@@ -0,0 +1,104 @@
1
+ import { StructuredTool } from '@langchain/core/tools';
2
+ import { z } from 'zod';
3
+
4
+ declare const ResolveEntitiesSchema: z.ZodObject<{
5
+ message: z.ZodString;
6
+ entities: z.ZodArray<z.ZodObject<{
7
+ entityId: z.ZodString;
8
+ entityName: z.ZodString;
9
+ entityType: z.ZodString;
10
+ }, "strip", z.ZodTypeAny, {
11
+ entityId: string;
12
+ entityName: string;
13
+ entityType: string;
14
+ }, {
15
+ entityId: string;
16
+ entityName: string;
17
+ entityType: string;
18
+ }>, "many">;
19
+ }, "strip", z.ZodTypeAny, {
20
+ message: string;
21
+ entities: {
22
+ entityId: string;
23
+ entityName: string;
24
+ entityType: string;
25
+ }[];
26
+ }, {
27
+ message: string;
28
+ entities: {
29
+ entityId: string;
30
+ entityName: string;
31
+ entityType: string;
32
+ }[];
33
+ }>;
34
+ declare const ExtractEntitiesSchema: z.ZodObject<{
35
+ response: z.ZodString;
36
+ userMessage: z.ZodString;
37
+ }, "strip", z.ZodTypeAny, {
38
+ response: string;
39
+ userMessage: string;
40
+ }, {
41
+ response: string;
42
+ userMessage: string;
43
+ }>;
44
+ export declare class ResolveEntitiesTool extends StructuredTool {
45
+ name: string;
46
+ description: string;
47
+ schema: z.ZodObject<{
48
+ message: z.ZodString;
49
+ entities: z.ZodArray<z.ZodObject<{
50
+ entityId: z.ZodString;
51
+ entityName: z.ZodString;
52
+ entityType: z.ZodString;
53
+ }, "strip", z.ZodTypeAny, {
54
+ entityId: string;
55
+ entityName: string;
56
+ entityType: string;
57
+ }, {
58
+ entityId: string;
59
+ entityName: string;
60
+ entityType: string;
61
+ }>, "many">;
62
+ }, "strip", z.ZodTypeAny, {
63
+ message: string;
64
+ entities: {
65
+ entityId: string;
66
+ entityName: string;
67
+ entityType: string;
68
+ }[];
69
+ }, {
70
+ message: string;
71
+ entities: {
72
+ entityId: string;
73
+ entityName: string;
74
+ entityType: string;
75
+ }[];
76
+ }>;
77
+ private llm;
78
+ constructor(apiKey: string, modelName?: string);
79
+ _call(input: z.infer<typeof ResolveEntitiesSchema>): Promise<string>;
80
+ private groupEntitiesByType;
81
+ private buildEntityContext;
82
+ }
83
+ export declare class ExtractEntitiesTool extends StructuredTool {
84
+ name: string;
85
+ description: string;
86
+ schema: z.ZodObject<{
87
+ response: z.ZodString;
88
+ userMessage: z.ZodString;
89
+ }, "strip", z.ZodTypeAny, {
90
+ response: string;
91
+ userMessage: string;
92
+ }, {
93
+ response: string;
94
+ userMessage: string;
95
+ }>;
96
+ private llm;
97
+ constructor(apiKey: string, modelName?: string);
98
+ _call(input: z.infer<typeof ExtractEntitiesSchema>): Promise<string>;
99
+ }
100
+ export declare function createEntityTools(apiKey: string, modelName?: string): {
101
+ resolveEntities: ResolveEntitiesTool;
102
+ extractEntities: ExtractEntitiesTool;
103
+ };
104
+ export {};
@@ -0,0 +1,37 @@
1
+ /**
2
+ * Inscription quote response from standards-agent-kit
3
+ */
4
+ export interface InscriptionQuote {
5
+ totalCostHbar: string;
6
+ validUntil: string;
7
+ breakdown: {
8
+ transfers: Array<{
9
+ type: string;
10
+ amount: string;
11
+ description: string;
12
+ }>;
13
+ };
14
+ }
15
+ /**
16
+ * Parameters for inscription tool calls with quote support
17
+ */
18
+ export interface InscriptionToolParams {
19
+ [key: string]: unknown;
20
+ quoteOnly?: boolean;
21
+ }
22
+ /**
23
+ * Result from inscription tool execution
24
+ */
25
+ export interface InscriptionResult {
26
+ success: boolean;
27
+ transactionId?: string;
28
+ message: string;
29
+ quote?: InscriptionQuote;
30
+ }
31
+ /**
32
+ * User confirmation status for inscription
33
+ */
34
+ export interface InscriptionConfirmation {
35
+ confirmed: boolean;
36
+ reason?: string;
37
+ }
package/package.json CHANGED
@@ -1,10 +1,13 @@
1
1
  {
2
2
  "name": "@hashgraphonline/conversational-agent",
3
- "version": "0.1.208",
3
+ "version": "0.1.210",
4
4
  "type": "module",
5
5
  "main": "./dist/cjs/index.cjs",
6
6
  "module": "./dist/esm/index.js",
7
7
  "types": "./dist/types/index.d.ts",
8
+ "bin": {
9
+ "conversational-agent": "./bin/conversational-agent-cli.js"
10
+ },
8
11
  "exports": {
9
12
  ".": {
10
13
  "types": "./dist/types/index.d.ts",
@@ -18,6 +21,8 @@
18
21
  "./package.json": "./package.json"
19
22
  },
20
23
  "files": [
24
+ "bin",
25
+ "cli/dist",
21
26
  "dist",
22
27
  "src",
23
28
  "LICENSE",
@@ -31,6 +36,7 @@
31
36
  "build:cjs": "BUILD_FORMAT=cjs vite build",
32
37
  "build:umd": "BUILD_FORMAT=umd vite build",
33
38
  "build": "pnpm run clean && pnpm run build:es && pnpm run build:cjs",
39
+ "build:all": "pnpm run build && pnpm run cli:build",
34
40
  "prepublishOnly": "pnpm run build",
35
41
  "release": "pnpm publish --access public",
36
42
  "release:canary": "pnpm run prepublishOnly && pnpm publish --tag canary --access public",
@@ -39,7 +45,7 @@
39
45
  "lint": "eslint .",
40
46
  "lint:fix": "eslint . --fix",
41
47
  "typecheck": "tsc --noEmit",
42
- "cli:build": "pnpm run build && cd cli && pnpm install && pnpm build",
48
+ "cli:build": "cd cli && pnpm install && pnpm build",
43
49
  "cli": "tsx cli/scripts/run-cli.ts",
44
50
  "cli:dev": "cd cli && pnpm dev",
45
51
  "example:mcp-filesystem": "tsx examples/mcp-filesystem-demo.ts",
@@ -86,13 +92,16 @@
86
92
  },
87
93
  "dependencies": {
88
94
  "@hashgraph/sdk": "^2.69.0",
89
- "@hashgraphonline/standards-agent-kit": "0.2.121",
90
- "@hashgraphonline/standards-sdk": "0.0.168",
95
+ "@hashgraphonline/standards-agent-kit": "0.2.123",
96
+ "@langchain/anthropic": "^0.3.26",
97
+ "@hashgraphonline/standards-sdk": "^0.0.180",
91
98
  "@langchain/core": "^0.3.66",
92
99
  "@langchain/openai": "^0.6.3",
93
100
  "@modelcontextprotocol/sdk": "^1.17.0",
101
+ "axios": "^1.11.0",
94
102
  "bignumber.js": "^9.3.1",
95
103
  "electron-log": "^5.4.2",
104
+ "ethers": "^6.15.0",
96
105
  "hedera-agent-kit": "^2.0.3",
97
106
  "langchain": "^0.3.3",
98
107
  "tiktoken": "^1.0.21",
package/src/base-agent.ts CHANGED
@@ -11,7 +11,7 @@ import {
11
11
  import type { CostCalculation } from 'hedera-agent-kit';
12
12
  import type { AIProvider, VercelAIProvider, BAMLProvider } from './providers';
13
13
  import { Logger } from '@hashgraphonline/standards-sdk';
14
- import type { MCPServerConfig } from './mcp/types';
14
+ import type { MCPServerConfig, MCPConnectionStatus } from './mcp/types';
15
15
 
16
16
  export interface ToolFilterConfig {
17
17
  namespaceWhitelist?: string[];
@@ -115,16 +115,17 @@ export abstract class BaseAgent {
115
115
  abstract getUsageStats(): UsageStats;
116
116
  abstract getUsageLog(): UsageStats[];
117
117
  abstract clearUsageStats(): void;
118
+ abstract connectMCPServers(): Promise<void>;
119
+ abstract getMCPConnectionStatus(): Map<string, MCPConnectionStatus>;
118
120
 
119
- getCore(): HederaAgentKit | undefined {
121
+ public getCore(): HederaAgentKit | undefined {
120
122
  return this.agentKit;
121
123
  }
122
124
 
123
- protected filterTools(
124
- tools: StructuredTool[]
125
- ): StructuredTool[] {
125
+ protected filterTools(tools: StructuredTool[]): StructuredTool[] {
126
126
  let filtered = [...tools];
127
127
  const filter = this.config.filtering;
128
+
128
129
  if (!filter) return filtered;
129
130
 
130
131
  if (filter.namespaceWhitelist?.length) {
@@ -160,7 +161,7 @@ export abstract class BaseAgent {
160
161
 
161
162
  parts.push(
162
163
  `You are a helpful Hedera assistant. Your primary operator account is ${operatorId}. ` +
163
- `You have tools to interact with the Hedera network. ` +
164
+ `You have tools to interact with the Hedera Hashgraph. ` +
164
165
  `When using any tool, provide all necessary parameters as defined by that tool's schema and description.`
165
166
  );
166
167
 
@@ -198,11 +199,15 @@ export abstract class BaseAgent {
198
199
  );
199
200
  } else {
200
201
  parts.push(
201
- `\nOPERATIONAL MODE: 'returnBytes'. Your goal is to provide transaction bytes directly. ` +
202
+ `\nOPERATIONAL MODE: 'returnBytes'. Your goal is to provide transaction bytes when possible. ` +
202
203
  `When a user asks for a transaction to be prepared (e.g., for them to sign, or for scheduling without the default scheduling flow), ` +
203
- `you MUST call the appropriate tool. If you want raw bytes for the user to sign for their own account ${
204
+ `you MUST call the appropriate tool. ` +
205
+ `IMPORTANT: Only use metaOption 'returnBytes: true' for tools that explicitly support it (like HBAR transfers, token operations). ` +
206
+ `Many tools (inscriptions, HCS-2, HCS-20, etc.) do NOT support returnBytes and will execute directly - this is expected behavior. ` +
207
+ `For tools without returnBytes support, simply call them with their standard parameters. ` +
208
+ `If you need raw bytes for the user to sign for their own account ${
204
209
  userAccId || 'if specified'
205
- }, ensure the tool constructs the transaction body accordingly and use metaOption 'returnBytes: true' if available, or ensure the builder is configured for the user.`
210
+ }, ensure the tool constructs the transaction body accordingly when returnBytes IS supported.`
206
211
  );
207
212
  }
208
213
  }
@@ -1,12 +1,21 @@
1
- export const getSystemMessage = (accountId: string): string => `You are a helpful assistant managing Hashgraph Online HCS-10 connections, messages, HCS-2 registries, and content inscription.
1
+ export const getSystemMessage = (
2
+ accountId: string
3
+ ): string => `You are a helpful assistant managing Hashgraph Online HCS-10 connections, messages, HCS-2 registries, content inscription, and Hedera Hashgraph operations.
2
4
 
3
5
  You have access to tools for:
4
6
  - HCS-10: registering agents, finding registered agents, initiating connections, listing active connections, sending messages over connections, and checking for new messages
5
7
  - HCS-2: creating registries, registering entries, updating entries, deleting entries, migrating registries, and querying registry contents
6
8
  - Inscription: inscribing content from URLs, files, or buffers, creating Hashinal NFTs, and retrieving inscriptions
9
+ - Hedera Token Service (HTS): creating tokens, transferring tokens, airdropping tokens, and managing token operations
7
10
 
8
11
  *** IMPORTANT CONTEXT ***
9
12
  You are currently operating as agent: ${accountId} on the Hashgraph Online network
10
13
  When users ask about "my profile", "my account", "my connections", etc., use this account ID: ${accountId}
11
14
 
12
- Remember the connection numbers when listing connections, as users might refer to them.`
15
+ *** CRITICAL ENTITY HANDLING RULES ***
16
+ - 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
17
+ - Entity IDs look like "0.0.XXXXXX" and are stored in memory after creation
18
+ - NEVER use example or placeholder IDs like "0.0.123456" - always use actual created entity IDs
19
+ - Account ID ${accountId} is NOT a token - tokens and accounts are different entities
20
+
21
+ Remember the connection numbers when listing connections, as users might refer to them.`;
@@ -1,4 +1,4 @@
1
- import type { ContentReference, ReferenceId, ContentReferenceError } from '../types/content-reference';
1
+ import type { ContentReference, ReferenceId } from '../types/content-reference';
2
2
  import type { ContentStorage } from '../memory/ContentStorage';
3
3
  import { Logger } from '@hashgraphonline/standards-sdk';
4
4
 
@@ -169,7 +169,7 @@ export class ReferenceContextManager {
169
169
  let valid = 0;
170
170
  let invalid = 0;
171
171
 
172
- for (const [referenceId, context] of this.activeReferences.entries()) {
172
+ for (const [referenceId, _context] of this.activeReferences.entries()) {
173
173
  try {
174
174
  const isValid = await this.contentStorage.hasReference(referenceId);
175
175
  if (isValid) {
@@ -218,7 +218,12 @@ export class ReferenceContextManager {
218
218
  /**
219
219
  * Get current context statistics
220
220
  */
221
- getContextStats() {
221
+ getContextStats(): {
222
+ activeReferences: number;
223
+ conversationTurn: number;
224
+ oldestReference: number | null;
225
+ mostRecentReference: number | null;
226
+ } {
222
227
  return {
223
228
  activeReferences: this.activeReferences.size,
224
229
  conversationTurn: this.conversationTurn,
@@ -270,7 +275,7 @@ export class ReferenceContextManager {
270
275
  }
271
276
 
272
277
  if (includeActions) {
273
- display += `\n💡 You can say "inscribe it" to inscribe this content to the Hedera network.`;
278
+ display += `\n💡 You can say "inscribe it" to inscribe this content to the Hedera Hashgraph.`;
274
279
  }
275
280
 
276
281
  display += `\n\n*Reference ID: ${reference.referenceId.substring(0, 12)}...*`;
@@ -314,7 +319,7 @@ export class ReferenceContextManager {
314
319
  if (text.length <= maxLength) {
315
320
  return text;
316
321
  }
317
- return text.substring(0, maxLength - 3) + '...';
322
+ return text.substring(0, maxLength) + '...';
318
323
  }
319
324
 
320
325
  private getOldestReferenceAge(): number | null {
@@ -76,7 +76,7 @@ export class ReferenceResponseProcessor {
76
76
  const suggestedActions: string[] = [];
77
77
 
78
78
  if (autoDisplayReferences) {
79
- for (const { reference, position, originalText } of detection.references) {
79
+ for (const { reference, originalText } of detection.references) {
80
80
  const displayResult = await this.contextManager.displayReference(reference, displayOptions);
81
81
 
82
82
  processedContent = processedContent.replace(originalText, displayResult.displayText);
@@ -185,7 +185,7 @@ export class ReferenceResponseProcessor {
185
185
  }> = [];
186
186
 
187
187
  const contentReferenceRegex = /"type":\s*"content_reference"[^}]*"referenceId":\s*"([^"]+)"[^}]*}/g;
188
- let match;
188
+ let match: RegExpExecArray | null;
189
189
 
190
190
  while ((match = contentReferenceRegex.exec(content)) !== null) {
191
191
  try {
@@ -212,7 +212,7 @@ export class ReferenceResponseProcessor {
212
212
  }
213
213
 
214
214
  const plainRefRegex = /ref:\/\/([A-Za-z0-9_-]{43})|(?:^|\s)([A-Za-z0-9_-]{43})(?=\s|$)/g;
215
- let plainMatch;
215
+ let plainMatch: RegExpExecArray | null;
216
216
 
217
217
  while ((plainMatch = plainRefRegex.exec(content)) !== null) {
218
218
  const referenceId = plainMatch[1] || plainMatch[2];
@@ -246,7 +246,6 @@ export class ReferenceResponseProcessor {
246
246
  const parsed = JSON.parse(preview);
247
247
  preview = JSON.stringify(parsed, null, 0);
248
248
  } catch {
249
- // Keep original if not valid JSON
250
249
  }
251
250
  }
252
251