@hashgraphonline/standards-agent-kit 0.2.109 → 0.2.112

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hashgraphonline/standards-agent-kit",
-  "version": "0.2.109",
+  "version": "0.2.112",
   "description": "A modular SDK for building on-chain autonomous agents using Hashgraph Online Standards, including HCS-10 for agent discovery and communication.",
   "type": "module",
   "main": "./dist/cjs/standards-agent-kit.cjs",
@@ -89,7 +89,7 @@
   },
   "dependencies": {
     "@hashgraph/sdk": "^2.69.0",
-    "@hashgraphonline/standards-sdk": "0.0.164",
+    "@hashgraphonline/standards-sdk": "0.0.167",
     "@langchain/community": "^0.3.49",
     "@langchain/core": "^0.3.66",
     "@langchain/openai": "^0.6.3",

package/src/builders/hcs6/hcs6-builder.ts

@@ -0,0 +1,136 @@
+import { BaseServiceBuilder } from 'hedera-agent-kit';
+import type { HederaAgentKit } from 'hedera-agent-kit';
+import {
+  HCS6Client,
+  SDKHCS6ClientConfig,
+  HCS6CreateRegistryOptions,
+  HCS6RegisterEntryOptions,
+  HCS6QueryRegistryOptions,
+  HCS6RegisterOptions,
+  HCS6CreateHashinalOptions,
+  HCS6TopicRegistrationResponse,
+  HCS6RegistryOperationResponse,
+  HCS6TopicRegistry,
+  HCS6CreateHashinalResponse,
+  NetworkType,
+} from '@hashgraphonline/standards-sdk';
+
+/**
+ * Builder for HCS-6 operations that delegates to HCS6Client
+ */
+export class HCS6Builder extends BaseServiceBuilder {
+  protected hcs6Client?: HCS6Client;
+
+  constructor(hederaKit: HederaAgentKit) {
+    super(hederaKit);
+  }
+
+  /**
+   * Get or create HCS-6 client
+   */
+  protected async getHCS6Client(): Promise<HCS6Client> {
+    if (!this.hcs6Client) {
+      const operatorId = this.hederaKit.signer.getAccountId().toString();
+      const operatorPrivateKey = this.hederaKit.signer?.getOperatorPrivateKey()
+        ? this.hederaKit.signer.getOperatorPrivateKey().toStringRaw()
+        : '';
+
+      const network = this.hederaKit.client.network;
+      const networkType: NetworkType = network.toString().includes('mainnet')
+        ? 'mainnet'
+        : 'testnet';
+
+      const config: SDKHCS6ClientConfig = {
+        network: networkType,
+        operatorId: operatorId,
+        operatorKey: operatorPrivateKey,
+      };
+
+      this.hcs6Client = new HCS6Client(config);
+    }
+    return this.hcs6Client;
+  }
+
+  /**
+   * Create a new HCS-6 dynamic registry
+   * Note: This executes the transaction directly via HCS6Client
+   */
+  async createRegistry(
+    options: HCS6CreateRegistryOptions = {}
+  ): Promise<HCS6TopicRegistrationResponse> {
+    const client = await this.getHCS6Client();
+    return await client.createRegistry(options);
+  }
+
+  /**
+   * Register a new dynamic hashinal entry in an HCS-6 registry
+   */
+  async registerEntry(
+    registryTopicId: string,
+    options: HCS6RegisterEntryOptions
+  ): Promise<HCS6RegistryOperationResponse> {
+    const client = await this.getHCS6Client();
+    return await client.registerEntry(registryTopicId, options);
+  }
+
+  /**
+   * Query entries from an HCS-6 registry
+   */
+  async getRegistry(
+    topicId: string,
+    options: HCS6QueryRegistryOptions = {}
+  ): Promise<HCS6TopicRegistry> {
+    const client = await this.getHCS6Client();
+    return await client.getRegistry(topicId, options);
+  }
+
+  /**
+   * Create a complete dynamic hashinal with inscription and registry
+   */
+  async createHashinal(
+    options: HCS6CreateHashinalOptions
+  ): Promise<HCS6CreateHashinalResponse> {
+    const client = await this.getHCS6Client();
+    return await client.createHashinal(options);
+  }
+
+  /**
+   * Register a dynamic hashinal with combined inscription and registry creation
+   * This is the main method for creating and updating dynamic hashinals
+   */
+  async register(
+    options: HCS6RegisterOptions
+  ): Promise<HCS6CreateHashinalResponse> {
+    const client = await this.getHCS6Client();
+    return await client.register(options);
+  }
+
+  /**
+   * Submit a raw message to an HCS-6 topic
+   */
+  async submitMessage(
+    topicId: string,
+    payload: any
+  ): Promise<any> {
+    const client = await this.getHCS6Client();
+    return await client.submitMessage(topicId, payload);
+  }
+
+  /**
+   * Get topic info from mirror node
+   */
+  async getTopicInfo(topicId: string): Promise<any> {
+    const client = await this.getHCS6Client();
+    return await client.getTopicInfo(topicId);
+  }
+
+  /**
+   * Close the HCS-6 client
+   */
+  async close(): Promise<void> {
+    if (this.hcs6Client) {
+      this.hcs6Client.close();
+      this.hcs6Client = undefined;
+    }
+  }
+}

package/src/builders/hcs6/index.ts

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

package/src/builders/index.ts

@@ -1,4 +1,5 @@
 export * from './types';
 export * from './hcs10/hcs10-builder';
 export * from './hcs2/hcs2-builder';
+export * from './hcs6/hcs6-builder';
 export * from './inscriber/inscriber-builder';

package/src/tools/inscriber/InscribeFromBufferTool.ts

@@ -7,8 +7,8 @@ import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
  * Schema for inscribing from buffer
  */
 const inscribeFromBufferSchema = z.object({
-  base64Data: z.string().describe('Base64 encoded content to inscribe'),
-  fileName: z.string().describe('Name for the inscribed content'),
+  base64Data: z.string().min(1, 'Base64 data cannot be empty').describe('Base64 encoded content to inscribe. Must contain valid, non-empty content (minimum 10 bytes after decoding).'),
+  fileName: z.string().min(1, 'File name cannot be empty').describe('Name for the inscribed content. Required for all inscriptions.'),
   mimeType: z
     .string()
     .optional()
@@ -53,7 +53,7 @@ const inscribeFromBufferSchema = z.object({
  */
 export class InscribeFromBufferTool extends BaseInscriberQueryTool<typeof inscribeFromBufferSchema> {
   name = 'inscribeFromBuffer';
-  description = 'Inscribe content from a buffer/base64 data to the Hedera network. Useful for inscribing content that has been read into memory, including files accessed through MCP filesystem tools.';
+  description = 'Inscribe content that you already have (text, data, or files) to the Hedera network. Use this tool when you have content from: Wikipedia articles, MCP tool responses, text data, API responses, or any content you\'ve retrieved. Convert your content to base64 first. DO NOT use inscribeFromUrl for web page content - use this tool instead after retrieving the actual content.';
 
   get specificInputSchema() {
     return inscribeFromBufferSchema;
@@ -70,15 +70,44 @@ export class InscribeFromBufferTool extends BaseInscriberQueryTool<typeof inscri
     
     if (!params.base64Data || params.base64Data.trim() === '') {
       console.log(`[InscribeFromBufferTool] ERROR: No data provided`);
-      throw new Error('No data provided. Cannot inscribe empty content.');
+      throw new Error('No data provided. Cannot inscribe empty content. Please provide valid base64 encoded data.');
     }
 
-    const buffer = Buffer.from(params.base64Data, 'base64');
+    if (!params.fileName || params.fileName.trim() === '') {
+      console.log(`[InscribeFromBufferTool] ERROR: No fileName provided`);
+      throw new Error('No fileName provided. A valid fileName is required for inscription.');
+    }
+
+    let buffer: Buffer;
+    try {
+      buffer = Buffer.from(params.base64Data, 'base64');
+    } catch (error) {
+      console.log(`[InscribeFromBufferTool] ERROR: Invalid base64 data`);
+      throw new Error('Invalid base64 data provided. Please ensure the data is properly base64 encoded.');
+    }
+    
     console.log(`[InscribeFromBufferTool] Buffer length after conversion: ${buffer.length}`);
     
     if (buffer.length === 0) {
       console.log(`[InscribeFromBufferTool] ERROR: Buffer is empty after conversion`);
-      throw new Error('Buffer is empty. Cannot inscribe empty content.');
+      throw new Error('Buffer is empty after base64 conversion. The provided data appears to be invalid or empty.');
+    }
+
+    if (buffer.length < 10) {
+      console.log(`[InscribeFromBufferTool] WARNING: Buffer is very small (${buffer.length} bytes)`);
+      console.log(`[InscribeFromBufferTool] Buffer content preview: ${buffer.toString('utf8', 0, Math.min(buffer.length, 50))}`);
+      throw new Error(`Buffer content is too small (${buffer.length} bytes). This may indicate empty or invalid content. Please verify the source data contains actual content.`);
+    }
+
+    const isValidBase64 = /^[A-Za-z0-9+/]*={0,2}$/.test(params.base64Data);
+    if (!isValidBase64) {
+      console.log(`[InscribeFromBufferTool] ERROR: Invalid base64 format`);
+      throw new Error('Invalid base64 format. The data does not appear to be properly base64 encoded.');
+    }
+
+    if (buffer.toString('utf8', 0, Math.min(buffer.length, 100)).trim() === '') {
+      console.log(`[InscribeFromBufferTool] ERROR: Buffer contains only whitespace or empty content`);
+      throw new Error('Buffer contains only whitespace or empty content. Cannot inscribe meaningless data.');
     }
 
     const options: InscriptionOptions = {

package/src/tools/inscriber/InscribeFromFileTool.ts

@@ -9,7 +9,7 @@ import * as path from 'path';
  * Schema for inscribing from file
  */
 const inscribeFromFileSchema = z.object({
-  filePath: z.string().describe('The file path of the content to inscribe'),
+  filePath: z.string().min(1, 'File path cannot be empty').describe('The file path of the content to inscribe. Must point to a valid, non-empty file.'),
   mode: z
     .enum(['file', 'hashinal'])
     .optional()
@@ -49,7 +49,7 @@ export class InscribeFromFileTool extends BaseInscriberQueryTool<
 > {
   name = 'inscribeFromFile';
   description =
-    'Inscribe content from a local file to the Hedera network using a file path. For files accessed through MCP filesystem tools, consider reading the file content first and using inscribeFromBuffer instead.';
+    'Inscribe content from a local file to the Hedera network using a file path. IMPORTANT: Only use this tool when you have a valid file path to actual content. The file must exist and contain meaningful data (minimum 10 bytes). For files accessed through MCP filesystem tools, consider reading the file content first and using inscribeFromBuffer instead.';
 
   get specificInputSchema(): typeof inscribeFromFileSchema {
     return inscribeFromFileSchema;
@@ -76,19 +76,46 @@ export class InscribeFromFileTool extends BaseInscriberQueryTool<
 
       if (stats.size === 0) {
         throw new Error(
-          `File "${params.filePath}" is empty. Cannot inscribe empty files.`
+          `File "${params.filePath}" is empty (0 bytes). Cannot inscribe empty files.`
         );
       }
 
+      if (stats.size < 10) {
+        throw new Error(
+          `File "${params.filePath}" is too small (${stats.size} bytes). Files must contain at least 10 bytes of meaningful content.`
+        );
+      }
+
+      if (stats.size > 100 * 1024 * 1024) {
+        console.log(`[InscribeFromFileTool] WARNING: Large file detected (${(stats.size / (1024 * 1024)).toFixed(2)} MB)`);
+      }
+
       this.logger?.info('Reading file content...');
       fileContent = await fs.readFile(params.filePath);
       this.logger?.info(`Read ${fileContent.length} bytes from file`);
 
       if (!fileContent || fileContent.length === 0) {
         throw new Error(
-          `File "${params.filePath}" has no content. Cannot inscribe empty files.`
+          `File "${params.filePath}" has no content after reading. Cannot inscribe empty files.`
+        );
+      }
+
+      if (fileContent.length < 10) {
+        throw new Error(
+          `File "${params.filePath}" content is too small (${fileContent.length} bytes). Files must contain at least 10 bytes of meaningful content.`
         );
       }
+
+      const fileName = path.basename(params.filePath);
+      const mimeType = this.getMimeType(fileName);
+      if (mimeType.startsWith('text/') || mimeType === 'application/json') {
+        const textContent = fileContent.toString('utf8', 0, Math.min(fileContent.length, 1000));
+        if (textContent.trim() === '') {
+          throw new Error(
+            `File "${params.filePath}" contains only whitespace or empty content. Cannot inscribe meaningless data.`
+          );
+        }
+      }
     } catch (error) {
       if (error instanceof Error) {
         if (error.message.includes('ENOENT')) {

package/src/tools/inscriber/InscribeFromUrlTool.ts

@@ -42,7 +42,7 @@ const inscribeFromUrlSchema = z.object({
  */
 export class InscribeFromUrlTool extends BaseInscriberQueryTool<typeof inscribeFromUrlSchema> {
   name = 'inscribeFromUrl';
-  description = 'Inscribe content from a URL to the Hedera network';
+  description = 'Inscribe content directly from a URL that points to a downloadable file (PDF, image, JSON, etc). DO NOT use this for web pages like Wikipedia, Twitter, or GitHub pages. This tool is ONLY for direct file URLs like https://example.com/document.pdf or https://api.example.com/data.json. For content you already have (from Wikipedia, MCP tools, or text), use inscribeFromBuffer instead.';
 
   get specificInputSchema() {
     return inscribeFromUrlSchema;
@@ -52,6 +52,68 @@ export class InscribeFromUrlTool extends BaseInscriberQueryTool<typeof inscribeF
     params: z.infer<typeof inscribeFromUrlSchema>,
     _runManager?: CallbackManagerForToolRun
   ): Promise<unknown> {
+    console.log(`[DEBUG] InscribeFromUrlTool.executeQuery called with URL: ${params.url}`);
+    
+    if (!params.url || params.url.trim() === '') {
+      throw new Error('URL cannot be empty. Please provide a valid URL.');
+    }
+
+    try {
+      const urlObj = new URL(params.url);
+      if (!urlObj.protocol || !urlObj.host) {
+        throw new Error('Invalid URL format. Please provide a complete URL with protocol (http/https).');
+      }
+      if (!['http:', 'https:'].includes(urlObj.protocol)) {
+        throw new Error('Only HTTP and HTTPS URLs are supported for inscription.');
+      }
+    } catch (error) {
+      throw new Error(`Invalid URL: ${params.url}. Please provide a valid URL.`);
+    }
+
+    console.log(`[InscribeFromUrlTool] Validating URL content before inscription...`);
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), 10000);
+      
+      try {
+        const response = await fetch(params.url, {
+          method: 'HEAD',
+          signal: controller.signal,
+        });
+        
+        clearTimeout(timeoutId);
+        
+        if (!response.ok) {
+          throw new Error(`URL returned error status ${response.status}: ${response.statusText}. Cannot inscribe content from inaccessible URLs.`);
+        }
+
+        const contentLength = response.headers.get('content-length');
+        if (contentLength && parseInt(contentLength) === 0) {
+          throw new Error('URL returns empty content (Content-Length: 0). Cannot inscribe empty content.');
+        }
+
+        if (contentLength && parseInt(contentLength) < 10) {
+          throw new Error(`URL content is too small (${contentLength} bytes). Content must be at least 10 bytes.`);
+        }
+
+        const contentType = response.headers.get('content-type');
+        console.log(`[InscribeFromUrlTool] URL validation passed. Content-Type: ${contentType}, Content-Length: ${contentLength || 'unknown'}`);
+      } catch (fetchError) {
+        clearTimeout(timeoutId);
+        throw fetchError;
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        if (error.name === 'AbortError') {
+          console.log(`[InscribeFromUrlTool] Warning: URL validation timed out after 10 seconds. Proceeding with inscription attempt.`);
+        } else if (error.message.includes('URL returned error') || error.message.includes('empty content') || error.message.includes('too small')) {
+          throw error;
+        } else {
+          console.log(`[InscribeFromUrlTool] Warning: Could not validate URL with HEAD request: ${error.message}. Proceeding with inscription attempt.`);
+        }
+      }
+    }
+
     const options: InscriptionOptions = {
       mode: params.mode,
       metadata: params.metadata,