@hashgraphonline/conversational-agent 0.1.215 → 0.1.217

package/src/langchain-agent.ts

@@ -1,7 +1,6 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import type { StructuredTool } from '@langchain/core/tools';
 import { createOpenAIToolsAgent } from 'langchain/agents';
-import { z } from 'zod';
 import { FormAwareAgentExecutor } from './langchain/FormAwareAgentExecutor';
 import {
   ChatPromptTemplate,
@@ -25,10 +24,53 @@ import {
 import { MCPClientManager } from './mcp/MCPClientManager';
 import { convertMCPToolToLangChain } from './mcp/adapters/langchain';
 import { SmartMemoryManager } from './memory/SmartMemoryManager';
-import type { MCPConnectionStatus } from './mcp/types';
+import type { MCPConnectionStatus, MCPServerConfig } from './mcp/types';
+import { ResponseFormatter } from './utils/ResponseFormatter';
 import type { FormSubmission } from './forms/types';
-import { FormGenerator } from './forms/form-generator';
-import { wrapToolWithFormValidation } from './langchain/FormValidatingToolWrapper';
+import type { ToolRegistrationOptions } from './core/ToolRegistry';
+import { HumanMessage, AIMessage } from '@langchain/core/messages';
+import { ToolRegistry } from './core/ToolRegistry';
+import {
+  ExecutionPipeline,
+  SessionContext,
+} from './execution/ExecutionPipeline';
+import { FormEngine } from './forms/FormEngine';
+import type { ChainValues } from '@langchain/core/utils/types';
+
+interface RenderConfigSchema {
+  _renderConfig?: Record<string, unknown>;
+}
+
+interface ToolExecutionData {
+  type: string;
+  formId?: string;
+  parameters?: Record<string, unknown>;
+}
+
+interface IntermediateStep {
+  action?: {
+    tool?: string;
+    toolInput?: Record<string, unknown>;
+  };
+  observation?: unknown;
+}
+interface RenderConfigSchema {
+  _renderConfig?: Record<string, unknown>;
+}
+
+interface ToolExecutionData {
+  type: string;
+  formId?: string;
+  parameters?: Record<string, unknown>;
+}
+
+interface IntermediateStep {
+  action?: {
+    tool?: string;
+    toolInput?: Record<string, unknown>;
+  };
+  observation?: unknown;
+}
 
 export class LangChainAgent extends BaseAgent {
   private executor: FormAwareAgentExecutor | undefined;
@@ -36,11 +78,505 @@ export class LangChainAgent extends BaseAgent {
   private mcpManager?: MCPClientManager;
   private smartMemory: SmartMemoryManager | undefined;
   private mcpConnectionStatus: Map<string, MCPConnectionStatus> = new Map();
+  private toolRegistry!: ToolRegistry;
+  private executionPipeline!: ExecutionPipeline;
+  private formEngine!: FormEngine;
+
+  /**
+   * Get inscription tool by capability instead of hardcoded name
+   */
+  private getInscriptionTool(): StructuredTool | null {
+    const criticalTools = this.toolRegistry.getToolsByCapability(
+      'priority',
+      'critical'
+    );
+
+    for (const entry of criticalTools) {
+      const tool = entry.tool;
+      const name = tool.name.toLowerCase();
+      const desc = tool.description?.toLowerCase() || '';
+
+      if (
+        name.includes('inscribe') ||
+        name.includes('hashinal') ||
+        desc.includes('inscribe') ||
+        desc.includes('hashinal')
+      ) {
+        return tool;
+      }
+    }
+
+    const allTools = this.toolRegistry.getAllRegistryEntries();
+    for (const entry of allTools) {
+      const tool = entry.tool;
+      const name = tool.name.toLowerCase();
+      const desc = tool.description?.toLowerCase() || '';
+
+      if (
+        name.includes('inscribe') ||
+        name.includes('hashinal') ||
+        desc.includes('inscribe') ||
+        desc.includes('hashinal')
+      ) {
+        return tool;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Get a tool by name from the registry with type safety
+   */
+  private getTool(name: string): StructuredTool | null {
+    const entry = this.toolRegistry.getTool(name);
+    return entry ? entry.tool : null;
+  }
+
+  /**
+   * Execute a tool directly with parameters, optionally using ExecutionPipeline
+   */
+  private async executeToolDirect(
+    toolName: string,
+    parameters: Record<string, unknown>,
+    useExecutionPipeline = false
+  ): Promise<string> {
+    if (useExecutionPipeline && this.executionPipeline && this.smartMemory) {
+      const sessionContext: SessionContext = {
+        sessionId: `session-${Date.now()}`,
+        timestamp: Date.now(),
+      };
+
+      const result = await this.executionPipeline.execute(
+        toolName,
+        parameters,
+        sessionContext
+      );
+
+      if (!result.success) {
+        throw new Error(result.error || 'Pipeline execution failed');
+      }
+
+      return result.output;
+    }
+
+    const entry = this.toolRegistry.getTool(toolName);
+    if (!entry) {
+      throw new Error(`Tool not found: ${toolName}`);
+    }
+
+    const mergedArgs = { ...parameters, renderForm: false };
+
+    if (entry.wrapper) {
+      const maybeWrapper = entry.tool as unknown as {
+        originalTool?: {
+          call?: (a: Record<string, unknown>) => Promise<string>;
+        };
+      };
+      if (maybeWrapper.originalTool?.call) {
+        return await maybeWrapper.originalTool.call(mergedArgs);
+      }
+    }
+
+    return await entry.tool.call(mergedArgs);
+  }
+
+  /**
+   * Create a standard ChatResponse from tool output
+   */
+  private createToolResponse(toolOutput: string): ChatResponse {
+    return {
+      output: toolOutput,
+      message: toolOutput,
+      notes: [],
+    };
+  }
+
+  /**
+   * Handle TOOL_EXECUTION format messages
+   */
+  private async handleToolExecution(
+    message: string,
+    context?: ConversationContext
+  ): Promise<ChatResponse | null> {
+    let isToolExecution = false;
+    let toolExecutionData: ToolExecutionData | null = null;
+
+    try {
+      if (message.includes('TOOL_EXECUTION')) {
+        const parsed = JSON.parse(message);
+        if (parsed.type === 'TOOL_EXECUTION') {
+          isToolExecution = true;
+          toolExecutionData = parsed;
+        }
+      }
+    } catch {}
+
+    if (!isToolExecution || !toolExecutionData?.formId) {
+      return null;
+    }
+
+    try {
+      const params = (toolExecutionData.parameters || {}) as Record<
+        string,
+        unknown
+      >;
+      const toolName = (toolExecutionData as unknown as { toolName?: string })
+        .toolName;
+
+      if (toolName) {
+        const toolOutput = await this.executeToolDirect(toolName, params);
+        return this.createToolResponse(toolOutput);
+      }
+    } catch {}
+
+    const formSubmission: FormSubmission = {
+      formId: toolExecutionData.formId,
+      toolName:
+        (toolExecutionData as unknown as { toolName?: string }).toolName || '',
+      parameters: toolExecutionData.parameters || {},
+      timestamp: Date.now(),
+    };
+
+    if (
+      this.executor &&
+      'processFormSubmission' in this.executor &&
+      typeof this.executor.processFormSubmission === 'function'
+    ) {
+      return this.processFormSubmission(formSubmission, context);
+    }
+
+    return null;
+  }
+
+  /**
+   * Handle direct tool execution commands
+   */
+  private async handleDirectToolExecution(
+    message: string
+  ): Promise<ChatResponse | null> {
+    if (
+      typeof message !== 'string' ||
+      !message.includes('Please execute the following tool:')
+    ) {
+      return null;
+    }
+
+    try {
+      const toolLineMatch = message.match(/Tool:\s*(.+)/);
+      const argsLineIndex = message.indexOf('Arguments:');
+
+      if (toolLineMatch && argsLineIndex !== -1) {
+        const toolName = toolLineMatch[1].trim();
+        const argsText = message
+          .slice(argsLineIndex + 'Arguments:'.length)
+          .trim();
+
+        let args: Record<string, unknown> = {};
+        try {
+          args = JSON.parse(argsText);
+        } catch {}
+
+        const toolOutput = await this.executeToolDirect(toolName, args);
+        return this.createToolResponse(toolOutput);
+      }
+    } catch {}
+
+    return null;
+  }
+
+  /**
+   * Handle JSON format tool calls and form submissions
+   */
+  private async handleJsonToolCalls(
+    message: string,
+    context?: ConversationContext
+  ): Promise<ChatResponse | null> {
+    if (typeof message !== 'string') {
+      return null;
+    }
+
+    try {
+      const trimmed = message.trim();
+      if (
+        !(trimmed.startsWith('{') && trimmed.endsWith('}')) &&
+        !(trimmed.startsWith('[') && trimmed.endsWith(']'))
+      ) {
+        return null;
+      }
+
+      const obj = JSON.parse(trimmed) as Record<string, unknown>;
+      const formId = obj['formId'] as string | undefined;
+      const toolName = (obj['toolName'] as string) || '';
+      const parameters = (obj['parameters'] as Record<string, unknown>) || {};
+
+      if (
+        formId &&
+        this.executor &&
+        'processFormSubmission' in this.executor &&
+        typeof this.executor.processFormSubmission === 'function'
+      ) {
+        return this.processFormSubmission(
+          { formId, toolName, parameters, timestamp: Date.now() },
+          context
+        );
+      }
+
+      if (toolName) {
+        const toolOutput = await this.executeToolDirect(toolName, parameters);
+        return this.createToolResponse(toolOutput);
+      }
+    } catch {}
+
+    return null;
+  }
+
+  /**
+   * Handle content-ref messages for inscription tools
+   */
+  private async handleContentRefMessages(
+    message: string
+  ): Promise<ChatResponse | null> {
+    if (typeof message !== 'string' || !message.includes('content-ref:')) {
+      return null;
+    }
+
+    try {
+      const tool = this.getInscriptionTool();
+      if (!tool) {
+        return null;
+      }
+
+      const idMatch =
+        message.match(/content-ref:([A-Za-z0-9_\-]+)/i) ||
+        message.match(/content-ref:([^\s)]+)/i);
+      const contentRef =
+        idMatch && idMatch[1]
+          ? `content-ref:${idMatch[1]}`
+          : message.match(/content-ref:[^\s)]+/i)?.[0] || undefined;
+
+      const args = contentRef
+        ? ({ contentRef, renderForm: true, withHashLinkBlocks: true } as Record<string, unknown>)
+        : ({ renderForm: true, withHashLinkBlocks: true } as Record<string, unknown>);
+
+      const toolOutput = await tool.call(args);
+      let parsed: Record<string, unknown> | undefined;
+
+      try {
+        parsed =
+          typeof toolOutput === 'string'
+            ? (JSON.parse(toolOutput) as Record<string, unknown>)
+            : (toolOutput as unknown as Record<string, unknown>);
+      } catch {}
+
+      if (parsed && parsed['requiresForm'] && parsed['formMessage']) {
+        const pending = new Map<
+          string,
+          {
+            toolName: string;
+            originalInput: Record<string, unknown>;
+            originalToolInput?: Record<string, unknown>;
+            schema: unknown;
+          }
+        >();
+
+        const originalInput = {
+          input: message,
+          chat_history: this.smartMemory!.getMessages(),
+        } as Record<string, unknown>;
+
+        const formMessage = parsed['formMessage'] as { id: string };
+        pending.set(formMessage.id, {
+          toolName: tool.name,
+          originalInput,
+          originalToolInput: args,
+          schema: null,
+        });
+
+        const maybeRestore = this.executor as unknown as {
+          restorePendingForms?: (p: Map<string, unknown>) => void;
+        };
+
+        if (typeof maybeRestore.restorePendingForms === 'function') {
+          (
+            maybeRestore.restorePendingForms as unknown as (
+              p: Map<string, unknown>
+            ) => void
+          )(pending as unknown as Map<string, unknown>);
+        }
+
+        const outputMsg =
+          (parsed['message'] as string) ||
+          'Please complete the form to continue.';
+
+        return {
+          output: outputMsg,
+          message: outputMsg,
+          notes: [],
+          requiresForm: true,
+          formMessage: formMessage as unknown as ChatResponse['formMessage'],
+        } as ChatResponse;
+      }
+    } catch {}
+
+    return null;
+  }
+
+  /**
+   * Process executor result and format response
+   */
+  private async processExecutorResult(
+    result: ChainValues
+  ): Promise<ChatResponse> {
+    let outputStr = '';
+    if (typeof result.output === 'string') {
+      outputStr = result.output;
+    } else if (result.output) {
+      try {
+        outputStr = JSON.stringify(result.output);
+      } catch {
+        outputStr = String(result.output);
+      }
+    }
+
+    let response: ChatResponse = {
+      output: outputStr,
+      message: outputStr,
+      notes: [],
+      intermediateSteps: result.intermediateSteps,
+    };
+
+    if (result.requiresForm && result.formMessage) {
+      response.formMessage = result.formMessage;
+      response.requiresForm = true;
+    }
+
+    if (result.intermediateSteps && Array.isArray(result.intermediateSteps)) {
+      const toolCalls = result.intermediateSteps.map(
+        (step: IntermediateStep, index: number) => ({
+          id: `call_${index}`,
+          name: step.action?.tool || 'unknown',
+          args: step.action?.toolInput || {},
+          output:
+            typeof step.observation === 'string'
+              ? step.observation
+              : JSON.stringify(step.observation),
+        })
+      );
+
+      if (toolCalls.length > 0) {
+        response.tool_calls = toolCalls;
+      }
+    }
+
+    const parsedSteps = result?.intermediateSteps?.[0]?.observation;
+    if (
+      parsedSteps &&
+      typeof parsedSteps === 'string' &&
+      this.isJSON(parsedSteps)
+    ) {
+      try {
+        const parsed = JSON.parse(parsedSteps);
+
+        if (ResponseFormatter.isInscriptionResponse(parsed)) {
+          const formattedMessage =
+            ResponseFormatter.formatInscriptionResponse(parsed);
+          response.output = formattedMessage;
+          response.message = formattedMessage;
+
+          if (parsed.inscription) {
+            response.inscription = parsed.inscription;
+          }
+          if (parsed.metadata) {
+            response.metadata = {
+              ...response.metadata,
+              ...parsed.metadata,
+            };
+          }
+        } else {
+          response = { ...response, ...parsed };
+        }
+
+        const blockMetadata = this.processHashLinkBlocks(parsed);
+        if (blockMetadata.hashLinkBlock) {
+          response.metadata = {
+            ...response.metadata,
+            ...blockMetadata,
+          };
+        }
+      } catch (error) {
+        this.logger.error('Error parsing intermediate steps:', error);
+      }
+    }
+
+    if (!response.output || response.output.trim() === '') {
+      response.output = 'Agent action complete.';
+    }
+
+    if (response.output) {
+      this.smartMemory!.addMessage(new AIMessage(response.output));
+    }
+
+    if (this.tokenTracker) {
+      const tokenUsage = this.tokenTracker.getLatestTokenUsage();
+      if (tokenUsage) {
+        response.tokenUsage = tokenUsage;
+        response.cost = calculateTokenCostSync(tokenUsage);
+      }
+    }
+
+    const finalMemoryStats = this.smartMemory!.getMemoryStats();
+    response.metadata = {
+      ...response.metadata,
+      memoryStats: {
+        activeMessages: finalMemoryStats.totalActiveMessages,
+        tokenUsage: finalMemoryStats.currentTokenCount,
+        maxTokens: finalMemoryStats.maxTokens,
+        usagePercentage: finalMemoryStats.usagePercentage,
+      },
+    };
+
+    this.logger.info('LangChainAgent.chat returning response:', response);
+    return response;
+  }
+
+  /**
+   * Normalize context messages into LangChain message instances and load into memory
+   */
+  private loadContextMessages(context?: ConversationContext): void {
+    if (!this.smartMemory) {
+      return;
+    }
+    if (!context?.messages || context.messages.length === 0) {
+      return;
+    }
+    this.smartMemory.clear();
+    const rawMessages = context.messages as unknown[];
+    for (const msg of rawMessages) {
+      if (msg instanceof HumanMessage || msg instanceof AIMessage) {
+        this.smartMemory.addMessage(msg);
+        continue;
+      }
+      if (
+        msg &&
+        typeof msg === 'object' &&
+        'content' in (msg as Record<string, unknown>) &&
+        'type' in (msg as Record<string, unknown>)
+      ) {
+        const content = String((msg as { content: unknown }).content);
+        const type = String((msg as { type: unknown }).type);
+        if (type === 'human') {
+          this.smartMemory.addMessage(new HumanMessage(content));
+        } else {
+          this.smartMemory.addMessage(new AIMessage(content));
+        }
+      }
+    }
+  }
 
   async boot(): Promise<void> {
-    console.log('🚨🚨🚨 LANGCHAIN AGENT BOOT METHOD CALLED 🚨🚨🚨');
     this.logger.info('🚨🚨🚨 LANGCHAIN AGENT BOOT METHOD CALLED 🚨🚨🚨');
-    
+
     if (this.initialized) {
       this.logger.warn('Agent already initialized');
       return;
@@ -56,77 +592,100 @@ export class LangChainAgent extends BaseAgent {
         'gpt-4o-mini';
       this.tokenTracker = new TokenUsageCallbackHandler(modelName);
 
+      this.toolRegistry = new ToolRegistry(this.logger);
+
       const allTools = this.agentKit.getAggregatedLangChainTools();
-      this.logger.info('=== TOOL WRAPPING DEBUG START ===');
-      this.logger.info('All tools from agentKit:', allTools.map(t => t.name));
-      
+      this.logger.info('=== TOOL REGISTRATION START ===');
+      this.logger.info(
+        'All tools from agentKit:',
+        allTools.map((t) => t.name)
+      );
+
       const filteredTools = this.filterTools(allTools);
-      this.logger.info('All filtered tools:', filteredTools.map(t => t.name));
-      
-      const formGenerator = new FormGenerator();
-      
-      this.tools = filteredTools.map(tool => {
-        this.logger.info(`Processing tool: ${tool.name}`);
-        console.log(`🔧 Processing tool: ${tool.name}`);
-        
-        if (tool.name === 'inscribeHashinal') {
-          this.logger.info(`Debug InscribeHashinalTool schema:`, {
+      this.logger.info(
+        'Filtered tools for registration:',
+        filteredTools.map((t) => t.name)
+      );
+
+      for (const tool of filteredTools) {
+        this.logger.info(`🔧 Registering tool: ${tool.name}`);
+
+        const options: ToolRegistrationOptions = {};
+
+        const name = tool.name.toLowerCase();
+        const desc = tool.description?.toLowerCase() || '';
+
+        if (
+          name.includes('inscribe') ||
+          name.includes('hashinal') ||
+          desc.includes('inscribe') ||
+          desc.includes('hashinal')
+        ) {
+          options.forceWrapper = true;
+          options.metadata = {
+            category: 'core' as const,
+            version: '1.0.0',
+            dependencies: [],
+          };
+
+          this.logger.info(`🎯 CRITICAL TOOL DEBUG - ${tool.name} schema:`, {
             hasSchema: !!tool.schema,
             schemaType: tool.schema?.constructor?.name,
-            hasRenderConfig: !!(tool.schema as any)?._renderConfig,
-            renderConfig: (tool.schema as any)?._renderConfig
+            hasRenderConfig: !!(tool.schema as RenderConfigSchema)
+              ?._renderConfig,
+            renderConfig: (tool.schema as RenderConfigSchema)?._renderConfig,
           });
         }
-        
-        // Force schema getter to be called to ensure _renderConfig is set
-        const schema = tool.schema;
-        let hasRenderConfig = (schema as any)?._renderConfig;
-        
-        // Special handling for InscribeHashinalTool
-        if (tool.name === 'inscribeHashinal') {
-          this.logger.info(`InscribeHashinalTool detected`, {
-            hasRenderConfig: !!hasRenderConfig,
-            schemaType: schema?.constructor?.name
-          });
-          
-          if (!hasRenderConfig) {
-            // Ensure render config is set for form generation
-            (schema as any)._renderConfig = {
-              fieldType: 'object',
-              ui: {
-                label: 'Inscribe Hashinal NFT',
-                description: 'Create a Hashinal inscription for NFT minting'
-              }
-            };
-            hasRenderConfig = true;
-            this.logger.info(`Added render config to InscribeHashinalTool for form generation`);
+
+        this.toolRegistry.registerTool(tool, options);
+      }
+
+      this.tools = this.toolRegistry.getAllTools();
+
+      this.logger.info(`🚀 TOOLS REGISTERED: ${this.tools.length} tools`);
+
+      const stats = this.toolRegistry.getStatistics();
+      this.logger.info('📊 Tool Registry Statistics:', {
+        total: stats.totalTools,
+        wrapped: stats.wrappedTools,
+        unwrapped: stats.unwrappedTools,
+        categories: stats.categoryCounts,
+        priorities: stats.priorityCounts,
+      });
+
+      const inscriptionTool = this.getInscriptionTool();
+      if (inscriptionTool) {
+        const entry = this.toolRegistry.getTool(inscriptionTool.name);
+        if (entry) {
+          this.logger.info(
+            `🔒 FINAL SECURITY CHECK - ${inscriptionTool.name} tool type: ${entry.tool.constructor.name}`
+          );
+          if (entry.tool.constructor.name !== 'FormValidatingToolWrapper') {
+            this.logger.error(
+              `🚨 SECURITY BREACH: ${inscriptionTool.name} tool is NOT wrapped!`
+            );
+            throw new Error(
+              `Critical security failure: ${inscriptionTool.name} tool bypassed FormValidatingToolWrapper`
+            );
+          } else {
+            this.logger.info(
+              `✅ SECURITY VALIDATED: ${inscriptionTool.name} tool is properly wrapped`
+            );
           }
         }
-        
-        // Check if schema is ZodObject or behaves like one (including ZodSchemaWithRender)
-        const isZodObjectLike = (schema: any): boolean => {
-          if (!schema || typeof schema !== 'object') {
-            return false;
-          }
-          return (
-            schema instanceof z.ZodObject || 
-            schema._def?.typeName === 'ZodObject' ||
-            ('shape' in schema && typeof schema.shape === 'object')
-          );
-        };
+      }
 
-        if (hasRenderConfig && isZodObjectLike(tool.schema)) {
-          this.logger.info(`Wrapping tool ${tool.name} with form validation`);
-          return wrapToolWithFormValidation(tool as StructuredTool<z.ZodObject<z.ZodRawShape, z.UnknownKeysParam, z.ZodTypeAny>>, formGenerator, {
-            requireAllFields: false,
-            skipFields: ['metaOptions']
-          });
-        }
-        return tool;
-      });
-      
-      console.log(`🚀 TOOLS ASSIGNED: ${this.tools.length} tools`);
-      this.logger.info(`🚀 TOOLS ASSIGNED: ${this.tools.length} tools`);
+      const toolNames = this.toolRegistry.getToolNames();
+      const uniqueNames = new Set(toolNames);
+      if (toolNames.length !== uniqueNames.size) {
+        this.logger.error('DUPLICATE TOOL NAMES DETECTED in registry!');
+        const duplicates = toolNames.filter(
+          (name, index) => toolNames.indexOf(name) !== index
+        );
+        throw new Error(
+          `Duplicate tool names detected: ${duplicates.join(', ')}`
+        );
+      }
 
       if (this.config.mcp?.servers && this.config.mcp.servers.length > 0) {
         if (this.config.mcp.autoConnect !== false) {
@@ -153,6 +712,15 @@ export class LangChainAgent extends BaseAgent {
         reserveTokens: 10000,
       });
 
+      this.formEngine = new FormEngine(this.logger);
+
+      this.executionPipeline = new ExecutionPipeline(
+        this.toolRegistry,
+        this.formEngine,
+        this.smartMemory,
+        this.logger
+      );
+
       this.systemMessage = this.buildSystemPrompt();
 
       this.smartMemory.setSystemPrompt(this.systemMessage);
@@ -160,7 +728,7 @@ export class LangChainAgent extends BaseAgent {
       await this.createExecutor();
 
       this.initialized = true;
-      this.logger.info('LangChain Hedera agent initialized');
+      this.logger.info('LangChain Hedera agent initialized with ToolRegistry');
     } catch (error) {
       this.logger.error('Failed to initialize agent:', error);
       throw error;
@@ -176,20 +744,35 @@ export class LangChainAgent extends BaseAgent {
     }
 
     try {
-      this.logger.info('LangChainAgent.chat called with:', {
+      const toolExecutionResult = await this.handleToolExecution(
         message,
-        contextLength: context?.messages?.length || 0,
-      });
+        context
+      );
+      if (toolExecutionResult) {
+        return toolExecutionResult;
+      }
+
+      const directToolResult = await this.handleDirectToolExecution(message);
+      if (directToolResult) {
+        return directToolResult;
+      }
 
-      if (context?.messages && context.messages.length > 0) {
-        this.smartMemory.clear();
+      const jsonToolResult = await this.handleJsonToolCalls(message, context);
+      if (jsonToolResult) {
+        return jsonToolResult;
+      }
 
-        for (const msg of context.messages) {
-          this.smartMemory.addMessage(msg);
-        }
+      const contentRefResult = await this.handleContentRefMessages(message);
+      if (contentRefResult) {
+        return contentRefResult;
       }
 
-      const { HumanMessage } = await import('@langchain/core/messages');
+      this.logger.info('LangChainAgent.chat called with:', {
+        message,
+        contextLength: context?.messages?.length || 0,
+      });
+
+      this.loadContextMessages(context);
       this.smartMemory.addMessage(new HumanMessage(message));
 
       const memoryStats = this.smartMemory.getMemoryStats();
@@ -208,86 +791,7 @@ export class LangChainAgent extends BaseAgent {
 
       this.logger.info('LangChainAgent executor result:', result);
 
-      const outputStr = typeof result.output === 'string' 
-        ? result.output 
-        : result.output 
-          ? JSON.stringify(result.output)
-          : '';
-
-      let response: ChatResponse = {
-        output: outputStr,
-        message: outputStr,
-        notes: [],
-        intermediateSteps: result.intermediateSteps,
-      };
-
-      if (result.requiresForm && result.formMessage) {
-        response.formMessage = result.formMessage;
-        response.requiresForm = true;
-      }
-
-      if (result.intermediateSteps && Array.isArray(result.intermediateSteps)) {
-        const toolCalls = result.intermediateSteps.map(
-          (step: any, index: number) => ({
-            id: `call_${index}`,
-            name: step.action?.tool || 'unknown',
-            args: step.action?.toolInput || {},
-            output:
-              typeof step.observation === 'string'
-                ? step.observation
-                : JSON.stringify(step.observation),
-          })
-        );
-
-        if (toolCalls.length > 0) {
-          response.tool_calls = toolCalls;
-        }
-      }
-
-      const parsedSteps = result?.intermediateSteps?.[0]?.observation;
-      if (
-        parsedSteps &&
-        typeof parsedSteps === 'string' &&
-        this.isJSON(parsedSteps)
-      ) {
-        try {
-          const parsed = JSON.parse(parsedSteps);
-          response = { ...response, ...parsed };
-        } catch (error) {
-          this.logger.error('Error parsing intermediate steps:', error);
-        }
-      }
-
-      if (!response.output || response.output.trim() === '') {
-        response.output = 'Agent action complete.';
-      }
-
-      if (response.output) {
-        const { AIMessage } = await import('@langchain/core/messages');
-        this.smartMemory.addMessage(new AIMessage(response.output));
-      }
-
-      if (this.tokenTracker) {
-        const tokenUsage = this.tokenTracker.getLatestTokenUsage();
-        if (tokenUsage) {
-          response.tokenUsage = tokenUsage;
-          response.cost = calculateTokenCostSync(tokenUsage);
-        }
-      }
-
-      const finalMemoryStats = this.smartMemory.getMemoryStats();
-      response.metadata = {
-        ...response.metadata,
-        memoryStats: {
-          activeMessages: finalMemoryStats.totalActiveMessages,
-          tokenUsage: finalMemoryStats.currentTokenCount,
-          maxTokens: finalMemoryStats.maxTokens,
-          usagePercentage: finalMemoryStats.usagePercentage,
-        },
-      };
-
-      this.logger.info('LangChainAgent.chat returning response:', response);
-      return response;
+      return this.processExecutorResult(result);
     } catch (error) {
       this.logger.error('LangChainAgent.chat error:', error);
       return this.handleError(error);
@@ -304,6 +808,10 @@ export class LangChainAgent extends BaseAgent {
       this.smartMemory = undefined;
     }
 
+    if (this.toolRegistry) {
+      this.toolRegistry.clear();
+    }
+
     this.executor = undefined;
     this.agentKit = undefined;
     this.tools = [];
@@ -370,38 +878,118 @@ export class LangChainAgent extends BaseAgent {
     submission: FormSubmission,
     context?: ConversationContext
   ): Promise<ChatResponse> {
+    this.logger.info('🔥 LangChainAgent.processFormSubmission START');
+    
     if (!this.initialized || !this.executor || !this.smartMemory) {
+      this.logger.error('🔥 LangChainAgent.processFormSubmission - Agent not initialized');
       throw new Error('Agent not initialized. Call boot() first.');
     }
 
+    this.logger.info('🔥 LangChainAgent.processFormSubmission - After initialization check');
+
     try {
+      this.logger.info('🔥 LangChainAgent.processFormSubmission - About to log submission info');
+      
       this.logger.info('Processing form submission:', {
         formId: submission.formId,
-        dataKeys: Object.keys(submission.data)
+        toolName: submission.toolName,
+        parameterKeys: Object.keys(submission.parameters || {}),
+        hasParameters: !!submission.parameters,
+        parametersType: typeof submission.parameters,
+        parametersIsNull: submission.parameters === null,
+        parametersIsUndefined: submission.parameters === undefined,
+        hasContext: !!submission.context,
       });
 
-      if (context?.messages && context.messages.length > 0) {
-        this.smartMemory.clear();
-        for (const msg of context.messages) {
-          this.smartMemory.addMessage(msg);
-        }
+      this.logger.info('🔥 LangChainAgent.processFormSubmission - After submission info logged');
+
+      if (!submission.parameters || typeof submission.parameters !== 'object') {
+        this.logger.error('Invalid form submission parameters:', {
+          parameters: submission.parameters,
+          type: typeof submission.parameters,
+        });
+        const errorInfo = JSON.stringify(submission, null, 2);
+        return this.handleError(
+          new Error(`Invalid form submission parameters: ${errorInfo}`)
+        );
       }
 
-      const result = await this.executor.processFormSubmission(submission);
+      this.logger.info('🔥 LangChainAgent.processFormSubmission - Parameters validated');
+
+      this.loadContextMessages(context);
 
-      const outputMessage = typeof result.output === 'string' 
-        ? result.output 
-        : result.output 
-          ? JSON.stringify(result.output)
-          : 'Form processed successfully.';
+      this.logger.info('🔥 LangChainAgent.processFormSubmission - Context loaded');
+
+      const safeSubmission = {
+        ...submission,
+        parameters: submission.parameters || {},
+      };
+
+      this.logger.info('🔥 LangChainAgent.processFormSubmission - Safe submission created');
+
+      this.logger.info('About to call executor.processFormSubmission with:', {
+        formId: safeSubmission.formId,
+        toolName: safeSubmission.toolName,
+        parameterKeys: Object.keys(safeSubmission.parameters),
+        parameterCount: Object.keys(safeSubmission.parameters).length,
+      });
+
+      const result = await this.executor.processFormSubmission(safeSubmission);
+      
+      this.logger.info('🔍 DEBUG: Raw result from FormAwareAgentExecutor:', {
+        hasResult: !!result,
+        resultKeys: result ? Object.keys(result) : [],
+        hasMetadata: !!result?.metadata,
+        metadataKeys: result?.metadata ? Object.keys(result.metadata) : [],
+        hasHashLinkBlock: !!(result?.metadata as any)?.hashLinkBlock,
+        hashLinkBlockContent: (result?.metadata as any)?.hashLinkBlock
+      });
+      
+      if (result?.metadata) {
+        this.logger.info('🔍 DEBUG: Full metadata from executor:', JSON.stringify(result.metadata));
+      }
+      
+      const preservedMetadata = result?.metadata ? { ...result.metadata } : {};
+
+      this.logger.info('Executor processFormSubmission result:', {
+        hasResult: !!result,
+        hasOutput: !!result.output,
+        hasError: !!result.error,
+        hasMetadata: !!result.metadata,
+        outputType: typeof result.output,
+      });
+
+      let outputMessage = 'Form processed successfully.';
+      if (typeof result.output === 'string') {
+        outputMessage = result.output;
+      } else if (result.output) {
+        try {
+          outputMessage = JSON.stringify(result.output);
+        } catch {
+          outputMessage = String(result.output);
+        }
+      }
 
       let response: ChatResponse = {
         output: outputMessage,
         message: outputMessage,
         notes: [],
-        intermediateSteps: result.intermediateSteps as any
+        intermediateSteps: result.intermediateSteps as IntermediateStep[],
       };
 
+      if (result.metadata) {
+        response.metadata = {
+          ...response.metadata,
+          ...result.metadata
+        };
+        this.logger.info('🔍 DEBUG: Metadata after merge from result:', {
+          hasMetadata: !!response.metadata,
+          metadataKeys: response.metadata ? Object.keys(response.metadata) : [],
+          hasHashLinkBlock: !!(response.metadata as any)?.hashLinkBlock,
+          hashLinkBlockContent: (response.metadata as any)?.hashLinkBlock
+        });
+      }
+
       if (result.requiresForm && result.formMessage) {
         response.formMessage = result.formMessage;
         response.requiresForm = true;
@@ -409,17 +997,25 @@ export class LangChainAgent extends BaseAgent {
 
       if (result.intermediateSteps && Array.isArray(result.intermediateSteps)) {
         const toolCalls = result.intermediateSteps.map(
-          (step: any, index: number) => ({
-            id: `call_${index}`,
-            name: step.action?.tool || 'unknown',
-            args: step.action?.toolInput || {},
-            output:
-              typeof step.observation === 'string'
-                ? step.observation
-                : JSON.stringify(step.observation),
-          })
+          (step: IntermediateStep, index: number) => {
+            const name = step?.action?.tool || 'unknown';
+            const args = step?.action?.toolInput || {};
+            const obs = step?.observation;
+            let output = '';
+            if (typeof obs === 'string') {
+              output = obs;
+            } else if (obs && typeof obs === 'object') {
+              try {
+                output = JSON.stringify(obs);
+              } catch {
+                output = String(obs);
+              }
+            } else if (obs !== undefined) {
+              output = String(obs);
+            }
+            return { id: `call_${index}`, name, args, output };
+          }
         );
-
         if (toolCalls.length > 0) {
           response.tool_calls = toolCalls;
         }
@@ -434,13 +1030,20 @@ export class LangChainAgent extends BaseAgent {
         try {
           const parsed = JSON.parse(parsedSteps);
           response = { ...response, ...parsed };
+
+          const blockMetadata = this.processHashLinkBlocks(parsed);
+          if (blockMetadata.hashLinkBlock) {
+            response.metadata = {
+              ...response.metadata,
+              ...blockMetadata,
+            };
+          }
         } catch (error) {
           this.logger.error('Error parsing intermediate steps:', error);
         }
       }
 
       if (response.output) {
-        const { AIMessage } = await import('@langchain/core/messages');
         this.smartMemory.addMessage(new AIMessage(response.output));
       }
 
@@ -453,7 +1056,14 @@ export class LangChainAgent extends BaseAgent {
       }
 
       const finalMemoryStats = this.smartMemory.getMemoryStats();
+      this.logger.info('🔍 DEBUG: Metadata before memoryStats merge:', {
+        hasMetadata: !!response.metadata,
+        metadataKeys: response.metadata ? Object.keys(response.metadata) : [],
+        hasHashLinkBlock: !!(response.metadata as any)?.hashLinkBlock
+      });
+      
       response.metadata = {
+        ...preservedMetadata,
         ...response.metadata,
         memoryStats: {
           activeMessages: finalMemoryStats.totalActiveMessages,
@@ -462,6 +1072,19 @@ export class LangChainAgent extends BaseAgent {
           usagePercentage: finalMemoryStats.usagePercentage,
         },
       };
+      
+      this.logger.info('🔍 DEBUG: Final response metadata before return:', {
+        hasMetadata: !!response.metadata,
+        metadataKeys: response.metadata ? Object.keys(response.metadata) : [],
+        hasHashLinkBlock: !!(response.metadata as any)?.hashLinkBlock,
+        fullMetadata: response.metadata
+      });
+      
+      if ((preservedMetadata as any)?.hashLinkBlock && !(response.metadata as any)?.hashLinkBlock) {
+        this.logger.error('❌ CRITICAL: HashLink metadata was lost during processing!');
+        this.logger.error('Original metadata had hashLinkBlock:', (preservedMetadata as any).hashLinkBlock);
+        this.logger.error('Final metadata missing hashLinkBlock');
+      }
 
       return response;
     } catch (error) {
@@ -507,6 +1130,8 @@ export class LangChainAgent extends BaseAgent {
   }
 
   private async createExecutor(): Promise<void> {
+    const existingPendingForms = this.executor?.getPendingForms() || new Map();
+
     let llm: BaseChatModel;
     if (this.config.ai?.provider && this.config.ai.provider.getModel) {
       llm = this.config.ai.provider.getModel() as BaseChatModel;
@@ -540,6 +1165,41 @@ export class LangChainAgent extends BaseAgent {
 
     const langchainTools = this.tools as unknown as StructuredTool[];
 
+    const inscriptionTool = this.getInscriptionTool();
+    if (inscriptionTool) {
+      const entry = this.toolRegistry.getTool(inscriptionTool.name);
+      if (entry) {
+        this.logger.info(
+          `🔒 FINAL SECURITY CHECK - ${inscriptionTool.name} tool type: ${entry.tool.constructor.name}`
+        );
+        if (entry.tool.constructor.name !== 'FormValidatingToolWrapper') {
+          this.logger.error(
+            `🚨 SECURITY BREACH: ${inscriptionTool.name} tool is NOT wrapped!`
+          );
+          throw new Error(
+            `Critical security failure: ${inscriptionTool.name} tool bypassed FormValidatingToolWrapper`
+          );
+        } else {
+          this.logger.info(
+            `✅ SECURITY VALIDATED: ${inscriptionTool.name} tool is properly wrapped`
+          );
+        }
+      }
+    }
+
+    const stats = this.toolRegistry.getStatistics();
+    this.logger.info('🛡️ TOOL SECURITY REPORT:', {
+      totalTools: stats.totalTools,
+      wrappedTools: stats.wrappedTools,
+      unwrappedTools: stats.unwrappedTools,
+      categories: stats.categoryCounts,
+      priorities: stats.priorityCounts,
+    });
+
+    this.logger.info(
+      `📊 Tool Security Summary: ${stats.wrappedTools} wrapped, ${stats.unwrappedTools} unwrapped`
+    );
+
     const agent = await createOpenAIToolsAgent({
       llm,
       tools: langchainTools,
@@ -552,6 +1212,13 @@ export class LangChainAgent extends BaseAgent {
       verbose: this.config.debug?.verbose ?? false,
       returnIntermediateSteps: true,
     });
+
+    if (existingPendingForms.size > 0) {
+      this.logger.info(
+        `Restoring ${existingPendingForms.size} pending forms to new executor`
+      );
+      this.executor.restorePendingForms(existingPendingForms);
+    }
   }
 
   private handleError(error: unknown): ChatResponse {
@@ -651,8 +1318,17 @@ export class LangChainAgent extends BaseAgent {
             this.mcpManager,
             serverConfig
           );
-          this.tools.push(langchainTool);
+
+          this.toolRegistry.registerTool(langchainTool, {
+            metadata: {
+              category: 'mcp',
+              version: '1.0.0',
+              dependencies: [serverConfig.name],
+            },
+          });
         }
+
+        this.tools = this.toolRegistry.getAllTools();
       } else {
         this.logger.error(
           `Failed to connect to MCP server ${status.serverName}: ${status.error}`
@@ -687,7 +1363,7 @@ export class LangChainAgent extends BaseAgent {
   /**
    * Connect to a single MCP server in background with timeout
    */
-  private connectServerInBackground(serverConfig: any): void {
+  private connectServerInBackground(serverConfig: MCPServerConfig): void {
     const serverName = serverConfig.name;
 
     setTimeout(async () => {
@@ -708,9 +1384,18 @@ export class LangChainAgent extends BaseAgent {
               this.mcpManager!,
               serverConfig
             );
-            this.tools.push(langchainTool);
+
+            this.toolRegistry.registerTool(langchainTool, {
+              metadata: {
+                category: 'mcp',
+                version: '1.0.0',
+                dependencies: [serverConfig.name],
+              },
+            });
           }
 
+          this.tools = this.toolRegistry.getAllTools();
+
           if (this.initialized && this.executor) {
             this.logger.info(
               `Recreating executor with ${this.tools.length} total tools`
@@ -738,6 +1423,60 @@ export class LangChainAgent extends BaseAgent {
     }, 1000);
   }
 
+  /**
+   * Detects and processes HashLink blocks from tool responses
+   * @param parsedResponse - The parsed JSON response from a tool
+   * @returns Metadata object containing hashLinkBlock if detected
+   */
+  private processHashLinkBlocks(parsedResponse: unknown): {
+    hashLinkBlock?: Record<string, unknown>;
+  } {
+    try {
+      const responseRecord = parsedResponse as Record<string, unknown>;
+      if (
+        parsedResponse &&
+        typeof parsedResponse === 'object' &&
+        responseRecord.hashLinkBlock &&
+        typeof responseRecord.hashLinkBlock === 'object'
+      ) {
+        const block = responseRecord.hashLinkBlock as Record<string, unknown>;
+
+        if (
+          block.blockId &&
+          block.hashLink &&
+          block.template &&
+          block.attributes &&
+          typeof block.blockId === 'string' &&
+          typeof block.hashLink === 'string' &&
+          typeof block.template === 'string' &&
+          typeof block.attributes === 'object'
+        ) {
+          this.logger.info('HashLink block detected:', {
+            blockId: block.blockId,
+            hashLink: block.hashLink,
+            template: block.template,
+            attributeKeys: Object.keys(block.attributes),
+          });
+
+          return {
+            hashLinkBlock: {
+              blockId: block.blockId,
+              hashLink: block.hashLink,
+              template: block.template,
+              attributes: block.attributes,
+            },
+          };
+        } else {
+          this.logger.warn('Invalid HashLink block structure detected:', block);
+        }
+      }
+    } catch (error) {
+      this.logger.error('Error processing HashLink blocks:', error);
+    }
+
+    return {};
+  }
+
   /**
    * Check if a string is valid JSON
    */