@hashgraphonline/conversational-agent 0.2.104 → 0.2.105

package/src/conversational-agent.ts

@@ -2,13 +2,14 @@ import {
   ServerSigner,
   getAllHederaCorePlugins,
   BasePlugin,
+  AbstractSigner,
 } from 'hedera-agent-kit';
 import { Logger, type NetworkType } from '@hashgraphonline/standards-sdk';
 import { createAgent } from './agent-factory';
+import BrowserSigner from './signers/browser-signer';
 import { LangChainProvider } from './providers';
 import type { ChatResponse, ConversationContext } from './base-agent';
 import { ChatOpenAI } from '@langchain/openai';
-import OpenAI from 'openai';
 import { ChatAnthropic } from '@langchain/anthropic';
 import {
   HumanMessage,
@@ -19,7 +20,13 @@ import type { AgentOperationalMode, MirrorNodeConfig } from 'hedera-agent-kit';
 import { HCS10Plugin } from './plugins/hcs-10/HCS10Plugin';
 import { HCS2Plugin } from './plugins/hcs-2/HCS2Plugin';
 import { InscribePlugin } from './plugins/inscribe/InscribePlugin';
+import { getWalletBridgeProvider } from './runtime/wallet-bridge';
+import {
+  InscriberBuilder,
+  SignerProviderRegistry,
+} from '@hashgraphonline/standards-agent-kit';
 import { HbarPlugin } from './plugins/hbar/HbarPlugin';
+import { WebBrowserPlugin } from './plugins/web-browser/WebBrowserPlugin';
 import { OpenConvaiState } from '@hashgraphonline/standards-agent-kit';
 import type { IStateManager } from '@hashgraphonline/standards-agent-kit';
 import { getSystemMessage } from './config/system-message';
@@ -52,6 +59,9 @@ export type AgentInstance = ReturnType<typeof createAgent>;
 export type MirrorNetwork = 'testnet' | 'mainnet' | 'previewnet';
 
 const DEFAULT_MODEL_NAME = 'gpt-4o';
+const DEFAULT_OPENAI_MODEL = 'gpt-4o-mini';
+const DEFAULT_OPENROUTER_MODEL = 'openai/gpt-4o-mini';
+const DEFAULT_CLAUDE_MODEL = 'claude-3-7-sonnet-latest';
 const DEFAULT_TEMPERATURE = 0.1;
 const DEFAULT_NETWORK = 'testnet';
 const DEFAULT_OPERATIONAL_MODE: AgentOperationalMode = 'autonomous';
@@ -74,8 +84,19 @@ export interface ConversationalAgentOptions {
   mirrorNodeConfig?: MirrorNodeConfig;
   disableLogging?: boolean;
   enabledPlugins?: string[];
+  disabledPlugins?: string[];
   toolFilter?: (tool: { name: string; namespace?: string }) => boolean;
   mcpServers?: MCPServerConfig[];
+  walletExecutor?: (
+    base64: string,
+    network: 'mainnet' | 'testnet'
+  ) => Promise<{ transactionId: string }>;
+  /** Optional: provide a signer factory to override default signer selection */
+  customSignerFactory?: (args: {
+    operationalMode: AgentOperationalMode;
+    accountId: string;
+    network: NetworkType;
+  }) => AbstractSigner;
 
   /** Enable automatic entity memory functionality (default: true) */
   entityMemoryEnabled?: boolean;
@@ -114,6 +135,7 @@ export class ConversationalAgent {
   public hcs2Plugin: HCS2Plugin;
   public inscribePlugin: InscribePlugin;
   public hbarPlugin: HbarPlugin;
+  public webBrowserPlugin: WebBrowserPlugin;
   public stateManager: IStateManager;
   private options: ConversationalAgentOptions;
   public logger: Logger;
@@ -131,6 +153,7 @@ export class ConversationalAgent {
     this.hcs2Plugin = new HCS2Plugin();
     this.inscribePlugin = new InscribePlugin();
     this.hbarPlugin = new HbarPlugin();
+    this.webBrowserPlugin = new WebBrowserPlugin();
     this.logger = new Logger({
       module: 'ConversationalAgent',
       silent: options.disableLogging || false,
@@ -148,14 +171,18 @@ export class ConversationalAgent {
       );
       this.logger.info('Entity memory initialized');
 
-      const provider = options.entityMemoryProvider || options.llmProvider || 'openai';
-      const modelName =
-        options.entityMemoryModelName ||
-        (provider === 'anthropic'
-          ? 'claude-3-7-sonnet-latest'
-          : provider === 'openrouter'
-          ? 'openai/gpt-4o-mini'
-          : 'gpt-4o-mini');
+      const provider =
+        options.entityMemoryProvider || options.llmProvider || 'openai';
+      let modelName = options.entityMemoryModelName;
+      if (!modelName) {
+        if (provider === 'anthropic') {
+          modelName = DEFAULT_CLAUDE_MODEL;
+        } else if (provider === 'openrouter') {
+          modelName = DEFAULT_OPENROUTER_MODEL;
+        } else {
+          modelName = DEFAULT_OPENAI_MODEL;
+        }
+      }
 
       let resolverLLM: ChatOpenAI | ChatAnthropic;
       if (provider === 'anthropic') {
@@ -165,7 +192,8 @@ export class ConversationalAgent {
           temperature: 0,
         });
       } else if (provider === 'openrouter') {
-        const baseURL = options.openRouterBaseURL || 'https://openrouter.ai/api/v1';
+        const baseURL =
+          options.openRouterBaseURL || 'https://openrouter.ai/api/v1';
         const apiKey = options.openRouterApiKey || options.openAIApiKey;
         resolverLLM = new ChatOpenAI({
           apiKey,
@@ -174,8 +202,12 @@ export class ConversationalAgent {
           configuration: {
             baseURL,
             defaultHeaders: {
-              'HTTP-Referer': process.env.OPENROUTER_REFERRER || 'https://hashgraphonline.com',
-              'X-Title': process.env.OPENROUTER_TITLE || 'Hashgraph Online Conversational Agent',
+              'HTTP-Referer':
+                process.env.OPENROUTER_REFERRER ||
+                'https://hashgraphonline.com',
+              'X-Title':
+                process.env.OPENROUTER_TITLE ||
+                'Hashgraph Online Conversational Agent',
             },
           },
         });
@@ -210,29 +242,213 @@ export class ConversationalAgent {
     this.validateOptions(accountId, privateKey);
 
     try {
-      const serverSigner = new ServerSigner(
-        accountId!,
-        privateKey!,
-        network as MirrorNetwork
-      );
+      const opMode = (this.options.operationalMode ||
+        DEFAULT_OPERATIONAL_MODE) as string;
+      const bytesMode = opMode !== 'autonomous';
+      let signer: AbstractSigner;
+
+      try {
+        type InscriberBuilderWithWalletMethods = typeof InscriberBuilder & {
+          setPreferWalletOnly?: (prefer: boolean) => void;
+          setWalletInfoResolver?: (
+            fn: () => Promise<{ accountId: string; network: string } | null>
+          ) => void;
+          setWalletExecutor?: (
+            fn: (
+              base64: string,
+              network: 'mainnet' | 'testnet'
+            ) => Promise<{ transactionId: string }>
+          ) => void;
+          setStartInscriptionDelegate?: (
+            fn: (
+              request: Record<string, unknown>,
+              network: 'mainnet' | 'testnet'
+            ) => Promise<unknown>
+          ) => void;
+        };
+        const IB = InscriberBuilder as InscriberBuilderWithWalletMethods;
+        if (typeof IB.setPreferWalletOnly === 'function') {
+          IB.setPreferWalletOnly(false);
+        }
+      } catch (e) {
+        this.logger.warn('Failed to set wallet-only preference', e as Error);
+      }
+      if (!bytesMode) {
+        signer = new ServerSigner(
+          accountId!,
+          privateKey!,
+          network as MirrorNetwork
+        );
+      } else {
+        const chain: 'mainnet' | 'testnet' =
+          String(network || 'testnet') === 'mainnet' ? 'mainnet' : 'testnet';
+        const effectiveAccount = (this.options.userAccountId || accountId)!;
+        signer = new BrowserSigner(
+          effectiveAccount,
+          chain,
+          this.options.walletExecutor
+        );
+      }
+
+      this.logger.info('Signer configured', {
+        operationalMode: opMode,
+        bytesMode,
+        signerClass:
+          Object.getPrototypeOf(signer)?.constructor?.name || 'unknown',
+      });
+
+      try {
+        const bridge = getWalletBridgeProvider();
+        if (bridge) {
+          type InscriberBuilderWithWalletMethods = typeof InscriberBuilder & {
+            setWalletInfoResolver?: (
+              fn: () => Promise<{ accountId: string; network: string } | null>
+            ) => void;
+            setWalletExecutor?: (
+              fn: (
+                base64: string,
+                network: 'mainnet' | 'testnet'
+              ) => Promise<{ transactionId: string }>
+            ) => void;
+            setStartInscriptionDelegate?: (
+              fn: (
+                request: Record<string, unknown>,
+                network: 'mainnet' | 'testnet'
+              ) => Promise<unknown>
+            ) => void;
+          };
+          const IB = InscriberBuilder as InscriberBuilderWithWalletMethods;
+          if (typeof IB.setWalletInfoResolver === 'function') {
+            IB.setWalletInfoResolver(async () => {
+              const status = await bridge.status();
+              if (status.connected && status.accountId && status.network) {
+                return { accountId: status.accountId, network: status.network };
+              }
+              return null;
+            });
+          }
+          if (typeof IB.setWalletExecutor === 'function') {
+            IB.setWalletExecutor(
+              async (base64: string, network: 'mainnet' | 'testnet') => {
+                return await bridge.executeBytes(base64, network);
+              }
+            );
+          }
+          if (
+            typeof IB.setStartInscriptionDelegate === 'function' &&
+            bridge.startInscription
+          ) {
+            IB.setStartInscriptionDelegate(
+              async (
+                request: Record<string, unknown>,
+                network: 'mainnet' | 'testnet'
+              ) => {
+                return await bridge.startInscription!(request, network);
+              }
+            );
+          }
+
+          try {
+            type HCSOp =
+              | 'submitConnectionRequest'
+              | 'handleConnectionRequest'
+              | 'sendMessage'
+              | 'hcs2.createRegistry'
+              | 'hcs2.migrateRegistry'
+              | 'hcs2.registerEntry'
+              | 'hcs2.updateEntry'
+              | 'hcs2.deleteEntry'
+              | 'hcs2.submitMessage'
+              | 'hcs6.createRegistry'
+              | 'hcs6.registerEntry'
+              | 'hcs6.submitMessage';
+            type WalletBridgeProviderExt = ReturnType<
+              typeof getWalletBridgeProvider
+            > & {
+              startHCS?: (
+                op: HCSOp,
+                request: Record<string, unknown>,
+                network: 'mainnet' | 'testnet'
+              ) => Promise<{ transactionBytes: string }>;
+            };
+
+            const status = await bridge.status();
+            const enforceWallet = !!(bytesMode && status.connected);
+
+            SignerProviderRegistry.setWalletInfoResolver(async () => {
+              const s = await bridge.status();
+              if (s.connected && s.accountId && s.network) {
+                return {
+                  accountId: s.accountId,
+                  network: s.network as 'mainnet' | 'testnet',
+                };
+              }
+              return null;
+            });
+
+            SignerProviderRegistry.setWalletExecutor(
+              async (base64: string, network: 'mainnet' | 'testnet') => {
+                return await bridge.executeBytes(base64, network);
+              }
+            );
+
+            const extended = bridge as WalletBridgeProviderExt;
+            if (typeof extended?.startHCS === 'function') {
+              SignerProviderRegistry.setStartHCSDelegate(
+                async (op, request, network) => {
+                  return await extended.startHCS!(
+                    op as HCSOp,
+                    request,
+                    network
+                  );
+                }
+              );
+            } else {
+              SignerProviderRegistry.setStartHCSDelegate(null);
+            }
+
+            SignerProviderRegistry.setPreferWalletOnly(enforceWallet);
+
+            type InscriberBuilderWithWalletMethods = typeof InscriberBuilder & {
+              setPreferWalletOnly?: (prefer: boolean) => void;
+            };
+            const IB2 = InscriberBuilder as InscriberBuilderWithWalletMethods;
+            if (typeof IB2.setPreferWalletOnly === 'function') {
+              IB2.setPreferWalletOnly(enforceWallet);
+            }
+          } catch (sakWireErr) {
+            this.logger.warn(
+              'Failed to wire SAK SignerProviderRegistry wallet delegates',
+              sakWireErr as Error
+            );
+          }
+        }
+      } catch (e) {
+        this.logger.warn(
+          'Failed to register wallet bridge providers',
+          e as Error
+        );
+      }
 
       let llm: ChatOpenAI | ChatAnthropic;
       let providerInfo: Record<string, unknown> = { provider: llmProvider };
       if (llmProvider === 'anthropic') {
         llm = new ChatAnthropic({
           apiKey: openAIApiKey,
-          model: openAIModelName || 'claude-3-7-sonnet-latest',
+          model: openAIModelName || DEFAULT_CLAUDE_MODEL,
           temperature: DEFAULT_TEMPERATURE,
         });
         providerInfo = {
           ...providerInfo,
-          model: openAIModelName || 'claude-3-7-sonnet-latest',
+          model: openAIModelName || DEFAULT_CLAUDE_MODEL,
           keyPresent: !!openAIApiKey,
         };
       } else if (llmProvider === 'openrouter') {
-        const baseURL = this.options.openRouterBaseURL || 'https://openrouter.ai/api/v1';
+        const baseURL =
+          this.options.openRouterBaseURL || 'https://openrouter.ai/api/v1';
         const apiKey = this.options.openRouterApiKey || openAIApiKey;
-        const modelName = openAIModelName || 'anthropic/claude-3-haiku-20240307';
+        const modelName =
+          openAIModelName || 'anthropic/claude-3-haiku-20240307';
         llm = new ChatOpenAI({
           apiKey,
           model: modelName,
@@ -240,8 +456,12 @@ export class ConversationalAgent {
           configuration: {
             baseURL,
             defaultHeaders: {
-              'HTTP-Referer': process.env.OPENROUTER_REFERRER || 'https://hashgraphonline.com',
-              'X-Title': process.env.OPENROUTER_TITLE || 'Hashgraph Online Conversational Agent',
+              'HTTP-Referer':
+                process.env.OPENROUTER_REFERRER ||
+                'https://hashgraphonline.com',
+              'X-Title':
+                process.env.OPENROUTER_TITLE ||
+                'Hashgraph Online Conversational Agent',
             },
           },
         });
@@ -252,20 +472,20 @@ export class ConversationalAgent {
           keyPresent: !!apiKey,
         };
       } else {
-        const modelName = openAIModelName || 'gpt-4o-mini';
+        const modelName2 = openAIModelName || DEFAULT_OPENAI_MODEL;
         const isGPT5Model =
-          modelName.toLowerCase().includes('gpt-5') ||
-          modelName.toLowerCase().includes('gpt5');
+          modelName2.toLowerCase().includes('gpt-5') ||
+          modelName2.toLowerCase().includes('gpt5');
         llm = new ChatOpenAI({
           apiKey: openAIApiKey,
-          model: modelName,
+          model: modelName2,
           ...(isGPT5Model
             ? { temperature: 1 }
             : { temperature: DEFAULT_TEMPERATURE }),
         });
         providerInfo = {
           ...providerInfo,
-          model: modelName,
+          model: modelName2,
           keyPresent: !!openAIApiKey,
         };
       }
@@ -275,7 +495,11 @@ export class ConversationalAgent {
       this.logger.info('Preparing plugins...');
       const allPlugins = this.preparePlugins();
       this.logger.info('Creating agent config...');
-      const agentConfig = this.createAgentConfig(serverSigner, llm, allPlugins);
+      const agentConfig = this.createAgentConfig(
+        signer as ServerSigner,
+        llm,
+        allPlugins
+      );
 
       this.logger.info('Creating agent...');
       this.agent = createAgent(agentConfig);
@@ -472,8 +696,14 @@ export class ConversationalAgent {
    * @throws {Error} If required fields are missing
    */
   private validateOptions(accountId?: string, privateKey?: string): void {
-    if (!accountId || !privateKey) {
-      throw new Error('Account ID and private key are required');
+    const opMode = (this.options.operationalMode ||
+      DEFAULT_OPERATIONAL_MODE) as string;
+    const bytesMode = opMode !== 'autonomous';
+    if (!accountId) {
+      throw new Error('Account ID is required');
+    }
+    if (!privateKey && !bytesMode) {
+      throw new Error('Private key is required in autonomous mode');
     }
 
     if (typeof accountId !== 'string') {
@@ -482,15 +712,18 @@ export class ConversationalAgent {
       );
     }
 
-    if (typeof privateKey !== 'string') {
+    if (!bytesMode && typeof privateKey !== 'string') {
       throw new Error(
         `Private key must be a string, received ${typeof privateKey}: ${JSON.stringify(
           privateKey
         )}`
       );
     }
-
-    if (privateKey.length < 10) {
+    if (
+      !bytesMode &&
+      typeof privateKey === 'string' &&
+      privateKey.length < 10
+    ) {
       throw new Error('Private key appears to be invalid (too short)');
     }
   }
@@ -501,38 +734,46 @@ export class ConversationalAgent {
    * @returns Array of plugins to initialize with the agent
    */
   private preparePlugins(): BasePlugin[] {
-    const { additionalPlugins = [], enabledPlugins } = this.options;
+    const { additionalPlugins = [], enabledPlugins, disabledPlugins } = this.options;
 
-    const standardPlugins = [
+    const standardPlugins: BasePlugin[] = [
       this.hcs10Plugin,
       this.hcs2Plugin,
       this.inscribePlugin,
       this.hbarPlugin,
     ];
+    standardPlugins.push(this.webBrowserPlugin);
 
     const corePlugins = getAllHederaCorePlugins();
+    let pluginPool = [...standardPlugins, ...corePlugins];
 
     if (enabledPlugins) {
       const enabledSet = new Set(enabledPlugins);
-      const filteredPlugins = [...standardPlugins, ...corePlugins].filter(
-        (plugin) => enabledSet.has(plugin.id)
-      );
-      return [...filteredPlugins, ...additionalPlugins];
+      pluginPool = pluginPool.filter((plugin) => enabledSet.has(plugin.id));
+    }
+
+    if (disabledPlugins && disabledPlugins.length > 0) {
+      const disabledSet = new Set(disabledPlugins);
+      pluginPool = pluginPool.filter((plugin) => !disabledSet.has(plugin.id));
     }
 
-    return [...standardPlugins, ...corePlugins, ...additionalPlugins];
+    const additional = disabledPlugins && disabledPlugins.length > 0
+      ? additionalPlugins.filter((plugin) => !disabledPlugins.includes(plugin.id))
+      : additionalPlugins;
+
+    return [...pluginPool, ...additional];
   }
 
   /**
    * Creates the agent configuration object.
    *
-   * @param serverSigner - The server signer instance
+   * @param signer - The signer instance
    * @param llm - The language model instance
    * @param allPlugins - Array of plugins to use
    * @returns Configuration object for creating the agent
    */
   private createAgentConfig(
-    serverSigner: ServerSigner,
+    signer: ServerSigner,
     llm: ChatOpenAI | ChatAnthropic,
     allPlugins: BasePlugin[]
   ): Parameters<typeof createAgent>[0] {
@@ -550,7 +791,7 @@ export class ConversationalAgent {
 
     return {
       framework: 'langchain',
-      signer: serverSigner,
+      signer,
       execution: {
         mode: operationalMode === 'autonomous' ? 'direct' : 'bytes',
         operationalMode: operationalMode,
@@ -820,7 +1061,7 @@ export class ConversationalAgent {
       }
       if (typeof response === 'string') {
         const match = response.match(
-          /transaction[\s\w]*ID[\s:"]*([0-9a-fA-F@\.\-]+)/i
+          /transaction[\s\w]*ID[\s:"]*([0-9a-fA-F@._-]+)/i
         );
         return match ? match[1] : undefined;
       }
@@ -902,6 +1143,38 @@ export class ConversationalAgent {
     }
   }
 
+  /**
+   * Switch operational mode
+   */
+  switchMode(mode?: AgentOperationalMode): void {
+    if (this.agent?.switchMode) {
+      this.agent.switchMode(mode || 'autonomous');
+    }
+  }
+
+  /**
+   * Get usage statistics
+   */
+  getUsageStats(): unknown {
+    return this.agent?.getUsageStats?.() ?? {};
+  }
+
+  /**
+   * Clear usage statistics
+   */
+  clearUsageStats(): void {
+    if (this.agent?.clearUsageStats) {
+      this.agent.clearUsageStats();
+    }
+  }
+
+  /**
+   * Shutdown the agent
+   */
+  shutdown(): Promise<void> {
+    return this.agent?.shutdown?.() ?? Promise.resolve();
+  }
+
   private extractResponseText(response: unknown): string {
     if (typeof response === 'string') {
       return response;

package/src/core/tool-registry.ts

@@ -6,6 +6,13 @@ import {
   wrapToolWithFormValidation,
 } from '../langchain/form-validating-tool-wrapper';
 import { FormGenerator } from '../forms/form-generator';
+import {
+  fieldGuidanceRegistry,
+} from '../forms/field-guidance-registry';
+import type {
+  ToolFieldConfiguration as FG_ToolFieldConfiguration,
+  FieldGuidanceProvider as FG_FieldGuidanceProvider,
+} from '../forms/field-guidance-registry';
 import { isFormValidatable } from '@hashgraphonline/standards-agent-kit';
 
 /**
@@ -40,6 +47,8 @@ export interface ToolMetadata {
   dependencies: string[];
   schema: unknown;
   entityResolutionPreferences?: EntityResolutionPreferences;
+  fieldGuidance?: FG_ToolFieldConfiguration;
+  fieldGuidanceProvider?: FG_FieldGuidanceProvider;
 }
 
 /**
@@ -50,6 +59,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;
+  };
 }
 
 /**
@@ -188,9 +203,30 @@ export class ToolRegistry {
       metadata,
       wrapper,
       originalTool: tool,
+      options: {
+        priority: capabilities.priority,
+        capability: 'basic', // Default capability
+        enabled: true, // All tools are enabled by default
+        namespace: metadata.category,
+      },
     };
 
     this.tools.set(tool.name, entry);
+
+    try {
+      const metaFG = metadata.fieldGuidance as FG_ToolFieldConfiguration | undefined;
+      if (metaFG) {
+        fieldGuidanceRegistry.registerToolConfiguration(metaFG);
+      }
+      const provider = metadata.fieldGuidanceProvider as FG_FieldGuidanceProvider | undefined;
+      if (provider) {
+        const pattern = metaFG?.toolPattern ?? tool.name;
+        fieldGuidanceRegistry.registerToolProvider(pattern, provider, {
+          id: `${tool.name}:field-guidance-provider`,
+          priority: 0,
+        });
+      }
+    } catch {}
   }
 
   /**
@@ -279,6 +315,55 @@ export class ToolRegistry {
     return Array.from(this.tools.keys());
   }
 
+  /**
+   * Get tools by priority
+   */
+  getToolsByPriority(priority: ToolCapabilities['priority']): ToolRegistryEntry[] {
+    return this.getToolsByCapability('priority', priority);
+  }
+
+  /**
+   * Get enabled tools (all tools are considered enabled by default)
+   */
+  getEnabledTools(): ToolRegistryEntry[] {
+    return this.getAllRegistryEntries();
+  }
+
+  /**
+   * Get tools by namespace/category
+   */
+  getToolsByNamespace(namespace?: string): ToolRegistryEntry[] {
+    if (!namespace) {
+      return this.getAllRegistryEntries();
+    }
+    return this.getToolsByQuery({ category: namespace as ToolMetadata['category'] });
+  }
+
+  /**
+   * Check if registry has capability
+   */
+  hasCapability(capability: keyof ToolCapabilities): boolean {
+    for (const entry of this.tools.values()) {
+      if (entry.metadata.capabilities[capability]) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Update tool options (metadata)
+   */
+  updateToolOptions(name: string, options: Partial<ToolMetadata>): boolean {
+    const entry = this.tools.get(name);
+    if (!entry) {
+      return false;
+    }
+
+    entry.metadata = { ...entry.metadata, ...options };
+    return true;
+  }
+
   /**
    * Check if a tool is registered
    */