@hashgraphonline/standards-agent-kit 0.2.119 → 0.2.121

package/src/tools/inscriber/InscribeFromBufferTool.ts

@@ -1,18 +1,21 @@
 import { z } from 'zod';
 import { BaseInscriberQueryTool } from './base-inscriber-tools';
-import { InscriptionOptions } from '@hashgraphonline/standards-sdk';
+import { InscriptionOptions, ContentResolverRegistry } from '@hashgraphonline/standards-sdk';
 import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+import { loadConfig } from '../../config/ContentReferenceConfig';
 
-/**
- * Schema for inscribing from buffer
- */
 const inscribeFromBufferSchema = z.object({
-  base64Data: z.string().min(1, 'Data cannot be empty').describe('The FULL content to inscribe as plain text or base64. When asked to "inscribe it" after retrieving content, pass ALL the content you retrieved here as plain text - NOT a summary, NOT URLs, NOT truncated. Example: if you fetched Wikipedia articles, pass the complete article text you received.'),
-  fileName: z.string().min(1, 'File name cannot be empty').describe('Name for the inscribed content. Required for all inscriptions.'),
-  mimeType: z
+  base64Data: z
     .string()
-    .optional()
-    .describe('MIME type of the content'),
+    .min(1, 'Data cannot be empty')
+    .describe(
+      'The content to inscribe. Accept BOTH plain text AND base64. Also accepts content reference IDs in format "content-ref:[id]". When user says "inscribe it" or "inscribe the content", use the EXACT content from your previous message or from MCP tool results. DO NOT generate new content. DO NOT create repetitive text. Pass the actual search results or other retrieved content EXACTLY as you received it.'
+    ),
+  fileName: z
+    .string()
+    .min(1, 'File name cannot be empty')
+    .describe('Name for the inscribed content. Required for all inscriptions.'),
+  mimeType: z.string().optional().describe('MIME type of the content'),
   mode: z
     .enum(['file', 'hashinal'])
     .optional()
@@ -40,20 +43,20 @@ const inscribeFromBufferSchema = z.object({
     .int()
     .positive()
     .optional()
-    .describe('Timeout in milliseconds for inscription (default: no timeout - waits until completion)'),
-  apiKey: z
-    .string()
-    .optional()
-    .describe('API key for inscription service'),
+    .describe(
+      'Timeout in milliseconds for inscription (default: no timeout - waits until completion)'
+    ),
+  apiKey: z.string().optional().describe('API key for inscription service'),
 });
 
-
-/**
- * Tool for inscribing content from buffer
- */
-export class InscribeFromBufferTool extends BaseInscriberQueryTool<typeof inscribeFromBufferSchema> {
+export class InscribeFromBufferTool extends BaseInscriberQueryTool<
+  typeof inscribeFromBufferSchema
+> {
   name = 'inscribeFromBuffer';
-  description = 'PRIMARY inscription tool for ANY content you have already retrieved. USE THIS when asked to "inscribe it" after fetching content from MCP tools, search results, or any text data. Pass THE FULL CONTENT as plain text in base64Data field - the tool accepts both plain text and base64. CRITICAL: Pass the COMPLETE content you retrieved, NOT a summary or truncated version. Example: If you fetched Wikipedia articles with full text, pass ALL that text here as plain text.';
+  description =
+    'Inscribe content that you have already retrieved or displayed. When user says "inscribe it" after you showed search results or other content, use THIS tool. The base64Data field accepts PLAIN TEXT (not just base64) and content reference IDs in format "content-ref:[id]". Pass the EXACT content from your previous response or MCP tool output. DO NOT generate new content or create repetitive text. Content references are automatically resolved to the original content for inscription.';
+
+  private config = loadConfig();
 
   get specificInputSchema() {
     return inscribeFromBufferSchema;
@@ -63,129 +66,245 @@ export class InscribeFromBufferTool extends BaseInscriberQueryTool<typeof inscri
     params: z.infer<typeof inscribeFromBufferSchema>,
     _runManager?: CallbackManagerForToolRun
   ): Promise<unknown> {
-    console.log(`[DEBUG] InscribeFromBufferTool.executeQuery called`);
-    console.log(`[DEBUG] Buffer tool received base64Data length: ${params.base64Data?.length || 0}`);
-    console.log(`[DEBUG] Buffer tool fileName: ${params.fileName}`);
-    console.log(`[DEBUG] Buffer tool mimeType: ${params.mimeType}`);
-    
+    this.validateInput(params);
+
+    const resolvedContent = await this.resolveContent(
+      params.base64Data,
+      params.mimeType,
+      params.fileName
+    );
+
+    this.validateContent(resolvedContent.buffer);
+
+    const buffer = resolvedContent.buffer;
+    const resolvedMimeType = resolvedContent.mimeType || params.mimeType;
+    const resolvedFileName = resolvedContent.fileName || params.fileName;
+
+    const options: InscriptionOptions = {
+      mode: params.mode,
+      metadata: params.metadata,
+      tags: params.tags,
+      chunkSize: params.chunkSize,
+      waitForConfirmation: params.waitForConfirmation ?? true,
+      waitMaxAttempts: 10,
+      waitIntervalMs: 3000,
+      apiKey: params.apiKey,
+      network: this.inscriberBuilder['hederaKit'].client.network
+        .toString()
+        .includes('mainnet')
+        ? 'mainnet'
+        : 'testnet',
+    };
+
+    const timeoutMs =
+      params.timeoutMs || (options.waitForConfirmation ? 60000 : undefined);
+
+    try {
+      const result = await this.executeInscription(
+        buffer,
+        resolvedFileName,
+        resolvedMimeType,
+        options,
+        timeoutMs
+      );
+      return this.formatInscriptionResult(result, options);
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error
+          ? error.message
+          : 'Failed to inscribe from buffer';
+      throw new Error(`Inscription failed: ${errorMessage}`);
+    }
+  }
+
+  private validateInput(
+    params: z.infer<typeof inscribeFromBufferSchema>
+  ): void {
     if (!params.base64Data || params.base64Data.trim() === '') {
-      console.log(`[InscribeFromBufferTool] ERROR: No data provided`);
-      throw new Error('No data provided. Cannot inscribe empty content. Please provide valid base64 encoded data.');
+      throw new Error(
+        'No data provided. Cannot inscribe empty content. Please provide valid content, plain text, base64 encoded data, or a content reference ID.'
+      );
     }
 
     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.');
+      throw new Error(
+        'No fileName provided. A valid fileName is required for inscription.'
+      );
     }
+  }
 
-    let buffer: Buffer;
-    
-    // First check if it's valid base64
-    const isValidBase64 = /^[A-Za-z0-9+/]*={0,2}$/.test(params.base64Data);
-    
-    if (isValidBase64) {
-      // Try to decode as base64
-      try {
-        buffer = Buffer.from(params.base64Data, 'base64');
-        console.log(`[InscribeFromBufferTool] Successfully decoded base64 data`);
-      } catch (error) {
-        console.log(`[InscribeFromBufferTool] ERROR: Failed to decode base64`);
-        throw new Error('Failed to decode base64 data. Please ensure the data is properly encoded.');
-      }
-    } else {
-      // Not base64, treat as plain text and encode it
-      console.log(`[InscribeFromBufferTool] WARNING: Data is not base64 encoded, treating as plain text`);
-      buffer = Buffer.from(params.base64Data, 'utf8');
-      console.log(`[InscribeFromBufferTool] Converted plain text to buffer`);
-    }
-    
-    console.log(`[InscribeFromBufferTool] Buffer length after conversion: ${buffer.length}`);
-    
+  private validateContent(buffer: Buffer): void {
     if (buffer.length === 0) {
-      console.log(`[InscribeFromBufferTool] ERROR: Buffer is empty after conversion`);
-      throw new Error('Buffer is empty after conversion. The provided data appears to be invalid or empty.');
+      throw new Error(
+        'Buffer is empty after 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.`);
+    if (buffer.length > this.config.maxInscriptionSize) {
+      const maxSizeKB = Math.round(this.config.maxInscriptionSize / 1024);
+      const bufferSizeKB = Math.round(buffer.length / 1024);
+      throw new Error(
+        `Content is too large for inscription (${bufferSizeKB}KB, max ${maxSizeKB}KB). Please summarize or extract key information before inscribing.`
+      );
     }
 
-    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.');
+    if (buffer.length < this.config.minContentSize) {
+      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.`
+      );
+    }
+
+    if (
+      buffer.toString('utf8', 0, Math.min(buffer.length, 100)).trim() === ''
+    ) {
+      throw new Error(
+        'Buffer contains only whitespace or empty content. Cannot inscribe meaningless data.'
+      );
     }
 
-    // Check for empty HTML pattern (just links with no content)
     const contentStr = buffer.toString('utf8');
     const emptyHtmlPattern = /<a\s+href=["'][^"']+["']\s*>\s*<\/a>/i;
-    const hasOnlyEmptyLinks = emptyHtmlPattern.test(contentStr) && 
-                              contentStr.replace(/<[^>]+>/g, '').trim().length < 50;
-    
+    const hasOnlyEmptyLinks =
+      emptyHtmlPattern.test(contentStr) &&
+      contentStr.replace(/<[^>]+>/g, '').trim().length < 50;
+
     if (hasOnlyEmptyLinks) {
-      console.log(`[InscribeFromBufferTool] ERROR: Buffer contains empty HTML with just links and no content`);
-      throw new Error('Buffer contains empty HTML with only links and no actual content. When inscribing content from external sources, use the actual article text you retrieved, not empty HTML with links.');
+      throw new Error(
+        'Buffer contains empty HTML with only links and no actual content. When inscribing content from external sources, use the actual article text you retrieved, not empty HTML with links.'
+      );
     }
+  }
 
-    const options: InscriptionOptions = {
-      mode: params.mode,
-      metadata: params.metadata,
-      tags: params.tags,
-      chunkSize: params.chunkSize,
-      waitForConfirmation: params.waitForConfirmation ?? true,
-      waitMaxAttempts: 10,
-      waitIntervalMs: 3000,
-      apiKey: params.apiKey,
-      network: this.inscriberBuilder['hederaKit'].client.network.toString().includes('mainnet') ? 'mainnet' : 'testnet',
+  private async executeInscription(
+    buffer: Buffer,
+    fileName: string,
+    mimeType: string | undefined,
+    options: InscriptionOptions,
+    timeoutMs?: number
+  ): Promise<Awaited<ReturnType<typeof this.inscriberBuilder.inscribe>>> {
+    const inscriptionData = {
+      type: 'buffer' as const,
+      buffer,
+      fileName,
+      mimeType,
     };
 
-    try {
-      let result: Awaited<ReturnType<typeof this.inscriberBuilder.inscribe>>;
-      
-      if (params.timeoutMs) {
-        const timeoutPromise = new Promise<never>((_, reject) => {
-          setTimeout(
-            () => reject(new Error(`Inscription timed out after ${params.timeoutMs}ms`)),
-            params.timeoutMs
-          );
-        });
-
-        result = await Promise.race([
-          this.inscriberBuilder.inscribe(
-            {
-              type: 'buffer',
-              buffer,
-              fileName: params.fileName,
-              mimeType: params.mimeType,
-            },
-            options
-          ),
-          timeoutPromise,
-        ]);
-      } else {
-        result = await this.inscriberBuilder.inscribe(
-          {
-            type: 'buffer',
-            buffer,
-            fileName: params.fileName,
-            mimeType: params.mimeType,
-          },
-          options
+    if (timeoutMs) {
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        setTimeout(
+          () => reject(new Error(`Inscription timed out after ${timeoutMs}ms`)),
+          timeoutMs
         );
+      });
+
+      return Promise.race([
+        this.inscriberBuilder.inscribe(inscriptionData, options),
+        timeoutPromise,
+      ]);
+    }
+
+    return this.inscriberBuilder.inscribe(inscriptionData, options);
+  }
+
+  private formatInscriptionResult(
+    result: Awaited<ReturnType<typeof this.inscriberBuilder.inscribe>>,
+    options: InscriptionOptions
+  ): string {
+    if (result.confirmed) {
+      const topicId = result.inscription?.topic_id || result.result.topicId;
+      const network = options.network || 'testnet';
+      const cdnUrl = topicId
+        ? `https://kiloscribe.com/api/inscription-cdn/${topicId}?network=${network}`
+        : null;
+      return `Successfully inscribed and confirmed content on the Hedera network!\n\nTransaction ID: ${
+        result.result.transactionId
+      }\nTopic ID: ${topicId || 'N/A'}${
+        cdnUrl ? `\nView inscription: ${cdnUrl}` : ''
+      }\n\nThe inscription is now available.`;
+    }
+
+    return `Successfully submitted inscription to the Hedera network!\n\nTransaction ID: ${result.result.transactionId}\n\nThe inscription is processing and will be confirmed shortly.`;
+  }
+
+  private async resolveContent(
+    input: string,
+    providedMimeType?: string,
+    providedFileName?: string
+  ): Promise<{
+    buffer: Buffer;
+    mimeType?: string;
+    fileName?: string;
+    wasReference?: boolean;
+  }> {
+    const trimmedInput = input.trim();
+    
+    // Try to get resolver from either injected dependency or registry
+    const resolver = this.getContentResolver() || ContentResolverRegistry.getResolver();
+    
+    if (!resolver) {
+      // No resolver available, handle content directly
+      return this.handleDirectContent(trimmedInput, providedMimeType, providedFileName);
+    }
+    
+    const referenceId = resolver.extractReferenceId(trimmedInput);
+
+    if (referenceId) {
+      try {
+        const resolution = await resolver.resolveReference(referenceId);
+
+        return {
+          buffer: resolution.content,
+          mimeType: resolution.metadata?.mimeType || providedMimeType,
+          fileName: resolution.metadata?.fileName || providedFileName,
+          wasReference: true,
+        };
+      } catch (error) {
+        const errorMsg =
+          error instanceof Error
+            ? error.message
+            : 'Unknown error resolving reference';
+        throw new Error(`Reference resolution failed: ${errorMsg}`);
       }
+    }
+
+    // No reference found, handle as direct content
+    return this.handleDirectContent(trimmedInput, providedMimeType, providedFileName);
+  }
+
+  private handleDirectContent(
+    input: string,
+    providedMimeType?: string,
+    providedFileName?: string
+  ): {
+    buffer: Buffer;
+    mimeType?: string;
+    fileName?: string;
+    wasReference?: boolean;
+  } {
+    const isValidBase64 = /^[A-Za-z0-9+/]*={0,2}$/.test(input);
 
-      if (result.confirmed) {
-        const topicId = result.inscription?.topic_id || result.result.topicId;
-        const network = options.network || 'testnet';
-        const cdnUrl = topicId ? `https://kiloscribe.com/api/inscription-cdn/${topicId}?network=${network}` : null;
-        return `Successfully inscribed and confirmed content on the Hedera network!\n\nTransaction ID: ${result.result.transactionId}\nTopic ID: ${topicId || 'N/A'}${cdnUrl ? `\nView inscription: ${cdnUrl}` : ''}\n\nThe inscription is now available.`;
-      } else {
-        return `Successfully submitted inscription to the Hedera network!\n\nTransaction ID: ${result.result.transactionId}\n\nThe inscription is processing and will be confirmed shortly.`;
+    if (isValidBase64) {
+      try {
+        const buffer = Buffer.from(input, 'base64');
+        return {
+          buffer,
+          mimeType: providedMimeType,
+          fileName: providedFileName,
+          wasReference: false,
+        };
+      } catch (error) {
+        throw new Error(
+          'Failed to decode base64 data. Please ensure the data is properly encoded.'
+        );
       }
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : 'Failed to inscribe from buffer';
-      throw new Error(`Inscription failed: ${errorMessage}`);
     }
+
+    const buffer = Buffer.from(input, 'utf8');
+    return {
+      buffer,
+      mimeType: providedMimeType || 'text/plain',
+      fileName: providedFileName,
+      wasReference: false,
+    };
   }
-}
+}

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

@@ -8,6 +8,7 @@ import {
   InscriberTransactionToolParams,
   InscriberQueryToolParams,
 } from './inscriber-tool-params';
+import type { ContentResolverInterface } from '../../types/content-resolver';
 import { z } from 'zod';
 
 /**
@@ -21,11 +22,13 @@ export abstract class BaseInscriberTransactionTool<
   > = z.ZodObject<z.ZodRawShape>
 > extends BaseHederaTransactionTool<T> {
   protected inscriberBuilder: InscriberBuilder;
+  protected contentResolver: ContentResolverInterface | null;
   namespace = 'inscriber' as const;
 
   constructor(params: InscriberTransactionToolParams) {
     super(params);
     this.inscriberBuilder = params.inscriberBuilder;
+    this.contentResolver = params.contentResolver || null;
   }
 
   /**
@@ -34,6 +37,13 @@ export abstract class BaseInscriberTransactionTool<
   protected getServiceBuilder(): BaseServiceBuilder {
     return this.inscriberBuilder;
   }
+
+  /**
+   * Get content resolver with fallback to registry
+   */
+  protected getContentResolver(): ContentResolverInterface | null {
+    return this.contentResolver;
+  }
 }
 
 /**
@@ -47,11 +57,13 @@ export abstract class BaseInscriberQueryTool<
   > = z.ZodObject<z.ZodRawShape>
 > extends BaseHederaQueryTool<T> {
   protected inscriberBuilder: InscriberBuilder;
+  protected contentResolver: ContentResolverInterface | null;
   namespace = 'inscriber' as const;
 
   constructor(params: InscriberQueryToolParams) {
     super(params);
     this.inscriberBuilder = params.inscriberBuilder;
+    this.contentResolver = params.contentResolver || null;
   }
 
   /**
@@ -60,4 +72,11 @@ export abstract class BaseInscriberQueryTool<
   protected getServiceBuilder(): BaseServiceBuilder {
     return this.inscriberBuilder;
   }
+
+  /**
+   * Get content resolver with fallback to registry
+   */
+  protected getContentResolver(): ContentResolverInterface | null {
+    return this.contentResolver;
+  }
 }

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

@@ -1,6 +1,7 @@
 import { HederaAgentKit } from 'hedera-agent-kit';
 import type { BasePluginContext } from 'hedera-agent-kit';
 import { InscriberBuilder } from '../../builders/inscriber/inscriber-builder';
+import type { ContentResolverInterface } from '../../types/content-resolver';
 
 /**
  * Parameters for Inscriber transaction tools
@@ -9,6 +10,7 @@ export interface InscriberTransactionToolParams {
   hederaKit: HederaAgentKit;
   inscriberBuilder: InscriberBuilder;
   logger?: BasePluginContext['logger'];
+  contentResolver?: ContentResolverInterface;
 }
 
 /**
@@ -18,4 +20,5 @@ export interface InscriberQueryToolParams {
   hederaKit: HederaAgentKit;
   inscriberBuilder: InscriberBuilder;
   logger?: BasePluginContext['logger'];
+  contentResolver?: ContentResolverInterface;
 }

package/src/types/content-resolver.ts

@@ -0,0 +1,11 @@
+/**
+ * Content Resolver Types
+ * 
+ * Re-export types from standards-sdk for content resolution.
+ */
+
+export type { 
+  ContentResolverInterface,
+  ReferenceResolutionResult,
+  ContentStoreInterface 
+} from '@hashgraphonline/standards-sdk';