@hashgraphonline/conversational-agent 0.1.217 → 0.1.218

package/dist/types/langchain/external-tool-wrapper.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Mock external tool wrapper functionality
+ * These are placeholders to satisfy import statements in test scripts
+ */
+export interface ExternalToolWrapper<T> {
+    name: string;
+    description: string;
+    schema: T;
+}
+export declare function wrapExternalToolWithRenderConfig<T>(tool: {
+    name: string;
+    description: string;
+    schema: T;
+}, config: {
+    ui?: {
+        label?: string;
+        description?: string;
+    };
+    fieldConfigs?: Record<string, unknown>;
+}): ExternalToolWrapper<T>;
+export declare const renderConfigs: {
+    text: (label: string, placeholder?: string, help?: string) => {
+        type: string;
+        label: string;
+        placeholder: string | undefined;
+        help: string | undefined;
+    };
+    number: (label: string, min?: number, max?: number, help?: string) => {
+        type: string;
+        label: string;
+        min: number | undefined;
+        max: number | undefined;
+        help: string | undefined;
+    };
+    accountId: (label: string) => {
+        type: string;
+        label: string;
+        placeholder: string;
+    };
+    checkbox: (label: string, help?: string) => {
+        type: string;
+        label: string;
+        help: string | undefined;
+    };
+    currency: (label: string, currency: string, min?: number, max?: number) => {
+        type: string;
+        label: string;
+        currency: string;
+        min: number | undefined;
+        max: number | undefined;
+    };
+    tokenId: (label: string) => {
+        type: string;
+        label: string;
+        placeholder: string;
+    };
+    select: (label: string, options: Array<{
+        value: string;
+        label: string;
+    }>) => {
+        type: string;
+        label: string;
+        options: {
+            value: string;
+            label: string;
+        }[];
+    };
+};
+export declare const hederaToolConfigs: {
+    hbarTransfer: () => {
+        ui: {
+            label: string;
+            description: string;
+        };
+        fieldConfigs: {
+            fromAccountId: {
+                type: string;
+                label: string;
+                placeholder: string;
+            };
+            toAccountId: {
+                type: string;
+                label: string;
+                placeholder: string;
+            };
+            amount: {
+                type: string;
+                label: string;
+                currency: string;
+                min: number | undefined;
+                max: number | undefined;
+            };
+            memo: {
+                type: string;
+                label: string;
+                placeholder: string | undefined;
+                help: string | undefined;
+            };
+        };
+    };
+};

package/dist/{cjs/langchain/FormAwareAgentExecutor.d.ts → types/langchain/form-aware-agent-executor.d.ts}

@@ -15,6 +15,12 @@ interface PendingFormData {
         call?: (args: Record<string, unknown>) => Promise<string>;
     } | undefined;
 }
+/**
+ * Parameter preprocessing callback interface
+ */
+export interface ParameterPreprocessingCallback {
+    (toolName: string, parameters: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
 /**
  * Agent executor that intercepts Zod validation errors and generates forms,
  * and processes HashLink block responses for rich UI rendering
@@ -24,16 +30,25 @@ export declare class FormAwareAgentExecutor extends AgentExecutor {
     private formEngine;
     private formLogger;
     private pendingForms;
+    private parameterPreprocessingCallback;
+    /**
+     * Type guard to check if a Zod type is a ZodObject
+     */
+    private isZodObject;
+    /**
+     * Type guard to check if metadata has hashLinkBlock
+     */
+    private hasHashLinkBlock;
     constructor(...args: ConstructorParameters<typeof AgentExecutor>);
+    /**
+     * Set parameter preprocessing callback
+     */
+    setParameterPreprocessingCallback(callback: ParameterPreprocessingCallback | undefined): void;
     /**
      * BULLETPROOF TOOL INTERCEPTION
      * Override the single-step execution to intercept tool calls BEFORE LangChain processes them
      */
     _takeNextStep(nameToolMap: Record<string, ToolInterface>, inputs: ChainValues, intermediateSteps: AgentStep[], runManager?: CallbackManagerForChainRun, config?: RunnableConfig): Promise<AgentFinish | AgentStep[]>;
-    /**
-     * Type guard to check if a schema is a ZodObject
-     */
-    private isZodObject;
     /**
      * Helper to determine if a field is required in the schema
      */
@@ -42,10 +57,6 @@ export declare class FormAwareAgentExecutor extends AgentExecutor {
      * Override _call to intercept Zod validation errors at the execution level
      */
     _call(inputs: Record<string, unknown>): Promise<Record<string, unknown>>;
-    /**
-     * Handles Zod validation errors by generating forms
-     */
-    private handleValidationError;
     /**
      * Get a copy of pending forms for preservation during executor recreation
      */
@@ -66,10 +77,6 @@ export declare class FormAwareAgentExecutor extends AgentExecutor {
      * Attempts to find tool from execution context
      */
     private findToolFromContext;
-    /**
-     * Additional fallback to detect tool from error context
-     */
-    private detectToolFromErrorContext;
     /**
      * Checks if a schema structure matches error paths
      */

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

@@ -0,0 +1,2 @@
+export * from './form-aware-agent-executor';
+export * from './langchain-agent';

package/dist/{cjs → types/langchain}/langchain-agent.d.ts

@@ -1,6 +1,7 @@
-import { BaseAgent, ConversationContext, ChatResponse, OperationalMode, UsageStats } from './base-agent';
-import { MCPConnectionStatus } from './mcp/types';
-import { FormSubmission } from './forms/types';
+import { ParameterPreprocessingCallback } from './form-aware-agent-executor';
+import { BaseAgent, ConversationContext, ChatResponse, OperationalMode, UsageStats } from '../base-agent';
+import { MCPConnectionStatus } from '../mcp/types';
+import { FormSubmission } from '../forms/types';
 
 export declare class LangChainAgent extends BaseAgent {
     private executor;
@@ -11,14 +12,14 @@ export declare class LangChainAgent extends BaseAgent {
     private toolRegistry;
     private executionPipeline;
     private formEngine;
+    private addToolRawToMemory;
+    private persistToolRaw;
+    private persistIntermediateSteps;
+    private pendingParameterPreprocessingCallback;
     /**
      * Get inscription tool by capability instead of hardcoded name
      */
     private getInscriptionTool;
-    /**
-     * Get a tool by name from the registry with type safety
-     */
-    private getTool;
     /**
      * Execute a tool directly with parameters, optionally using ExecutionPipeline
      */
@@ -50,6 +51,9 @@ export declare class LangChainAgent extends BaseAgent {
     /**
      * Normalize context messages into LangChain message instances and load into memory
      */
+    /**
+     * Loads context messages into memory, merging with existing messages
+     */
     private loadContextMessages;
     boot(): Promise<void>;
     chat(message: string, context?: ConversationContext): Promise<ChatResponse>;
@@ -76,6 +80,10 @@ export declare class LangChainAgent extends BaseAgent {
     }>;
     private createAgentKit;
     private createExecutor;
+    /**
+     * Set parameter preprocessing callback for tool parameter format conversion
+     */
+    setParameterPreprocessingCallback(callback: ParameterPreprocessingCallback | undefined): void;
     private handleError;
     private initializeMCP;
     /**

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

@@ -0,0 +1 @@
+export * from './langchain';

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

@@ -1,6 +1,6 @@
 import { DynamicStructuredTool } from '@langchain/core/tools';
 import { MCPToolInfo, MCPServerConfig } from '../types';
-import { MCPClientManager } from '../MCPClientManager';
+import { MCPClientManager } from '../mcp-client-manager';
 
 /**
  * Convert an MCP tool to a LangChain DynamicStructuredTool

package/dist/{cjs/mcp/ContentProcessor.d.ts → types/mcp/content-processor.d.ts}

@@ -1,4 +1,4 @@
-import { ContentStorage } from '../memory/ContentStorage';
+import { ContentStorage } from '../memory/content-storage';
 import { Logger } from '@hashgraphonline/standards-sdk';
 
 export interface MCPResponseContent {

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

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './helpers';
+export * from './mcp-client-manager';
+export * from './content-processor';
+export * from './adapters';

package/dist/{cjs/mcp/MCPClientManager.d.ts → types/mcp/mcp-client-manager.d.ts}

@@ -1,6 +1,6 @@
 import { MCPServerConfig, MCPToolInfo, MCPConnectionStatus } from './types';
 import { Logger } from '@hashgraphonline/standards-sdk';
-import { ContentStorage } from '../memory/ContentStorage';
+import { ContentStorage } from '../memory/content-storage';
 
 /**
  * Manages connections to MCP servers and tool discovery

package/dist/types/memory/{ContentStorage.d.ts → content-storage.d.ts}

@@ -129,12 +129,12 @@ export declare class ContentStorage implements ContentReferenceStore {
      * Export messages to a JSON-serializable format
      * @returns Serializable representation of stored messages
      */
-    exportMessages(): {
-        content: import('@langchain/core/messages').MessageContent;
-        type: import('@langchain/core/messages').MessageType;
+    exportMessages(): Array<{
+        content: string;
+        type: string;
         storedAt: string;
         id: string;
-    }[];
+    }>;
     /**
      * Determine if content should be stored as a reference based on size
      */

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

@@ -1,7 +1,5 @@
-export { TokenCounter } from './TokenCounter';
-export { MemoryWindow } from './MemoryWindow';
-export { ContentStorage } from './ContentStorage';
-export { SmartMemoryManager } from './SmartMemoryManager';
-export type { SmartMemoryConfig, SearchOptions, MemoryStats, EntityAssociation, EntityResolutionOptions } from './SmartMemoryManager';
-export type { AddMessageResult } from './MemoryWindow';
-export type { StorageStats } from './ContentStorage';
+export * from './smart-memory-manager';
+export * from './token-counter';
+export * from './memory-window';
+export * from './content-storage';
+export * from './reference-id-generator';

package/dist/{cjs/memory/MemoryWindow.d.ts → types/memory/memory-window.d.ts}

@@ -1,5 +1,5 @@
 import { BaseMessage } from '@langchain/core/messages';
-import { TokenCounter } from './TokenCounter';
+import { TokenCounter } from './token-counter';
 
 /**
  * Result of adding a message to the memory window

package/dist/{cjs/memory/SmartMemoryManager.d.ts → types/memory/smart-memory-manager.d.ts}

@@ -1,5 +1,5 @@
 import { BaseMessage } from '@langchain/core/messages';
-import { ContentStorage } from './ContentStorage';
+import { ContentStorage } from './content-storage';
 
 /**
  * Entity association for storing blockchain entity contexts

package/dist/types/services/{ContentStoreManager.d.ts → content-store-manager.d.ts}

@@ -1,11 +1,11 @@
-import { ContentStorage } from '../memory/ContentStorage';
-import { ContentReferenceConfig } from '../types/content-reference';
+import { ContentStorage } from '../memory/content-storage';
+import { ContentReference, ContentReferenceConfig, ContentReferenceStats } from '../types/content-reference';
 import { Logger } from '@hashgraphonline/standards-sdk';
 
 /**
- * Content metadata interface
+ * Content metadata interface for adapter compatibility
  */
-interface ContentMetadata {
+interface AdapterContentMetadata {
     mimeType?: string;
     fileName?: string;
     sizeBytes?: number;
@@ -32,7 +32,7 @@ export declare class ContentStoreManager {
     /**
      * Get storage statistics
      */
-    getStats(): Promise<import('../types').ContentReferenceStats>;
+    getStats(): Promise<ContentReferenceStats>;
     /**
      * Update configuration
      */
@@ -51,7 +51,7 @@ export declare class ContentStoreManager {
     /**
      * Store content if it's large enough
      */
-    storeContentIfLarge(content: Buffer | string, metadata: ContentMetadata): Promise<import('../types').ContentReference | null>;
+    storeContentIfLarge(content: Buffer | string, metadata: AdapterContentMetadata): Promise<ContentReference | null>;
     /**
      * Cleanup and unregister
      */

package/dist/types/services/context/resolution-context.d.ts

@@ -0,0 +1,49 @@
+import { ToolMetadata } from '../../core/tool-registry';
+
+export declare enum EntityType {
+    TOPIC = "topicId",
+    TOKEN = "tokenId",
+    NFT = "tokenId",
+    ACCOUNT = "accountId",
+    INSCRIPTION = "hrl"
+}
+export interface EntityHint {
+    type: EntityType;
+    value: string;
+    confidence: number;
+    source: 'user' | 'llm' | 'cached';
+}
+export interface ConversionRecord {
+    originalValue: string;
+    convertedValue: string;
+    sourceFormat: string;
+    targetFormat: string;
+    converterUsed: string;
+    timestamp: Date;
+    context: Record<string, unknown>;
+}
+export interface ResolutionContext {
+    toolMetadata?: ToolMetadata;
+    userMessage: string;
+    entityHints: EntityHint[];
+    networkType: string;
+    conversionHistory: ConversionRecord[];
+    sessionId: string;
+}
+/**
+ * Builder for creating and modifying resolution contexts
+ */
+export declare class ResolutionContextBuilder {
+    /**
+     * Create initial context from user message and session ID
+     */
+    static fromMessage(message: string, sessionId: string): ResolutionContext;
+    /**
+     * Add tool metadata to existing context
+     */
+    static withToolContext(context: ResolutionContext, toolMetadata: ToolMetadata): ResolutionContext;
+    /**
+     * Add entity hints to existing context
+     */
+    static withEntityHints(context: ResolutionContext, hints: EntityHint[]): ResolutionContext;
+}

package/dist/types/services/entity-resolver.d.ts

@@ -0,0 +1,58 @@
+import { EntityAssociation } from '../memory/smart-memory-manager';
+import { EntityFormat } from '..';
+
+export interface EntityResolverConfig {
+    apiKey: string;
+    modelName?: string;
+}
+interface ExtractedEntity {
+    id: string;
+    name: string;
+    type: EntityFormat;
+    transactionId?: string;
+}
+/**
+ * LLM-based entity resolver that replaces brittle regex patterns
+ */
+export declare class EntityResolver {
+    private llm;
+    private logger;
+    constructor(config: EntityResolverConfig);
+    /**
+     * Resolve entity references using LLM instead of regex
+     */
+    resolveReferences(message: string, entities: EntityAssociation[]): Promise<string>;
+    /**
+     * Extract entities from agent response using receipt data (preferred) or LLM fallback
+     */
+    extractEntities(response: unknown, userMessage: string): Promise<ExtractedEntity[]>;
+    /**
+     * Extract entities from transaction receipt data (primary method)
+     */
+    private extractFromReceipt;
+    /**
+     * Extract entity name from user message
+     */
+    private extractNameFromMessage;
+    /**
+     * Extract entities using LLM (fallback method)
+     */
+    private extractWithLLM;
+    /**
+     * Validate that an entity matches the expected type
+     */
+    validateEntityType(entityId: string, expectedType: string, entities: EntityAssociation[]): boolean;
+    /**
+     * Resolve entity references with type validation
+     */
+    resolveWithTypeValidation(query: string, entities: EntityAssociation[], expectedType?: string): Promise<EntityAssociation[]>;
+    /**
+     * Get entities filtered by type
+     */
+    getEntitiesByType(entities: EntityAssociation[], entityType: string): EntityAssociation[];
+    /**
+     * Find the most recent entity of a specific type
+     */
+    getMostRecentEntityByType(entities: EntityAssociation[], entityType: string): EntityAssociation | null;
+}
+export {};

package/dist/types/services/formatters/converters/index.d.ts

@@ -0,0 +1,2 @@
+export { TopicIdToHrlConverter } from './topic-id-to-hrl-converter';
+export { StringNormalizationConverter } from './string-normalization-converter';

package/dist/types/services/formatters/converters/string-normalization-converter.d.ts

@@ -0,0 +1,13 @@
+import { EntityFormat, FormatConverter, ConversionContext } from '../types';
+
+/**
+ * Generic converter that normalizes various string entity references (cdn urls, content-ref, raw topic id)
+ * into canonical HRL. It declares source ANY -> HRL and internally short-circuits if unsupported.
+ */
+export declare class StringNormalizationConverter implements FormatConverter<string, string> {
+    sourceFormat: EntityFormat;
+    targetFormat: EntityFormat;
+    private static standardCache;
+    canConvert(source: string, _context: ConversionContext): boolean;
+    convert(source: string, context: ConversionContext): Promise<string>;
+}

package/dist/types/services/formatters/converters/topic-id-to-hrl-converter.d.ts

@@ -0,0 +1,17 @@
+import { EntityFormat, FormatConverter, ConversionContext } from '../types';
+
+/**
+ * Converts Hedera topic IDs to HRL format for consensus service messages
+ */
+export declare class TopicIdToHrlConverter implements FormatConverter<string, string> {
+    sourceFormat: EntityFormat;
+    targetFormat: EntityFormat;
+    /**
+     * Check if the source string is a valid topic ID
+     */
+    canConvert(source: string, _context: ConversionContext): boolean;
+    /**
+     * Convert topic ID to HRL format based on network type
+     */
+    convert(topicId: string, context: ConversionContext): Promise<string>;
+}

package/dist/types/services/formatters/format-converter-registry.d.ts

@@ -0,0 +1,66 @@
+import { EntityFormat, FormatConverter, ConversionContext } from './types';
+
+/**
+ * Registry for format converters that handles entity transformation
+ */
+export declare class FormatConverterRegistry {
+    private converters;
+    private entityTypeCache;
+    private logger;
+    private defaultCacheTTL;
+    /**
+     * Register a format converter
+     */
+    register<TSource, TTarget>(converter: FormatConverter<TSource, TTarget>): void;
+    /**
+     * Find a converter for the given source and target formats
+     */
+    findConverter(source: EntityFormat, target: EntityFormat): FormatConverter<unknown, unknown> | null;
+    /**
+     * Convert an entity to the target format
+     */
+    convertEntity(entity: string, target: EntityFormat, context: ConversionContext): Promise<string>;
+    /**
+     * Detect the format of an entity string with API-based verification and fallback
+     */
+    private detectFormatWithFallback;
+    /**
+     * Public helper: detect entity format (ACCOUNT_ID, TOKEN_ID, TOPIC_ID, HRL, or ANY)
+     */
+    detectEntityFormat(entity: string, context?: ConversionContext): Promise<EntityFormat>;
+    /**
+     * Detect entity format via Hedera Mirror Node API calls
+     */
+    private detectFormat;
+    /**
+     * Get cached entity format if valid
+     */
+    private getCachedFormat;
+    /**
+     * Set cached entity format
+     */
+    private setCachedFormat;
+    /**
+     * Check if cache entry is expired
+     */
+    private isCacheExpired;
+    /**
+     * Get all registered converters
+     */
+    getRegisteredConverters(): Array<{
+        source: EntityFormat;
+        target: EntityFormat;
+    }>;
+    /**
+     * Check if a converter exists for the given formats
+     */
+    hasConverter(source: EntityFormat, target: EntityFormat): boolean;
+    /**
+     * Clear all registered converters
+     */
+    clear(): void;
+    /**
+     * Clear entity type cache
+     */
+    clearCache(): void;
+}

package/dist/types/services/formatters/index.d.ts

@@ -0,0 +1,3 @@
+export { FormatConverterRegistry } from './format-converter-registry';
+export { EntityFormat, type FormatConverter, type ConversionContext } from './types';
+export * from './converters';

package/dist/types/services/formatters/types.d.ts

@@ -0,0 +1,29 @@
+export declare enum EntityFormat {
+    TOPIC_ID = "topicId",
+    HRL = "hrl",
+    SCHEDULE_ID = "scheduleId",
+    TOKEN_ID = "tokenId",
+    ADDRESS = "address",
+    SYMBOL = "symbol",
+    SERIAL_NUMBER = "serialNumber",
+    METADATA = "metadata",
+    ACCOUNT_ID = "accountId",
+    ALIAS = "alias",
+    EVM_ADDRESS = "evmAddress",
+    CONTRACT_ID = "contractId",
+    FILE_ID = "fileId",
+    ANY = "any"
+}
+export interface ConversionContext {
+    networkType?: string;
+    sessionId?: string;
+    toolName?: string;
+    toolPreferences?: Record<string, string>;
+    [key: string]: unknown;
+}
+export interface FormatConverter<TSource = string, TTarget = string> {
+    sourceFormat: EntityFormat;
+    targetFormat: EntityFormat;
+    canConvert(source: string, context: ConversionContext): boolean;
+    convert(entity: TSource, context: ConversionContext): Promise<TTarget>;
+}

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

@@ -0,0 +1,3 @@
+export * from './entity-resolver';
+export * from './content-store-manager';
+export * from './formatters';

package/dist/types/services/resolution/resolution-pipeline.d.ts

@@ -0,0 +1,44 @@
+import { ResolutionContext, EntityType } from '../context/resolution-context';
+
+export interface DetectedEntity {
+    type: EntityType;
+    value: string;
+    originalText: string;
+    confidence: number;
+    position: number;
+}
+export interface ResolvedMessage {
+    message: string;
+    entities: DetectedEntity[];
+    conversions: Array<{
+        original: string;
+        converted: string;
+    }>;
+    context: ResolutionContext;
+}
+export interface ResolutionStage<TInput = unknown, TOutput = unknown> {
+    name: string;
+    process(input: TInput, context: ResolutionContext): Promise<TOutput>;
+}
+/**
+ * Multi-stage resolution pipeline that processes messages through configurable stages
+ */
+export declare class ResolutionPipeline {
+    private stages;
+    /**
+     * Add a stage to the pipeline
+     */
+    addStage<TInput, TOutput>(stage: ResolutionStage<TInput, TOutput>): void;
+    /**
+     * Get all registered stages
+     */
+    getStages(): ResolutionStage<unknown, unknown>[];
+    /**
+     * Clear all stages from the pipeline
+     */
+    clear(): void;
+    /**
+     * Process a message through all pipeline stages
+     */
+    process(message: string, context: ResolutionContext): Promise<ResolvedMessage>;
+}

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

@@ -0,0 +1 @@
+export * from './entity-resolver-tool';

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

@@ -0,0 +1 @@
+export * from './response-formatter';