@hashgraphonline/conversational-agent 0.2.103 → 0.2.105

package/src/langchain/form-aware-agent-executor.ts

@@ -979,9 +979,11 @@ export class FormAwareAgentExecutor extends AgentExecutor {
               '🔗 HASHLINK DETECTED: Processing HashLink response separately to preserve metadata'
             );
 
+            const parsedRecord = parsed as Record<string, unknown>;
             responseMetadata = {
               ...responseMetadata,
-              hashLinkBlock: (parsed as Record<string, unknown>).hashLinkBlock,
+              hashLinkBlock: parsedRecord.hashLinkBlock,
+              ...parsedRecord,
             };
 
             formattedOutput = ResponseFormatter.formatHashLinkResponse(parsed);
@@ -1003,6 +1005,7 @@ export class FormAwareAgentExecutor extends AgentExecutor {
             responseMetadata = {
               ...responseMetadata,
               hashLinkBlock: (parsed as Record<string, unknown>).hashLinkBlock,
+              ...parsed,
             };
           }
         } else {
@@ -1240,6 +1243,7 @@ Please fill out the form below to continue.`;
     }));
   }
 
+
   /**
    * Processes HashLink block responses from tools
    */
@@ -1251,11 +1255,7 @@ Please fill out the form below to continue.`;
 
       if (toolResponse.hashLinkBlock) {
         hashLinkBlock = toolResponse.hashLinkBlock;
-      } else if (
-        toolResponse.success &&
-        toolResponse.inscription &&
-        toolResponse.hashLinkBlock
-      ) {
+      } else if (toolResponse.success && toolResponse.hashLinkBlock) {
         hashLinkBlock = toolResponse.hashLinkBlock;
       }
 

package/src/langchain/langchain-agent.ts

@@ -819,7 +819,7 @@ export class LangChainAgent extends BaseAgent {
             if (args.metaOptions && typeof args.metaOptions === 'object') {
               const metaOptions = args.metaOptions as Record<string, unknown>;
               if (metaOptions.transactionMemo) {
-                console.warn(
+                this.logger.warn(
                   '🚨 WORKAROUND: Stripping transactionMemo from hedera-hts-mint-nft to avoid bug',
                   { originalMemo: metaOptions.transactionMemo }
                 );

package/src/mcp/mcp-client-manager.ts

@@ -56,10 +56,17 @@ export class MCPClientManager {
       this.clients.set(config.name, client);
 
       const toolsResponse = await client.listTools();
-      const toolsWithServer: MCPToolInfo[] = toolsResponse.tools.map(tool => ({
-        ...tool,
-        serverName: config.name,
-      }));
+      const toolsWithServer: MCPToolInfo[] = toolsResponse.tools.map((tool: unknown) => {
+        const t = tool as { description?: string } & Record<string, unknown>;
+        const { description, ...rest } = t;
+        const base = description !== undefined && typeof description === 'string'
+          ? { ...rest, description }
+          : { ...rest };
+        return {
+          ...(base as Omit<MCPToolInfo, 'serverName'>),
+          serverName: config.name,
+        } as MCPToolInfo;
+      });
 
       this.tools.set(config.name, toolsWithServer);
       this.logger.info(`Connected to MCP server ${config.name} with ${toolsWithServer.length} tools`);
@@ -205,4 +212,4 @@ export class MCPClientManager {
     }
     return this.contentProcessor.analyzeResponse(response);
   }
-}
+}

package/src/mcp/types.ts

@@ -1,4 +1,16 @@
-import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Minimal MCP Tool shape used internally to avoid external type dependency resolution issues.
+ * Aligns with MCP tool metadata returned by listTools.
+ */
+export interface BaseMCPTool {
+  name: string;
+  description?: string;
+  /**
+   * JSON Schema describing input parameters for the tool.
+   * Kept as unknown and validated/converted at the boundary.
+   */
+  inputSchema?: unknown;
+}
 
 export interface MCPServerConfig {
   name: string;
@@ -17,7 +29,7 @@ export interface MCPServerConfig {
   toolDescriptions?: Record<string, string>;
 }
 
-export interface MCPToolInfo extends Tool {
+export interface MCPToolInfo extends BaseMCPTool {
   serverName: string;
 }
 
@@ -26,4 +38,4 @@ export interface MCPConnectionStatus {
   connected: boolean;
   error?: string;
   tools: MCPToolInfo[];
-}
+}

package/src/memory/content-storage.ts

@@ -317,7 +317,11 @@ export class ContentStorage implements ContentReferenceStore {
    * Get the current storage configuration
    * @returns Storage configuration object
    */
-  getConfig(): { maxStorage: number; currentUsage: number; utilizationPercentage: number } {
+  getConfig(): {
+    maxStorage: number;
+    currentUsage: number;
+    utilizationPercentage: number;
+  } {
     return {
       maxStorage: this.maxStorage,
       currentUsage: this.messages.length,
@@ -354,11 +358,17 @@ export class ContentStorage implements ContentReferenceStore {
    * Export messages to a JSON-serializable format
    * @returns Serializable representation of stored messages
    */
-  exportMessages(): Array<{ content: string; type: string; storedAt: string; id: string }> {
+  exportMessages(): Array<{
+    content: string;
+    type: string;
+    storedAt: string;
+    id: string;
+  }> {
     return this.messages.map((stored) => ({
-      content: typeof stored.message.content === 'string' 
-        ? stored.message.content 
-        : JSON.stringify(stored.message.content),
+      content:
+        typeof stored.message.content === 'string'
+          ? stored.message.content
+          : JSON.stringify(stored.message.content),
       type: stored.message._getType(),
       storedAt: stored.storedAt.toISOString(),
       id: stored.id,
@@ -832,7 +842,10 @@ export class ContentStorage implements ContentReferenceStore {
     return new Date(Date.now() + policy.maxAgeMs);
   }
 
-  private getCleanupPolicy(source: ContentSource): { maxAgeMs: number; priority: number } {
+  private getCleanupPolicy(source: ContentSource): {
+    maxAgeMs: number;
+    priority: number;
+  } {
     switch (source) {
       case 'mcp_tool':
         return this.referenceConfig.cleanupPolicies.recent;

package/src/memory/smart-memory-manager.ts

@@ -702,7 +702,6 @@ export class SmartMemoryManager {
         }
       }
 
-      // Merge duplicates by entityId, preferring the newest and one that carries transactionId
       const mergedById = new Map<string, EntityAssociation>();
       const getTime = (d: Date | string): number =>
         d instanceof Date ? d.getTime() : new Date(d).getTime();

package/src/plugins/hbar/AccountBuilder.ts

@@ -1,8 +1,4 @@
-import {
-  AccountId,
-  Hbar,
-  TransferTransaction,
-} from '@hashgraph/sdk';
+import { AccountId, Hbar, TransferTransaction } from '@hashgraph/sdk';
 import BigNumber from 'bignumber.js';
 import { HederaAgentKit, BaseServiceBuilder } from 'hedera-agent-kit';
 import { HbarTransferParams } from './types';
@@ -24,7 +20,7 @@ export class AccountBuilder extends BaseServiceBuilder {
   ): this {
     this.clearNotes();
     const transaction = new TransferTransaction();
-    
+
     if (!params.transfers || params.transfers.length === 0) {
       throw new Error('HbarTransferParams must include at least one transfer.');
     }
@@ -61,7 +57,7 @@ export class AccountBuilder extends BaseServiceBuilder {
             this.kit.userAccountId
           } to ${recipientAccountId.toString()}`
         );
-        
+
         this.addNote(
           `Configured HBAR transfer from your account (${
             this.kit.userAccountId
@@ -84,7 +80,7 @@ export class AccountBuilder extends BaseServiceBuilder {
         amount: BigNumber;
         hbar: Hbar;
       }> = [];
-      
+
       for (const transferInput of params.transfers) {
         const accountId =
           typeof transferInput.accountId === 'string'
@@ -99,7 +95,7 @@ export class AccountBuilder extends BaseServiceBuilder {
 
         const amountBigNum = new BigNumber(amountValue);
         const roundedAmount = amountBigNum.toFixed(8, BigNumber.ROUND_DOWN);
-        
+
         this.logger.info(
           `Processing transfer: ${amountValue} HBAR (rounded to ${roundedAmount}) for account ${accountId.toString()}`
         );
@@ -108,7 +104,7 @@ export class AccountBuilder extends BaseServiceBuilder {
         processedTransfers.push({
           accountId,
           amount: amountBigNum,
-          hbar: sdkHbarAmount
+          hbar: sdkHbarAmount,
         });
 
         const tinybarsContribution = sdkHbarAmount.toTinybars();
@@ -121,20 +117,24 @@ export class AccountBuilder extends BaseServiceBuilder {
         this.logger.warn(
           `Transfer sum not zero: ${netZeroInTinybars.toString()} tinybars off. Adjusting last transfer.`
         );
-        
+
         if (processedTransfers.length > 0) {
-          const lastTransfer = processedTransfers[processedTransfers.length - 1];
+          const lastTransfer =
+            processedTransfers[processedTransfers.length - 1];
           const adjustment = netZeroInTinybars.dividedBy(-100000000);
           const adjustedAmount = lastTransfer.amount.plus(adjustment);
-          const adjustedRounded = adjustedAmount.toFixed(8, BigNumber.ROUND_DOWN);
+          const adjustedRounded = adjustedAmount.toFixed(
+            8,
+            BigNumber.ROUND_DOWN
+          );
           lastTransfer.hbar = Hbar.fromString(adjustedRounded);
-          
+
           this.logger.info(
             `Adjusted last transfer for ${lastTransfer.accountId.toString()} to ${adjustedRounded} HBAR`
           );
         }
       }
-      
+
       for (const transfer of processedTransfers) {
         transaction.addHbarTransfer(transfer.accountId, transfer.hbar);
       }
@@ -151,4 +151,4 @@ export class AccountBuilder extends BaseServiceBuilder {
     this.setCurrentTransaction(transaction);
     return this;
   }
-}
+}

package/src/plugins/hcs-10/HCS10Plugin.ts

@@ -19,33 +19,15 @@ import {
   AcceptConnectionRequestTool,
   RetrieveProfileTool,
   ListUnapprovedConnectionRequestsTool,
+  RegisteredAgent,
 } from '@hashgraphonline/standards-agent-kit';
 import { HCS10Client } from '@hashgraphonline/standards-sdk';
+import { PrivateKey } from 'node_modules/@hashgraph/sdk/lib/Mnemonic';
 
 interface HCS10ClientManager {
   initializeConnectionsManager(client: HCS10Client): void;
 }
 
-/**
- * Extracts private key string from operator key
- */
-function extractPrivateKey(opKey: unknown): string {
-  const key = opKey as {
-    toString?: () => string;
-    toStringRaw?: () => string;
-  };
-  
-  if (typeof key?.toStringRaw === 'function') {
-    return key.toStringRaw();
-  }
-  
-  if (typeof key?.toString === 'function') {
-    return key.toString();
-  }
-  
-  return String(key);
-}
-
 function hasInitializeConnectionsManager(
   stateManager: IStateManager
 ): stateManager is IStateManager & HCS10ClientManager {
@@ -67,7 +49,7 @@ export class HCS10Plugin extends BasePlugin {
   namespace = 'hcs10';
 
   private stateManager?: IStateManager;
-  private tools: HederaTool[] = [];
+  private tools: any[] = [];
   appConfig?: Record<string, unknown>;
 
   override async initialize(context: GenericPluginContext): Promise<void> {
@@ -89,17 +71,27 @@ export class HCS10Plugin extends BasePlugin {
         new OpenConvaiState();
 
       const accountId = hederaKit.signer.getAccountId().toString();
+      const isBytesMode =
+        String(hederaKit.operationalMode || 'returnBytes') === 'returnBytes';
       let inboundTopicId = '';
       let outboundTopicId = '';
 
+      let operatorPrivateKeyRef: PrivateKey =
+        hederaKit.signer.getOperatorPrivateKey();
+      let operatorPrivateKeySerialized: string | undefined;
+
       try {
-        const opKey = hederaKit.signer.getOperatorPrivateKey();
-        const privateKey = extractPrivateKey(opKey);
+        const resolved =
+          typeof operatorPrivateKeyRef?.toString === 'function'
+            ? operatorPrivateKeyRef.toString()
+            : '';
+
+        operatorPrivateKeySerialized = resolved;
 
         const hcs10Client = new HCS10Client({
           network: hederaKit.network as 'mainnet' | 'testnet',
           operatorId: accountId,
-          operatorPrivateKey: privateKey,
+          operatorPrivateKey: operatorPrivateKeyRef,
           logLevel: 'error',
         });
 
@@ -110,52 +102,60 @@ export class HCS10Plugin extends BasePlugin {
         }
       } catch (profileError) {
         this.context.logger.warn(
-          'Could not retrieve profile topics:',
+          'Skipping profile topic discovery',
           profileError
         );
       }
 
-      this.stateManager.setCurrentAgent({
+      const agentRecord: Record<string, unknown> = {
         name: `Agent ${accountId}`,
         accountId: accountId,
         inboundTopicId,
         outboundTopicId,
-        privateKey: ((): string => {
-          const opKey = hederaKit.signer.getOperatorPrivateKey();
-          return extractPrivateKey(opKey);
-        })(),
-      });
+      };
+      if (!isBytesMode && operatorPrivateKeySerialized) {
+        agentRecord.privateKey = operatorPrivateKeySerialized;
+      }
+      this.stateManager.setCurrentAgent(
+        agentRecord as unknown as RegisteredAgent
+      );
 
       this.context.logger.info(
         `Set current agent: ${accountId} with topics ${inboundTopicId}/${outboundTopicId}`
       );
 
-      if (this.stateManager && !this.stateManager.getConnectionsManager()) {
+      if (
+        !isBytesMode &&
+        this.stateManager &&
+        !this.stateManager.getConnectionsManager()
+      ) {
         try {
-          const opKey = hederaKit.signer.getOperatorPrivateKey();
-          const privateKey = extractPrivateKey(opKey);
           const hcs10Client = new HCS10Client({
             network: hederaKit.network as 'mainnet' | 'testnet',
             operatorId: accountId,
-            operatorPrivateKey: privateKey,
+            operatorPrivateKey: operatorPrivateKeyRef ?? '',
             logLevel: 'error',
           });
 
           if (hasInitializeConnectionsManager(this.stateManager)) {
             this.stateManager.initializeConnectionsManager(hcs10Client);
           } else {
-            this.context.logger.warn('StateManager does not support connection manager initialization');
+            this.context.logger.warn(
+              'StateManager does not support connection manager initialization'
+            );
           }
           this.context.logger.info(
             'ConnectionsManager initialized in HCS10Plugin'
           );
         } catch (cmError) {
-          this.context.logger.warn('Could not initialize ConnectionsManager:', cmError);
+          this.context.logger.warn(
+            'Could not initialize ConnectionsManager:',
+            cmError
+          );
         }
       }
 
       this.initializeTools();
-
       this.context.logger.info('HCS-10 Plugin initialized successfully');
     } catch (error) {
       this.context.logger.error('Failed to initialize HCS-10 plugin:', error);

package/src/plugins/hcs-2/HCS2Plugin.ts

@@ -26,7 +26,7 @@ export class HCS2Plugin extends BasePlugin {
   author = 'Hashgraph Online';
   namespace = 'hcs2';
 
-  private tools: HederaTool[] = [];
+  private tools: any[] = [];
 
   override async initialize(context: GenericPluginContext): Promise<void> {
     await super.initialize(context);
@@ -105,4 +105,4 @@ export class HCS2Plugin extends BasePlugin {
       this.context.logger.info('HCS-2 Plugin cleaned up');
     }
   }
-}
+}

package/src/plugins/index.ts

@@ -2,4 +2,5 @@ export { HCS10Plugin } from './hcs-10';
 export { HCS2Plugin } from './hcs-2';
 export { InscribePlugin } from './inscribe';
 export { HbarPlugin } from './hbar/HbarPlugin';
-export * from './hbar';
+export * from './hbar';
+export { WebBrowserPlugin } from './web-browser/WebBrowserPlugin';

package/src/plugins/inscribe/InscribePlugin.ts

@@ -12,6 +12,7 @@ import {
   InscribeHashinalTool,
   RetrieveInscriptionTool,
 } from '@hashgraphonline/standards-agent-kit';
+import { fieldGuidanceRegistry, type FieldGuidance } from '../../forms/field-guidance-registry';
 
 /**
  * Plugin providing content inscription tools for Hedera
@@ -25,7 +26,8 @@ export class InscribePlugin extends BasePlugin {
   author = 'Hashgraph Online';
   namespace = 'inscribe';
 
-  private tools: HederaTool[] = [];
+  private tools: any[] = [];
+  private providerId: string | null = null;
 
   override async initialize(context: GenericPluginContext): Promise<void> {
     await super.initialize(context);
@@ -41,6 +43,42 @@ export class InscribePlugin extends BasePlugin {
     try {
       this.initializeTools();
 
+      try {
+        const provider = {
+          getFieldGuidance: (fieldName: string): FieldGuidance | null => {
+            if (fieldName === 'name') {
+              return {
+                suggestions: [
+                  'Sunset Landscape #42',
+                  'Digital Abstract Art',
+                ],
+                contextualHelpText:
+                  'Create a distinctive name that collectors will find appealing',
+              };
+            }
+            if (fieldName === 'description') {
+              return {
+                fieldTypeOverride: 'textarea',
+                suggestions: ['A beautiful piece representing...'],
+              };
+            }
+            return null;
+          },
+          getGlobalGuidance: () => ({
+            qualityStandards: [
+              'Use meaningful names that describe the artwork or content',
+            ],
+          }),
+        };
+        this.providerId = fieldGuidanceRegistry.registerToolProvider(
+          /hashinal/i,
+          provider,
+          { id: 'inscribe:hashinal:provider', priority: 1 }
+        );
+      } catch (e) {
+        this.context.logger.warn('Could not register Inscribe field guidance provider');
+      }
+
       this.context.logger.info(
         'Inscribe Plugin initialized successfully'
       );
@@ -95,8 +133,14 @@ export class InscribePlugin extends BasePlugin {
 
   override async cleanup(): Promise<void> {
     this.tools = [];
+    if (this.providerId) {
+      try {
+        fieldGuidanceRegistry.unregisterProvider(this.providerId);
+      } catch {}
+      this.providerId = null;
+    }
     if (this.context?.logger) {
       this.context.logger.info('Inscribe Plugin cleaned up');
     }
   }
-}
+}

package/src/plugins/web-browser/WebBrowserPlugin.ts

@@ -0,0 +1,128 @@
+import {
+  BasePlugin,
+  type GenericPluginContext,
+  BaseHederaQueryTool,
+  type HederaAgentKit,
+  type HederaTool,
+} from 'hedera-agent-kit';
+import { z } from 'zod';
+
+const PageSnapshotSchema = z.object({
+  url: z.string().url(),
+  maxCharacters: z
+    .number()
+    .int()
+    .min(256, 'Minimum length is 256 characters')
+    .max(8000, 'Maximum length is 8000 characters')
+    .optional()
+    .default(3000),
+});
+
+class WebPageSnapshotTool extends BaseHederaQueryTool<typeof PageSnapshotSchema> {
+  name = 'web_page_snapshot';
+  description = 'Fetches the visible text content of a web page for analysis.';
+  namespace = 'browser';
+  specificInputSchema = PageSnapshotSchema;
+
+  constructor(params: {
+    hederaKit: HederaAgentKit;
+    logger?: GenericPluginContext['logger'];
+    fetchImpl?: typeof fetch;
+  }) {
+    const { fetchImpl, ...rest } = params;
+    super(rest);
+    this.fetchImpl = fetchImpl ?? fetch;
+  }
+
+  private readonly fetchImpl: typeof fetch;
+
+  protected async executeQuery(
+    input: z.infer<typeof PageSnapshotSchema>
+  ): Promise<string> {
+    const maxChars = input.maxCharacters ?? 3000;
+
+    try {
+      const response = await this.fetchImpl(input.url, {
+        redirect: 'follow',
+      });
+
+      if (!response.ok) {
+        return `Failed to load ${input.url}: HTTP ${response.status}`;
+      }
+
+      const html = await response.text();
+      const text = this.normalizeHtml(html);
+
+      if (!text) {
+        return 'The fetched page did not contain readable text.';
+      }
+
+      return text.length > maxChars ? `${text.slice(0, maxChars)}…` : text;
+    } catch (error) {
+      this.logger.error('WebPageSnapshotTool failed', error);
+      return `Failed to fetch content for ${input.url}: ${
+        error instanceof Error ? error.message : String(error)
+      }`;
+    }
+  }
+
+  private normalizeHtml(html: string): string {
+    const withoutScripts = html
+      .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+      .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+      .replace(/<!--([\s\S]*?)-->/g, ' ');
+
+    const stripped = withoutScripts.replace(/<[^>]+>/g, ' ');
+    const decoded = stripped
+      .replace(/&nbsp;/gi, ' ')
+      .replace(/&amp;/gi, '&')
+      .replace(/&lt;/gi, '<')
+      .replace(/&gt;/gi, '>')
+      .replace(/&quot;/gi, '"')
+      .replace(/&#39;/gi, "'");
+
+    return decoded.replace(/\s+/g, ' ').trim();
+  }
+}
+
+export class WebBrowserPlugin extends BasePlugin<GenericPluginContext> {
+  id = 'web-browser';
+  name = 'Web Browser Plugin';
+  description =
+    'Provides tools for fetching live web page content to enrich assistant understanding.';
+  version = '0.1.0';
+  author = 'Hashgraph Online';
+  namespace = 'browser';
+
+  private tools: HederaTool[] = [];
+
+  override async initialize(context: GenericPluginContext): Promise<void> {
+    await super.initialize(context);
+
+    const hederaKit = context.config.hederaKit as HederaAgentKit | undefined;
+
+    if (!hederaKit) {
+      this.context.logger.warn(
+        'WebBrowserPlugin skipped because HederaAgentKit was not present in plugin context.'
+      );
+      this.tools = [];
+      return;
+    }
+
+    const tool = new WebPageSnapshotTool({
+      hederaKit,
+      logger: this.context.logger,
+    });
+
+    this.tools = [tool];
+    this.context.logger.info('Web Browser Plugin initialized with snapshot tool');
+  }
+
+  override getTools(): HederaTool[] {
+    return this.tools;
+  }
+
+  override async cleanup(): Promise<void> {
+    this.tools = [];
+  }
+}

package/src/runtime/wallet-bridge.ts

@@ -0,0 +1,46 @@
+export type WalletNetwork = 'mainnet' | 'testnet';
+
+export interface WalletStatus {
+  connected: boolean;
+  accountId?: string;
+  network?: WalletNetwork;
+}
+
+export interface WalletExecutorResult {
+  transactionId: string;
+}
+
+export interface StartInscriptionResult {
+  transactionBytes: string;
+  tx_id?: string;
+  topic_id?: string;
+  status?: string;
+  completed?: boolean;
+}
+
+export interface WalletBridgeProvider {
+  status: () => Promise<WalletStatus> | WalletStatus;
+  executeBytes: (
+    base64: string,
+    network: WalletNetwork
+  ) => Promise<WalletExecutorResult>;
+  startInscription?: (
+    request: Record<string, unknown>,
+    network: WalletNetwork
+  ) => Promise<StartInscriptionResult>;
+  startHCS?: (
+    op: string,
+    request: Record<string, unknown>,
+    network: WalletNetwork
+  ) => Promise<{ transactionBytes: string }>;
+}
+
+let providerRef: WalletBridgeProvider | null = null;
+
+export function setWalletBridgeProvider(provider: WalletBridgeProvider): void {
+  providerRef = provider;
+}
+
+export function getWalletBridgeProvider(): WalletBridgeProvider | null {
+  return providerRef;
+}