@hashgraphonline/standards-agent-kit 0.2.110 → 0.2.113

package/src/tools/hcs6/QueryDynamicRegistryTool.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { BaseHCS6QueryTool } from './base-hcs6-tools';
+import { HCS6QueryToolParams } from './hcs6-tool-params';
+import type { TransactionResponse } from 'hedera-agent-kit';
+
+/**
+ * Schema for querying a dynamic registry
+ */
+const QueryDynamicRegistrySchema = z.object({
+  topicId: z.string()
+    .describe('The registry topic ID to query'),
+  limit: z.number()
+    .optional()
+    .default(100)
+    .describe('Maximum number of entries to retrieve'),
+  order: z.enum(['asc', 'desc'])
+    .optional()
+    .default('desc')
+    .describe('Order of entries (desc shows latest first)'),
+  skip: z.number()
+    .optional()
+    .describe('Number of entries to skip'),
+});
+
+export type QueryDynamicRegistryInput = z.infer<typeof QueryDynamicRegistrySchema>;
+
+/**
+ * Tool for querying HCS-6 dynamic registries
+ */
+export class QueryDynamicRegistryTool extends BaseHCS6QueryTool<typeof QueryDynamicRegistrySchema> {
+  name = 'queryDynamicRegistry';
+  description = 'Query a dynamic registry to get the current state of a dynamic hashinal';
+  schema = QueryDynamicRegistrySchema;
+
+  constructor(params: HCS6QueryToolParams) {
+    super(params);
+  }
+
+  protected async _call(
+    params: QueryDynamicRegistryInput
+  ): Promise<TransactionResponse> {
+    try {
+      const registry = await this.hcs6Builder.getRegistry(params.topicId, {
+        limit: params.limit,
+        order: params.order,
+        skip: params.skip,
+      });
+
+      return {
+        status: 'success',
+        data: {
+          topicId: registry.topicId,
+          registryType: 'NON_INDEXED',
+          ttl: registry.ttl,
+          latestEntry: registry.latestEntry ? {
+            topicId: registry.latestEntry.message.t_id,
+            timestamp: registry.latestEntry.timestamp,
+            memo: registry.latestEntry.message.m,
+            sequence: registry.latestEntry.sequence,
+            payer: registry.latestEntry.payer,
+          } : null,
+          totalEntries: registry.entries.length,
+        },
+      };
+    } catch (error) {
+      return {
+        status: 'error',
+        message: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+}

package/src/tools/hcs6/RegisterDynamicHashinalTool.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import { BaseHCS6TransactionTool } from './base-hcs6-tools';
+import { HCS6TransactionToolParams } from './hcs6-tool-params';
+import type { TransactionResponse } from 'hedera-agent-kit';
+
+/**
+ * Schema for registering a dynamic hashinal
+ */
+const RegisterDynamicHashinalSchema = z.object({
+  metadata: z.record(z.unknown())
+    .describe('Metadata object for the hashinal (e.g., name, description, attributes)'),
+  data: z.object({
+    base64: z.string().optional().describe('Base64 encoded data for the hashinal'),
+    url: z.string().optional().describe('URL to fetch data from'),
+    mimeType: z.string().optional().describe('MIME type of the data'),
+  }).optional()
+    .describe('Data to inscribe with the hashinal'),
+  memo: z.string()
+    .optional()
+    .describe('Optional memo for the registration'),
+  ttl: z.number()
+    .min(3600)
+    .default(86400)
+    .describe('Time-to-live in seconds for the inscription'),
+  registryTopicId: z.string()
+    .optional()
+    .describe('Registry topic ID to use. If not provided, a new registry will be created'),
+  submitKey: z.string()
+    .optional()
+    .describe('Submit key for the registry (required if registry has a submit key)'),
+});
+
+export type RegisterDynamicHashinalInput = z.infer<typeof RegisterDynamicHashinalSchema>;
+
+/**
+ * Tool for registering (creating) dynamic hashinals
+ */
+export class RegisterDynamicHashinalTool extends BaseHCS6TransactionTool<typeof RegisterDynamicHashinalSchema> {
+  name = 'registerDynamicHashinal';
+  description = 'Create and register a new dynamic hashinal that can be updated over time';
+  schema = RegisterDynamicHashinalSchema;
+
+  constructor(params: HCS6TransactionToolParams) {
+    super(params);
+  }
+
+  protected async _call(
+    params: RegisterDynamicHashinalInput
+  ): Promise<TransactionResponse> {
+    try {
+      const result = await this.hcs6Builder.register({
+        metadata: params.metadata,
+        data: params.data,
+        memo: params.memo,
+        ttl: params.ttl,
+        registryTopicId: params.registryTopicId,
+        submitKey: params.submitKey,
+      });
+
+      if (!result.success || !result.registryTopicId || !result.inscriptionTopicId) {
+        throw new Error(result.error || 'Failed to register dynamic hashinal');
+      }
+
+      return {
+        status: 'success',
+        data: {
+          registryTopicId: result.registryTopicId,
+          inscriptionTopicId: result.inscriptionTopicId,
+          transactionId: result.transactionId,
+        },
+      };
+    } catch (error) {
+      return {
+        status: 'error',
+        message: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+}

package/src/tools/hcs6/UpdateDynamicHashinalTool.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { BaseHCS6TransactionTool } from './base-hcs6-tools';
+import { HCS6TransactionToolParams } from './hcs6-tool-params';
+import type { TransactionResponse } from 'hedera-agent-kit';
+
+/**
+ * Schema for updating a dynamic hashinal
+ */
+const UpdateDynamicHashinalSchema = z.object({
+  registryTopicId: z.string()
+    .describe('The registry topic ID that tracks this dynamic hashinal'),
+  metadata: z.record(z.unknown())
+    .describe('Updated metadata object for the hashinal'),
+  data: z.object({
+    base64: z.string().optional().describe('Base64 encoded data for the updated hashinal'),
+    url: z.string().optional().describe('URL to fetch updated data from'),
+    mimeType: z.string().optional().describe('MIME type of the data'),
+  }).optional()
+    .describe('Updated data to inscribe'),
+  memo: z.string()
+    .optional()
+    .describe('Optional memo for the update (e.g., "Level up", "Version 2.0")'),
+  submitKey: z.string()
+    .describe('Submit key for the registry (required to update)'),
+});
+
+export type UpdateDynamicHashinalInput = z.infer<typeof UpdateDynamicHashinalSchema>;
+
+/**
+ * Tool for updating dynamic hashinals
+ */
+export class UpdateDynamicHashinalTool extends BaseHCS6TransactionTool<typeof UpdateDynamicHashinalSchema> {
+  name = 'updateDynamicHashinal';
+  description = 'Update an existing dynamic hashinal with new content while maintaining the same registry';
+  schema = UpdateDynamicHashinalSchema;
+
+  constructor(params: HCS6TransactionToolParams) {
+    super(params);
+  }
+
+  protected async _call(
+    params: UpdateDynamicHashinalInput
+  ): Promise<TransactionResponse> {
+    try {
+      // Use the register method with the existing registry ID
+      const result = await this.hcs6Builder.register({
+        metadata: params.metadata,
+        data: params.data,
+        memo: params.memo,
+        registryTopicId: params.registryTopicId,
+        submitKey: params.submitKey,
+      });
+
+      if (!result.success) {
+        throw new Error(result.error || 'Failed to update dynamic hashinal');
+      }
+
+      return {
+        status: 'success',
+        data: {
+          registryTopicId: result.registryTopicId,
+          newInscriptionTopicId: result.inscriptionTopicId,
+          transactionId: result.transactionId,
+          updateMemo: params.memo,
+        },
+      };
+    } catch (error) {
+      return {
+        status: 'error',
+        message: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+}

package/src/tools/hcs6/base-hcs6-tools.ts

@@ -0,0 +1,63 @@
+import {
+  BaseHederaTransactionTool,
+  BaseHederaQueryTool,
+  BaseServiceBuilder,
+} from 'hedera-agent-kit';
+import { HCS6Builder } from '../../builders/hcs6/hcs6-builder';
+import {
+  HCS6TransactionToolParams,
+  HCS6QueryToolParams,
+} from './hcs6-tool-params';
+import { z } from 'zod';
+
+/**
+ * Base class for HCS6 transaction tools
+ */
+export abstract class BaseHCS6TransactionTool<
+  T extends z.ZodObject<
+    z.ZodRawShape,
+    z.UnknownKeysParam,
+    z.ZodTypeAny
+  > = z.ZodObject<z.ZodRawShape>
+> extends BaseHederaTransactionTool<T> {
+  protected hcs6Builder: HCS6Builder;
+  namespace = 'hcs6' as const;
+
+  constructor(params: HCS6TransactionToolParams) {
+    super(params);
+    this.hcs6Builder = params.hcs6Builder;
+  }
+
+  /**
+   * Override to return the HCS6Builder
+   */
+  protected getServiceBuilder(): BaseServiceBuilder {
+    return this.hcs6Builder;
+  }
+}
+
+/**
+ * Base class for HCS6 query tools
+ */
+export abstract class BaseHCS6QueryTool<
+  T extends z.ZodObject<
+    z.ZodRawShape,
+    z.UnknownKeysParam,
+    z.ZodTypeAny
+  > = z.ZodObject<z.ZodRawShape>
+> extends BaseHederaQueryTool<T> {
+  protected hcs6Builder: HCS6Builder;
+  namespace = 'hcs6' as const;
+
+  constructor(params: HCS6QueryToolParams) {
+    super(params);
+    this.hcs6Builder = params.hcs6Builder;
+  }
+
+  /**
+   * Override to return the HCS6Builder
+   */
+  protected getServiceBuilder(): BaseServiceBuilder {
+    return this.hcs6Builder;
+  }
+}

package/src/tools/hcs6/hcs6-tool-params.ts

@@ -0,0 +1,21 @@
+import { HederaAgentKit } from 'hedera-agent-kit';
+import type { BasePluginContext } from 'hedera-agent-kit';
+import { HCS6Builder } from '../../builders/hcs6/hcs6-builder';
+
+/**
+ * Parameters for HCS6 transaction tools
+ */
+export interface HCS6TransactionToolParams {
+  hederaKit: HederaAgentKit;
+  hcs6Builder: HCS6Builder;
+  logger?: BasePluginContext['logger'];
+}
+
+/**
+ * Parameters for HCS6 query tools
+ */
+export interface HCS6QueryToolParams {
+  hederaKit: HederaAgentKit;
+  hcs6Builder: HCS6Builder;
+  logger?: BasePluginContext['logger'];
+}

package/src/tools/hcs6/index.ts

@@ -0,0 +1,6 @@
+export * from './base-hcs6-tools';
+export * from './hcs6-tool-params';
+export * from './CreateDynamicRegistryTool';
+export * from './RegisterDynamicHashinalTool';
+export * from './UpdateDynamicHashinalTool';
+export * from './QueryDynamicRegistryTool';

package/src/tools/index.ts

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

package/src/tools/inscriber/InscribeFromBufferTool.ts

@@ -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. IMPORTANT: Only use this tool when you have actual content to inscribe. The base64Data must contain valid, non-empty content (minimum 10 bytes). Useful for inscribing content that has been read into memory, including files accessed through MCP filesystem tools. Always verify the content exists and is meaningful before attempting inscription.';
+  description = 'Inscribe content that you already have retrieved or generated. ALWAYS use this tool for: web page articles (after using MCP tools), API responses, text data, or any content from MCP tools. Steps: 1) Retrieve content using appropriate tool, 2) Convert to base64, 3) Use this tool. NEVER use inscribeFromUrl for web pages - that tool is ONLY for direct file downloads like PDFs or images.';
 
   get specificInputSchema() {
     return inscribeFromBufferSchema;

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. IMPORTANT: Only use this tool when you have a valid URL pointing to actual content. The URL must be accessible and return meaningful data. The tool will validate that the content exists and is not empty before inscription.';
+  description = 'Inscribe content ONLY from URLs that point directly to downloadable files (PDF, image, JSON, ZIP, etc). This tool will FAIL for web pages, news sites, or social media. Examples of VALID URLs: https://example.com/document.pdf, https://cdn.example.com/image.jpg, https://api.example.com/data.json. For web page articles or any content you retrieve via MCP tools, you MUST use inscribeFromBuffer instead after retrieving the content.';
 
   get specificInputSchema() {
     return inscribeFromUrlSchema;
@@ -76,18 +76,32 @@ export class InscribeFromUrlTool extends BaseInscriberQueryTool<typeof inscribeF
       const timeoutId = setTimeout(() => controller.abort(), 10000);
       
       try {
-        const response = await fetch(params.url, {
+        // First try HEAD request
+        const headResponse = 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.`);
+        if (!headResponse.ok) {
+          throw new Error(`URL returned error status ${headResponse.status}: ${headResponse.statusText}. Cannot inscribe content from inaccessible URLs.`);
         }
 
-        const contentLength = response.headers.get('content-length');
+        const contentType = headResponse.headers.get('content-type') || '';
+        const contentLength = headResponse.headers.get('content-length');
+        
+        // Check if content type indicates HTML/web page
+        const webPageContentTypes = [
+          'text/html',
+          'application/xhtml+xml',
+          'text/xml'
+        ];
+        
+        if (webPageContentTypes.some(type => contentType.toLowerCase().includes(type))) {
+          throw new Error(`URL returns HTML/web page content (Content-Type: ${contentType}). This tool only works with direct file URLs (PDFs, images, JSON, etc.). For web page content, first retrieve the content using the appropriate MCP tool or web scraper, then use inscribeFromBuffer to inscribe it.`);
+        }
+        
         if (contentLength && parseInt(contentLength) === 0) {
           throw new Error('URL returns empty content (Content-Length: 0). Cannot inscribe empty content.');
         }
@@ -95,8 +109,47 @@ export class InscribeFromUrlTool extends BaseInscriberQueryTool<typeof inscribeF
         if (contentLength && parseInt(contentLength) < 10) {
           throw new Error(`URL content is too small (${contentLength} bytes). Content must be at least 10 bytes.`);
         }
+        
+        // If HEAD doesn't provide content-type, do a partial GET to check
+        if (!contentType || contentType === 'application/octet-stream') {
+          console.log(`[InscribeFromUrlTool] Content-Type unclear, fetching first 1KB to verify...`);
+          
+          const getController = new AbortController();
+          const getTimeoutId = setTimeout(() => getController.abort(), 5000);
+          
+          try {
+            const getResponse = await fetch(params.url, {
+              signal: getController.signal,
+              headers: {
+                'Range': 'bytes=0-1023' // Get first 1KB
+              }
+            });
+            
+            clearTimeout(getTimeoutId);
+            
+            if (getResponse.ok || getResponse.status === 206) { // 206 is partial content
+              const buffer = await getResponse.arrayBuffer();
+              const bytes = new Uint8Array(buffer);
+              const text = new TextDecoder('utf-8', { fatal: false }).decode(bytes.slice(0, 512));
+              
+              // Check if it looks like HTML
+              if (text.toLowerCase().includes('<!doctype html') || 
+                  text.toLowerCase().includes('<html') ||
+                  text.match(/<meta\s+[^>]*>/i) ||
+                  text.match(/<title>/i)) {
+                throw new Error(`URL returns HTML content. This tool only works with direct file URLs. For web page content, first retrieve it using the appropriate tool, then use inscribeFromBuffer.`);
+              }
+            }
+          } catch (getError) {
+            clearTimeout(getTimeoutId);
+            if (getError instanceof Error && getError.message.includes('HTML content')) {
+              throw getError;
+            }
+            // If partial GET fails, continue anyway
+            console.log(`[InscribeFromUrlTool] Could not perform partial GET validation: ${getError instanceof Error ? getError.message : 'Unknown error'}`);
+          }
+        }
 
-        const contentType = response.headers.get('content-type');
         console.log(`[InscribeFromUrlTool] URL validation passed. Content-Type: ${contentType}, Content-Length: ${contentLength || 'unknown'}`);
       } catch (fetchError) {
         clearTimeout(timeoutId);
@@ -106,7 +159,7 @@ export class InscribeFromUrlTool extends BaseInscriberQueryTool<typeof inscribeF
       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')) {
+        } else if (error.message.includes('URL returned error') || error.message.includes('empty content') || error.message.includes('too small') || error.message.includes('HTML')) {
           throw error;
         } else {
           console.log(`[InscribeFromUrlTool] Warning: Could not validate URL with HEAD request: ${error.message}. Proceeding with inscription attempt.`);