@hashgraphonline/conversational-agent 0.2.104 → 0.2.105

package/src/forms/field-guidance-registry.ts

@@ -1,4 +1,5 @@
 import type { FormFieldType, FieldOption } from './types';
+import { Logger } from '@hashgraphonline/standards-sdk';
 
 /**
  * Field guidance configuration for providing contextual help and suggestions
@@ -90,6 +91,19 @@ export interface ToolFieldConfiguration {
  */
 class FieldGuidanceRegistry {
   private configurations: ToolFieldConfiguration[] = [];
+  private providers: Array<{
+    id: string;
+    priority: number;
+    pattern: string | RegExp;
+    provider: FieldGuidanceProvider;
+    order: number;
+  }> = [];
+  private registerOrderCounter = 0;
+  private logger: Logger;
+
+  constructor() {
+    this.logger = new Logger({ module: 'FieldGuidanceRegistry' });
+  }
 
   /**
    * Register field guidance for a specific tool
@@ -98,10 +112,55 @@ class FieldGuidanceRegistry {
     this.configurations.push(config);
   }
 
+  /**
+   * Register a provider for dynamic field/global guidance
+   */
+  registerToolProvider(
+    toolPattern: string | RegExp,
+    provider: FieldGuidanceProvider,
+    options?: { id?: string; priority?: number }
+  ): string {
+    const id = options?.id ?? `provider-${this.providers.length + 1}`;
+    const priority = options?.priority ?? 0;
+    if (this.providers.some((p) => p.id === id)) {
+      this.logger.error('Duplicate provider id', { id });
+      throw new Error('DUPLICATE_PROVIDER_ID');
+    }
+    this.providers.push({
+      id,
+      priority,
+      pattern: toolPattern,
+      provider,
+      order: this.registerOrderCounter++,
+    });
+    return id;
+  }
+
+  /** Unregister a provider by id */
+  unregisterProvider(id: string): void {
+    this.providers = this.providers.filter((p) => p.id !== id);
+  }
+
+  /** List registered providers */
+  listProviders(): Array<{
+    id: string;
+    priority: number;
+    pattern: string | RegExp;
+  }> {
+    return this.providers.map(({ id, priority, pattern }) => ({
+      id,
+      priority,
+      pattern,
+    }));
+  }
+
   /**
    * Get field guidance for a specific tool and field
    */
   getFieldGuidance(toolName: string, fieldName: string): FieldGuidance | null {
+    if (process.env.CA_FORM_GUIDANCE_ENABLED === 'false') {
+      return null;
+    }
     for (const config of this.configurations) {
       const matches =
         typeof config.toolPattern === 'string'
@@ -109,8 +168,31 @@ class FieldGuidanceRegistry {
           : config.toolPattern.test(toolName);
 
       if (matches && config.fields[fieldName]) {
-        return config.fields[fieldName];
+        const staticGuidance = config.fields[fieldName];
+        const providers = this.pickMatchingProviders(toolName);
+        if (providers.length === 0) return staticGuidance;
+        let merged: FieldGuidance = { ...staticGuidance };
+        for (const p of [...providers].reverse()) {
+          const fromProvider = this.safeGetFieldGuidance(
+            p,
+            fieldName,
+            toolName
+          );
+          if (fromProvider) {
+            merged = this.mergeGuidance(merged, fromProvider);
+          }
+        }
+        return merged;
+      }
+    }
+    const providers = this.pickMatchingProviders(toolName);
+    if (providers.length > 0) {
+      let merged: FieldGuidance = {};
+      for (const p of [...providers].reverse()) {
+        const g = this.safeGetFieldGuidance(p, fieldName, toolName);
+        if (g) merged = this.mergeGuidance(merged, g);
       }
+      return Object.keys(merged).length > 0 ? merged : null;
     }
     return null;
   }
@@ -121,6 +203,9 @@ class FieldGuidanceRegistry {
   getGlobalGuidance(
     toolName: string
   ): ToolFieldConfiguration['globalGuidance'] | null {
+    if (process.env.CA_FORM_GUIDANCE_ENABLED === 'false') {
+      return null;
+    }
     for (const config of this.configurations) {
       const matches =
         typeof config.toolPattern === 'string'
@@ -128,9 +213,42 @@ class FieldGuidanceRegistry {
           : config.toolPattern.test(toolName);
 
       if (matches && config.globalGuidance) {
-        return config.globalGuidance;
+        const base = config.globalGuidance;
+        const providers = this.pickMatchingProviders(toolName);
+        if (providers.length === 0) return base;
+        let mergedWarnings: string[] | undefined = base.warnings;
+        let mergedQuality: string[] | undefined = base.qualityStandards;
+        for (const p of [...providers].reverse()) {
+          const fromProvider = this.safeGetGlobalGuidance(p, toolName);
+          if (fromProvider) {
+            mergedWarnings = fromProvider.warnings ?? mergedWarnings;
+            mergedQuality = fromProvider.qualityStandards ?? mergedQuality;
+          }
+        }
+        const result: NonNullable<ToolFieldConfiguration['globalGuidance']> =
+          {};
+        if (mergedWarnings !== undefined) result.warnings = mergedWarnings;
+        if (mergedQuality !== undefined)
+          result.qualityStandards = mergedQuality;
+        return result;
       }
     }
+    const providers = this.pickMatchingProviders(toolName);
+    if (providers.length > 0) {
+      let mergedWarnings: string[] | undefined;
+      let mergedQuality: string[] | undefined;
+      for (const p of [...providers].reverse()) {
+        const g = this.safeGetGlobalGuidance(p, toolName);
+        if (g) {
+          mergedWarnings = g.warnings ?? mergedWarnings;
+          mergedQuality = g.qualityStandards ?? mergedQuality;
+        }
+      }
+      const result: NonNullable<ToolFieldConfiguration['globalGuidance']> = {};
+      if (mergedWarnings !== undefined) result.warnings = mergedWarnings;
+      if (mergedQuality !== undefined) result.qualityStandards = mergedQuality;
+      return Object.keys(result).length > 0 ? result : null;
+    }
     return null;
   }
 
@@ -222,194 +340,101 @@ class FieldGuidanceRegistry {
    */
   clear(): void {
     this.configurations = [];
+    this.providers = [];
+    this.registerOrderCounter = 0;
+  }
+
+  /** Choose matching provider by priority then last-in wins */
+  private pickMatchingProviders(toolName: string): Array<{
+    id: string;
+    provider: FieldGuidanceProvider;
+    priority: number;
+    order: number;
+  }> {
+    const matches = this.providers.filter((p) =>
+      typeof p.pattern === 'string'
+        ? toolName.toLowerCase().includes((p.pattern as string).toLowerCase())
+        : (p.pattern as RegExp).test(toolName)
+    );
+    const sorted = matches.sort((a, b) => {
+      if (b.priority !== a.priority) return b.priority - a.priority;
+      return b.order - a.order; // last-in wins when equal priority
+    });
+    return sorted.map((m) => ({
+      id: m.id,
+      provider: m.provider,
+      priority: m.priority,
+      order: m.order,
+    }));
+  }
+
+  private safeGetFieldGuidance(
+    winner: { id: string; provider: FieldGuidanceProvider },
+    fieldName: string,
+    toolName: string
+  ): FieldGuidance | null {
+    try {
+      return winner.provider.getFieldGuidance(fieldName, { toolName }) ?? null;
+    } catch (err) {
+      this.logger.warn('Provider getFieldGuidance failed', {
+        id: winner.id,
+        err,
+      });
+      return null;
+    }
+  }
+
+  private safeGetGlobalGuidance(
+    winner: { id: string; provider: FieldGuidanceProvider },
+    toolName: string
+  ): ToolFieldConfiguration['globalGuidance'] | null {
+    try {
+      return winner.provider.getGlobalGuidance?.(toolName) ?? null;
+    } catch (err) {
+      this.logger.warn('Provider getGlobalGuidance failed', {
+        id: winner.id,
+        err,
+      });
+      return null;
+    }
+  }
+
+  private mergeGuidance(
+    base: FieldGuidance,
+    over: FieldGuidance
+  ): FieldGuidance {
+    const out: FieldGuidance = {};
+    const suggestions = over.suggestions ?? base.suggestions;
+    if (suggestions !== undefined) out.suggestions = suggestions;
+    const predefinedOptions = over.predefinedOptions ?? base.predefinedOptions;
+    if (predefinedOptions !== undefined)
+      out.predefinedOptions = predefinedOptions;
+    const warnings = over.warnings ?? base.warnings;
+    if (warnings !== undefined) out.warnings = warnings;
+    const validationRules = over.validationRules ?? base.validationRules;
+    if (validationRules !== undefined) out.validationRules = validationRules;
+    const fieldTypeOverride = over.fieldTypeOverride ?? base.fieldTypeOverride;
+    if (fieldTypeOverride !== undefined)
+      out.fieldTypeOverride = fieldTypeOverride;
+    const contextualHelpText =
+      over.contextualHelpText ?? base.contextualHelpText;
+    if (contextualHelpText !== undefined)
+      out.contextualHelpText = contextualHelpText;
+    return out;
   }
 }
 
 export const fieldGuidanceRegistry = new FieldGuidanceRegistry();
 
-fieldGuidanceRegistry.registerToolConfiguration({
-  toolPattern: /inscribe.*hashinal/i,
-  globalGuidance: {
-    warnings: [
-      'Avoid auto-generating technical metadata like file types or upload sources',
-      'Focus on collectible traits that add value to the NFT',
-    ],
-    qualityStandards: [
-      'Use meaningful names that describe the artwork or content',
-      'Include collectible attributes like rarity, style, or theme',
-      'Provide descriptions that tell a story or explain the concept',
-    ],
-  },
-  fields: {
-    name: {
-      suggestions: [
-        'Sunset Landscape #42',
-        'Digital Abstract Art',
-        'Cosmic Dream Series',
-        'Portrait Study #5',
-      ],
-      validationRules: {
-        rejectPatterns: [
-          {
-            pattern: /^untitled$/i,
-            reason: 'Generic names like "Untitled" are not valuable for NFTs',
-          },
-          {
-            pattern: /^image|file|upload/i,
-            reason: 'Avoid technical file references in NFT names',
-          },
-        ],
-        qualityChecks: {
-          minNonTechnicalWords: 2,
-          forbidTechnicalTerms: [
-            'MIME',
-            'upload',
-            'file type',
-            'buffer',
-            'source',
-          ],
-        },
-      },
-      contextualHelpText:
-        'Create a distinctive name that collectors will find appealing and memorable',
-    },
-
-    description: {
-      suggestions: [
-        'A vibrant sunset captured in digital brushstrokes...',
-        'Part of the Cosmic Dreams collection, exploring...',
-        'This piece represents the intersection of technology and nature...',
-      ],
-      validationRules: {
-        rejectPatterns: [
-          {
-            pattern: /uploaded by|file size|mime type|created from/i,
-            reason: 'Avoid technical descriptions in NFT metadata',
-          },
-        ],
-        qualityChecks: {
-          minNonTechnicalWords: 8,
-          forbidTechnicalTerms: [
-            'uploaded',
-            'file size',
-            'mime type',
-            'user upload',
-            'image format',
-            'pixel dimensions',
-            'file extension',
-          ],
-          requireSpecificTerms: [
-            'art',
-            'collection',
-            'piece',
-            'concept',
-            'inspired',
-            'represents',
-          ],
-        },
-      },
-      fieldTypeOverride: 'textarea',
-      contextualHelpText:
-        'Describe the story, inspiration, or artistic vision behind this NFT',
-    },
-
-    creator: {
-      suggestions: [
-        '0.0.123456 (Hedera Account ID)',
-        'ArtistName',
-        'StudioBrand',
-        'CollectiveDAO',
-      ],
-      contextualHelpText:
-        "Provide the creator's account ID, artist name, or brand identity",
-    },
-
-    attributes: {
-      predefinedOptions: [
-        {
-          value: 'Rarity',
-          label: 'Rarity',
-          description: 'Common, Rare, Epic, Legendary',
-        },
-        {
-          value: 'Color',
-          label: 'Color',
-          description: 'Primary colors or palette',
-        },
-        {
-          value: 'Style',
-          label: 'Style',
-          description: 'Abstract, Realistic, Minimalist, etc.',
-        },
-        {
-          value: 'Theme',
-          label: 'Theme',
-          description: 'Nature, Technology, Fantasy, etc.',
-        },
-        {
-          value: 'Series',
-          label: 'Series',
-          description: 'Collection or series number',
-        },
-        {
-          value: 'Element',
-          label: 'Element',
-          description: 'Fire, Water, Earth, Air, etc.',
-        },
-        {
-          value: 'Power Level',
-          label: 'Power Level',
-          description: 'Numeric strength value',
-        },
-        {
-          value: 'Edition',
-          label: 'Edition',
-          description: 'Special, Limited, First, etc.',
-        },
-      ],
-      warnings: [
-        {
-          pattern: /mime.?type|file.?type|upload.?source/i,
-          message: 'Technical metadata is not valuable for NFT collectors',
-        },
-      ],
-      validationRules: {
-        rejectPatterns: [
-          {
-            pattern: /^(mime.?type|file.?type|source|origin|upload)$/i,
-            reason: 'Technical attributes are not collectible traits',
-          },
-        ],
-        qualityChecks: {
-          forbidTechnicalTerms: [
-            'MIME Type',
-            'File Type',
-            'Source',
-            'Origin',
-            'Upload Source',
-            'File Extension',
-            'Format',
-          ],
-        },
-      },
-      contextualHelpText:
-        'Add traits that make this NFT unique and valuable to collectors',
-    },
-
-    type: {
-      predefinedOptions: [
-        { value: 'Digital Art', label: 'Digital Art' },
-        { value: 'Photography', label: 'Photography' },
-        { value: 'Collectible Card', label: 'Collectible Card' },
-        { value: 'Avatar', label: 'Avatar' },
-        { value: 'Music', label: 'Music' },
-        { value: 'Video', label: 'Video' },
-        { value: '3D Model', label: '3D Model' },
-        { value: 'Generative Art', label: 'Generative Art' },
-        { value: 'Pixel Art', label: 'Pixel Art' },
-      ],
-      contextualHelpText:
-        'Choose the category that best represents your NFT content',
-    },
-  },
-});
+/**
+ * Provider interface (optional, for dynamic guidance)
+ */
+export interface FieldGuidanceProvider {
+  getFieldGuidance(
+    fieldName: string,
+    ctx: { toolName: string }
+  ): FieldGuidance | null;
+  getGlobalGuidance?(
+    toolName: string
+  ): ToolFieldConfiguration['globalGuidance'] | null;
+}

package/src/forms/form-generator.ts

@@ -187,11 +187,17 @@ export class FormGenerator {
     );
 
     const globalGuidance = fieldGuidanceRegistry.getGlobalGuidance(toolName);
-    let description = this.generateFormDescription(toolName, missingFields.size);
-    
+    let description = this.generateFormDescription(
+      toolName,
+      missingFields.size
+    );
+
     if (globalGuidance?.qualityStandards) {
-      description += '\n\nQuality Guidelines:\n' + 
-        globalGuidance.qualityStandards.map(standard => `• ${standard}`).join('\n');
+      description +=
+        '\n\nQuality Guidelines:\n' +
+        globalGuidance.qualityStandards
+          .map((standard) => `• ${standard}`)
+          .join('\n');
     }
 
     return {
@@ -203,7 +209,7 @@ export class FormGenerator {
       metadata: {
         toolName,
         missingFieldCount: missingFields.size,
-        globalGuidance
+        globalGuidance,
       },
     };
   }
@@ -453,8 +459,10 @@ export class FormGenerator {
   ): FormField {
     const type = this.mapFieldType(renderConfig?.fieldType, schema, fieldPath);
     const isRequired = this.isFieldRequired(schema, fieldPath || fieldName);
-    
-    const guidance = toolName ? fieldGuidanceRegistry.getFieldGuidance(toolName, fieldName) : null;
+
+    const guidance = toolName
+      ? fieldGuidanceRegistry.getFieldGuidance(toolName, fieldName)
+      : null;
     const finalType = guidance?.fieldTypeOverride || type;
 
     const field: FormField = {
@@ -474,7 +482,10 @@ export class FormGenerator {
       }
 
       if (guidance.predefinedOptions) {
-        field.options = [...(field.options || []), ...guidance.predefinedOptions];
+        field.options = [
+          ...(field.options || []),
+          ...guidance.predefinedOptions,
+        ];
       }
 
       if (guidance.contextualHelpText) {
@@ -482,7 +493,7 @@ export class FormGenerator {
       }
 
       if (guidance.warnings) {
-        field.warnings = guidance.warnings.map(w => w.message);
+        field.warnings = guidance.warnings.map((w) => w.message);
       }
 
       if (guidance.validationRules) {
@@ -491,7 +502,7 @@ export class FormGenerator {
           field.contextualGuidance = {
             qualityStandards: [],
             examples: guidance.suggestions || [],
-            avoidPatterns: qualityChecks.forbidTechnicalTerms || []
+            avoidPatterns: qualityChecks.forbidTechnicalTerms || [],
           };
 
           if (qualityChecks.minNonTechnicalWords) {
@@ -502,7 +513,9 @@ export class FormGenerator {
 
           if (qualityChecks.forbidTechnicalTerms) {
             field.contextualGuidance.qualityStandards?.push(
-              `Avoid technical terms like: ${qualityChecks.forbidTechnicalTerms.join(', ')}`
+              `Avoid technical terms like: ${qualityChecks.forbidTechnicalTerms.join(
+                ', '
+              )}`
             );
           }
         }
@@ -817,7 +830,10 @@ export class FormGenerator {
     zodSchema: z.ZodObject<z.ZodRawShape>,
     partialInput?: Record<string, unknown>,
     missingFields?: Set<string>
-  ): { jsonSchema: Record<string, unknown>; uiSchema: Record<string, unknown> } {
+  ): {
+    jsonSchema: Record<string, unknown>;
+    uiSchema: Record<string, unknown>;
+  } {
     const fullJsonSchema = zodToJsonSchema(zodSchema, {
       target: 'jsonSchema7',
     });

package/src/index.ts

@@ -26,3 +26,4 @@ export * from './services';
 export * from './langchain';
 export * from './tools';
 export * from './utils';
+export * from './runtime/wallet-bridge';

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[];
-}
+}