@hashgraphonline/standards-agent-kit 0.2.134 → 0.2.136

package/dist/umd/tools/inscriber/InscribeHashinalTool.d.ts

@@ -37,6 +37,7 @@ declare const inscribeHashinalSchema: import('../..').ZodSchemaWithRender<{
 export declare class InscribeHashinalTool extends BaseInscriberQueryTool implements FormValidatable {
     name: string;
     description: string;
+    getEntityResolutionPreferences(): Record<string, string>;
     get specificInputSchema(): z.ZodObject<z.ZodRawShape>;
     private _schemaWithRenderConfig?;
     get schema(): z.ZodObject<z.ZodRawShape>;
@@ -50,14 +51,6 @@ export declare class InscribeHashinalTool extends BaseInscriberQueryTool impleme
      * Returns the focused schema for form generation
      */
     getFormSchema(): z.ZodObject<z.ZodRawShape>;
-    /**
-     * Implementation of FormValidatable interface
-     * Validates metadata quality and provides detailed feedback
-     */
-    validateMetadataQuality(input: unknown): {
-        needsForm: boolean;
-        reason: string;
-    };
     protected executeQuery(params: z.infer<typeof inscribeHashinalSchema>, _runManager?: CallbackManagerForToolRun): Promise<InscriptionResponse>;
     /**
      * Creates HashLink block configuration for Hashinal inscriptions.

package/dist/umd/tools/inscriber/base-inscriber-tools.d.ts

@@ -4,12 +4,22 @@ import { InscriberTransactionToolParams, InscriberQueryToolParams } from './insc
 import { ContentResolverInterface } from '../../types/content-resolver';
 import { InscriptionInput, InscriptionOptions, QuoteResult } from '@hashgraphonline/standards-sdk';
 import { z } from 'zod';
+/**
+ * Event emitted when an entity is created during inscription
+ */
+export interface EntityCreationEvent {
+    entityId: string;
+    entityName: string;
+    entityType: string;
+    transactionId?: string;
+}
 /**
  * Base class for Inscriber transaction tools
  */
 export declare abstract class BaseInscriberTransactionTool<T extends z.ZodObject<z.ZodRawShape, z.UnknownKeysParam, z.ZodTypeAny> = z.ZodObject<z.ZodRawShape>> extends BaseHederaTransactionTool<T> {
     protected inscriberBuilder: InscriberBuilder;
     protected contentResolver: ContentResolverInterface | null;
+    protected onEntityCreated?: (event: EntityCreationEvent) => void;
     namespace: "inscriber";
     constructor(params: InscriberTransactionToolParams);
     /**
@@ -20,6 +30,10 @@ export declare abstract class BaseInscriberTransactionTool<T extends z.ZodObject
      * Get content resolver with fallback to registry
      */
     protected getContentResolver(): ContentResolverInterface | null;
+    /**
+     * Set entity creation handler for automatic entity storage
+     */
+    setEntityCreationHandler(handler: (event: EntityCreationEvent) => void): void;
     /**
      * Generate a quote for an inscription without executing it
      * @param input - The inscription input data
@@ -34,6 +48,7 @@ export declare abstract class BaseInscriberTransactionTool<T extends z.ZodObject
 export declare abstract class BaseInscriberQueryTool<T extends z.ZodObject<z.ZodRawShape, z.UnknownKeysParam, z.ZodTypeAny> = z.ZodObject<z.ZodRawShape>> extends BaseHederaQueryTool<T> {
     protected inscriberBuilder: InscriberBuilder;
     protected contentResolver: ContentResolverInterface | null;
+    protected onEntityCreated?: (event: EntityCreationEvent) => void;
     namespace: "inscriber";
     constructor(params: InscriberQueryToolParams);
     /**
@@ -44,6 +59,10 @@ export declare abstract class BaseInscriberQueryTool<T extends z.ZodObject<z.Zod
      * Get content resolver with fallback to registry
      */
     protected getContentResolver(): ContentResolverInterface | null;
+    /**
+     * Set entity creation handler for automatic entity storage
+     */
+    setEntityCreationHandler(handler: (event: EntityCreationEvent) => void): void;
     /**
      * Generate a quote for an inscription without executing it
      * @param input - The inscription input data

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hashgraphonline/standards-agent-kit",
-  "version": "0.2.134",
+  "version": "0.2.136",
   "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",
@@ -90,7 +90,7 @@
   },
   "dependencies": {
     "@hashgraph/sdk": "^2.69.0",
-    "@hashgraphonline/standards-sdk": "0.0.183",
+    "@hashgraphonline/standards-sdk": "0.0.187",
     "@kiloscribe/inscription-sdk": "^1.0.59",
     "@langchain/community": "^0.3.5",
     "@langchain/core": "^0.3.71",

package/src/interfaces/FormValidatable.ts

@@ -19,27 +19,20 @@ export interface FormValidatable {
   getFormSchema(): z.ZodSchema;
 
   /**
-   * Optional method to validate metadata quality and provide detailed feedback
-   * @param input The input data to analyze
-   * @returns Object indicating if form is needed and the reason
-   */
-  validateMetadataQuality?(input: unknown): { needsForm: boolean; reason: string };
-
-  /**
-   * Optional method to define which fields are essential for this tool
+   * Defines which fields are essential for this tool
    * Essential fields are always shown in forms even if marked as optional
    * @returns Array of field names that are essential for user experience
    */
-  getEssentialFields?(): string[];
+  getEssentialFields(): string[];
 
   /**
-   * Optional method to determine if a field value should be considered empty
+   * Determines if a field value should be considered empty
    * Allows tools to define custom empty logic for their specific data types
    * @param fieldName The name of the field
    * @param value The value to check
    * @returns true if the field should be considered empty
    */
-  isFieldEmpty?(fieldName: string, value: unknown): boolean;
+  isFieldEmpty(fieldName: string, value: unknown): boolean;
 }
 
 /**
@@ -51,7 +44,11 @@ export function isFormValidatable(tool: unknown): tool is FormValidatable {
     typeof tool === 'object' &&
     'shouldGenerateForm' in tool &&
     'getFormSchema' in tool &&
+    'getEssentialFields' in tool &&
+    'isFieldEmpty' in tool &&
     typeof (tool as FormValidatable).shouldGenerateForm === 'function' &&
-    typeof (tool as FormValidatable).getFormSchema === 'function'
+    typeof (tool as FormValidatable).getFormSchema === 'function' &&
+    typeof (tool as FormValidatable).getEssentialFields === 'function' &&
+    typeof (tool as FormValidatable).isFieldEmpty === 'function'
   );
 }

package/src/tools/inscriber/InscribeFromBufferTool.ts

@@ -59,8 +59,8 @@ export class InscribeFromBufferTool extends BaseInscriberQueryTool<
       waitForConfirmation: params.quoteOnly
         ? false
         : params.waitForConfirmation ?? true,
-      waitMaxAttempts: 10,
-      waitIntervalMs: 3000,
+      waitMaxAttempts: 60,
+      waitIntervalMs: 5000,
       apiKey: params.apiKey,
       network: this.inscriberBuilder['hederaKit'].client.network
         .toString()

package/src/tools/inscriber/InscribeFromUrlTool.ts

@@ -242,8 +242,8 @@ export class InscribeFromUrlTool extends BaseInscriberQueryTool<
       waitForConfirmation: params.quoteOnly
         ? false
         : params.waitForConfirmation ?? true,
-      waitMaxAttempts: 10,
-      waitIntervalMs: 3000,
+      waitMaxAttempts: 60,
+      waitIntervalMs: 5000,
       apiKey: params.apiKey,
       network: this.inscriberBuilder['hederaKit'].client.network
         .toString()

package/src/tools/inscriber/InscribeHashinalTool.ts

@@ -15,7 +15,6 @@ import {
   extendZodSchema,
   renderConfigs,
 } from '../../lib/zod-render/schema-extension';
-import type { EnhancedRenderConfig } from '../../lib/zod-render/types';
 import {
   createInscriptionSuccess,
   createInscriptionQuote,
@@ -38,7 +37,7 @@ const HASHLINK_BLOCK_CONFIG = {
     hashLink: 'hcs://12/0.0.TBD',
     template: '0.0.TBD',
   },
-} as const;
+};
 
 /**
  * Gets the appropriate HashLink block configuration for the specified network.
@@ -47,23 +46,19 @@ const HASHLINK_BLOCK_CONFIG = {
  * @param network The network type to get configuration for
  * @returns Network-specific block configuration with blockId, hashLink, and template
  */
-function getHashLinkBlockId(network: 'mainnet' | 'testnet') {
-  const config = HASHLINK_BLOCK_CONFIG[network];
+// @ts-ignore - keep untyped to satisfy mixed parser while using runtime narrowing
+function getHashLinkBlockId(network) {
+  const config =
+    network === 'mainnet'
+      ? HASHLINK_BLOCK_CONFIG.mainnet
+      : HASHLINK_BLOCK_CONFIG.testnet;
   if (!config || config.blockId === '0.0.TBD') {
     return HASHLINK_BLOCK_CONFIG.testnet;
   }
   return config;
 }
 
-/**
- * Result of HCS-12 block lookup
- */
-interface HCS12BlockResult {
-  blockId: string;
-  hashLink: string;
-  template: string;
-  attributes: Record<string, unknown>;
-}
+// Note: Using inline return type annotations to avoid parser issues with interface declarations
 
 /**
  * Schema for inscribing Hashinal NFT
@@ -210,6 +205,17 @@ export class InscribeHashinalTool
   description =
     'Tool for inscribing Hashinal NFTs. CRITICAL: When user provides content (url/contentRef/base64Data), call with ONLY the content parameters - DO NOT auto-generate name, description, creator, or attributes. A form will be automatically shown to collect metadata from the user. Only include metadata parameters if the user explicitly provided them in their message.';
 
+  // Declare entity resolution preferences to preserve user-specified literal fields
+  getEntityResolutionPreferences(): Record<string, string> {
+    return {
+      name: 'literal',
+      description: 'literal',
+      creator: 'literal',
+      attributes: 'literal',
+      properties: 'literal',
+    };
+  }
+
   get specificInputSchema(): z.ZodObject<z.ZodRawShape> {
     const baseSchema =
       (inscribeHashinalSchema as z.ZodType & { _def?: { schema?: z.ZodType } })
@@ -349,12 +355,7 @@ export class InscribeHashinalTool
             })
           )
         )
-          .withRender(
-            renderConfigs.array(
-              'NFT Attributes',
-              'Attribute'
-            ) as EnhancedRenderConfig
-          )
+          .withRender(renderConfigs.array('NFT Attributes', 'Attribute'))
           .optional()
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           .describe('Collectible traits and characteristics.'),
@@ -378,35 +379,6 @@ export class InscribeHashinalTool
     return focusedSchema as unknown as z.ZodObject<z.ZodRawShape>;
   }
 
-  /**
-   * Implementation of FormValidatable interface
-   * Validates metadata quality and provides detailed feedback
-   */
-  validateMetadataQuality(input: unknown): {
-    needsForm: boolean;
-    reason: string;
-  } {
-    const inputObj = input as Record<string, unknown>;
-    const hasRequiredMetadata = !!(
-      inputObj.name &&
-      inputObj.description &&
-      inputObj.creator
-    );
-
-    if (!hasRequiredMetadata) {
-      return {
-        needsForm: true,
-        reason:
-          'Missing essential metadata (name, description, creator) for NFT creation',
-      };
-    }
-
-    return {
-      needsForm: false,
-      reason: 'All required metadata fields present',
-    };
-  }
-
   protected async executeQuery(
     params: z.infer<typeof inscribeHashinalSchema>,
     _runManager?: CallbackManagerForToolRun
@@ -470,7 +442,7 @@ export class InscribeHashinalTool
       waitForConfirmation: params.quoteOnly
         ? false
         : params.waitForConfirmation ?? true,
-      waitMaxAttempts: 30,
+      waitMaxAttempts: 60,
       waitIntervalMs: 5000,
       network: this.inscriberBuilder['hederaKit'].client.network
         .toString()
@@ -602,6 +574,14 @@ export class InscribeHashinalTool
           },
         });
 
+        this.onEntityCreated?.({
+          entityId: jsonTopicId || imageTopicId || 'unknown',
+          entityName: params.name || 'Unnamed Inscription',
+          entityType: 'topicId',
+          transactionId: (result.result as { transactionId?: string })
+            ?.transactionId,
+        });
+
         if (params.withHashLinkBlocks) {
           try {
             const blockData = await this.createHashLinkBlock(
@@ -659,6 +639,14 @@ export class InscribeHashinalTool
               },
             });
 
+            this.onEntityCreated?.({
+              entityId: jsonTopicId || imageTopicId || 'unknown',
+              entityName: params.name || 'Unnamed Inscription',
+              entityType: 'topicId',
+              transactionId: (result.result as { transactionId?: string })
+                ?.transactionId,
+            });
+
             if (params.withHashLinkBlocks) {
               try {
                 const blockData = await this.createHashLinkBlock(
@@ -768,7 +756,12 @@ export class InscribeHashinalTool
   private async createHashLinkBlock(
     response: ReturnType<typeof createInscriptionSuccess>,
     _mimeType?: string
-  ): Promise<HCS12BlockResult> {
+  ): Promise<{
+    blockId: string;
+    hashLink: string;
+    template: string;
+    attributes: Record<string, unknown>;
+  }> {
     const clientNetwork = this.inscriberBuilder['hederaKit'].client.network
       .toString()
       .includes('mainnet')

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

@@ -16,6 +16,16 @@ import {
 } from '@hashgraphonline/standards-sdk';
 import { z } from 'zod';
 
+/**
+ * Event emitted when an entity is created during inscription
+ */
+export interface EntityCreationEvent {
+  entityId: string;
+  entityName: string;
+  entityType: string;
+  transactionId?: string;
+}
+
 /**
  * Base class for Inscriber transaction tools
  */
@@ -28,6 +38,7 @@ export abstract class BaseInscriberTransactionTool<
 > extends BaseHederaTransactionTool<T> {
   protected inscriberBuilder: InscriberBuilder;
   protected contentResolver: ContentResolverInterface | null;
+  protected onEntityCreated?: (event: EntityCreationEvent) => void;
   namespace = 'inscriber' as const;
 
   constructor(params: InscriberTransactionToolParams) {
@@ -50,6 +61,13 @@ export abstract class BaseInscriberTransactionTool<
     return this.contentResolver;
   }
 
+  /**
+   * Set entity creation handler for automatic entity storage
+   */
+  setEntityCreationHandler(handler: (event: EntityCreationEvent) => void): void {
+    this.onEntityCreated = handler;
+  }
+
   /**
    * Generate a quote for an inscription without executing it
    * @param input - The inscription input data
@@ -93,6 +111,7 @@ export abstract class BaseInscriberQueryTool<
 > extends BaseHederaQueryTool<T> {
   protected inscriberBuilder: InscriberBuilder;
   protected contentResolver: ContentResolverInterface | null;
+  protected onEntityCreated?: (event: EntityCreationEvent) => void;
   namespace = 'inscriber' as const;
 
   constructor(params: InscriberQueryToolParams) {
@@ -115,6 +134,13 @@ export abstract class BaseInscriberQueryTool<
     return this.contentResolver;
   }
 
+  /**
+   * Set entity creation handler for automatic entity storage
+   */
+  setEntityCreationHandler(handler: (event: EntityCreationEvent) => void): void {
+    this.onEntityCreated = handler;
+  }
+
   /**
    * Generate a quote for an inscription without executing it
    * @param input - The inscription input data

package/src/types/inscription-response.ts

@@ -131,9 +131,9 @@ export function createInscriptionSuccess(params: {
     },
     metadata,
     nextSteps: {
-      primary: 'Use the HRL below as metadata when minting your NFT',
+      primary: 'CRITICAL: When minting NFTs, use ONLY the mintingMetadata value as a single string in the metadata array. Do NOT create JSON objects.',
       context:
-        'The HRL (Hedera Resource Locator) is the standardized way to reference your inscribed content in NFT metadata.',
+        'The metadata parameter for minting should be exactly: ["' + hrl + '"] - just the HRL string in an array, nothing else.',
       mintingMetadata: hrl,
     },
   };