@hashgraphonline/standards-agent-kit 0.2.1 → 0.2.102

package/src/tools/hcs2/DeleteEntryTool.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { BaseHCS2QueryTool } from './base-hcs2-tools';
+import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+
+/**
+ * Schema for deleting an entry from HCS-2
+ */
+const deleteEntrySchema = z.object({
+  registryTopicId: z
+    .string()
+    .regex(/^\d+\.\d+\.\d+$/)
+    .describe('The HCS-2 registry topic ID (must be indexed)'),
+  uid: z
+    .string()
+    .describe('The unique ID of the entry to delete'),
+  memo: z
+    .string()
+    .max(500)
+    .optional()
+    .describe('Optional memo (max 500 characters)'),
+});
+
+
+/**
+ * Tool for deleting entries from HCS-2 registries
+ */
+export class DeleteEntryTool extends BaseHCS2QueryTool<typeof deleteEntrySchema> {
+  name = 'deleteHCS2Entry';
+  description = 'Delete an entry from an indexed HCS-2 registry';
+
+  get specificInputSchema() {
+    return deleteEntrySchema;
+  }
+
+  protected async executeQuery(
+    params: z.infer<typeof deleteEntrySchema>,
+    _runManager?: CallbackManagerForToolRun
+  ): Promise<unknown> {
+    try {
+      const result = await this.hcs2Builder.deleteEntry(
+        params.registryTopicId,
+        {
+          uid: params.uid,
+          memo: params.memo,
+        }
+      );
+
+      if (!result.success) {
+        throw new Error(result.error || 'Failed to delete entry');
+      }
+
+      return `Successfully deleted entry from HCS-2 registry!\n\nRegistry Topic: ${params.registryTopicId}\nUID: ${params.uid}${params.memo ? `\nMemo: ${params.memo}` : ''}\n\nThe entry has been removed from the registry.`;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Failed to delete entry';
+      throw new Error(`Entry deletion failed: ${errorMessage}`);
+    }
+  }
+}

package/src/tools/hcs2/MigrateRegistryTool.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import { BaseHCS2QueryTool } from './base-hcs2-tools';
+import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+
+/**
+ * Schema for migrating an HCS-2 registry
+ */
+const migrateRegistrySchema = z.object({
+  registryTopicId: z
+    .string()
+    .regex(/^\d+\.\d+\.\d+$/)
+    .describe('The current HCS-2 registry topic ID'),
+  targetTopicId: z
+    .string()
+    .regex(/^\d+\.\d+\.\d+$/)
+    .describe('The new topic ID to migrate to'),
+  metadata: z
+    .string()
+    .optional()
+    .describe('Optional metadata URI for migration details'),
+  memo: z
+    .string()
+    .max(500)
+    .optional()
+    .describe('Optional memo (max 500 characters)'),
+});
+
+
+/**
+ * Tool for migrating HCS-2 registries
+ */
+export class MigrateRegistryTool extends BaseHCS2QueryTool<typeof migrateRegistrySchema> {
+  name = 'migrateHCS2Registry';
+  description = 'Migrate an HCS-2 registry to a new topic';
+
+  get specificInputSchema() {
+    return migrateRegistrySchema;
+  }
+
+  protected async executeQuery(
+    params: z.infer<typeof migrateRegistrySchema>,
+    _runManager?: CallbackManagerForToolRun
+  ): Promise<unknown> {
+    try {
+      const result = await this.hcs2Builder.migrateRegistry(
+        params.registryTopicId,
+        {
+          targetTopicId: params.targetTopicId,
+          metadata: params.metadata,
+          memo: params.memo,
+        }
+      );
+
+      if (!result.success) {
+        throw new Error(result.error || 'Failed to migrate registry');
+      }
+
+      return `Successfully migrated HCS-2 registry!\n\nFrom Registry Topic: ${params.registryTopicId}\nTo Target Topic: ${params.targetTopicId}${params.metadata ? `\nMetadata: ${params.metadata}` : ''}${params.memo ? `\nMemo: ${params.memo}` : ''}\n\nThe registry has been migrated to the new topic.`;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Failed to migrate registry';
+      throw new Error(`Registry migration failed: ${errorMessage}`);
+    }
+  }
+}

package/src/tools/hcs2/QueryRegistryTool.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import { BaseHCS2QueryTool } from './base-hcs2-tools';
+import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+
+/**
+ * Schema for querying HCS-2 registry
+ */
+const queryRegistrySchema = z.object({
+  topicId: z
+    .string()
+    .regex(/^\d+\.\d+\.\d+$/)
+    .describe('The HCS-2 registry topic ID to query'),
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Maximum number of entries to return'),
+  order: z
+    .enum(['asc', 'desc'])
+    .optional()
+    .describe('Order of results (ascending or descending)'),
+  skip: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe('Number of entries to skip'),
+});
+
+
+/**
+ * Tool for querying HCS-2 registries
+ */
+export class QueryRegistryTool extends BaseHCS2QueryTool<typeof queryRegistrySchema> {
+  name = 'queryHCS2Registry';
+  description = 'Query entries from an HCS-2 registry';
+
+  get specificInputSchema() {
+    return queryRegistrySchema;
+  }
+
+  protected async executeQuery(
+    params: z.infer<typeof queryRegistrySchema>,
+    _runManager?: CallbackManagerForToolRun
+  ): Promise<unknown> {
+    const registry = await this.hcs2Builder.getRegistry(params.topicId, {
+      limit: params.limit,
+      order: params.order,
+      skip: params.skip,
+    });
+
+    return {
+      topicId: registry.topicId,
+      registryType: registry.registryType === 0 ? 'indexed' : 'non-indexed',
+      ttl: registry.ttl,
+      totalEntries: registry.entries.length,
+      entries: registry.entries.map(entry => ({
+        sequence: entry.sequence,
+        timestamp: entry.timestamp,
+        payer: entry.payer,
+        operation: entry.message.op,
+        targetTopicId: entry.message.t_id,
+        uid: entry.message.uid,
+        metadata: entry.message.metadata,
+        memo: entry.message.m,
+      })),
+    };
+  }
+}

package/src/tools/hcs2/RegisterEntryTool.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { BaseHCS2QueryTool } from './base-hcs2-tools';
+import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+
+/**
+ * Schema for registering an entry in HCS-2
+ */
+const registerEntrySchema = z.object({
+  registryTopicId: z
+    .string()
+    .regex(/^\d+\.\d+\.\d+$/)
+    .describe('The HCS-2 registry topic ID (e.g., 0.0.123456)'),
+  targetTopicId: z
+    .string()
+    .regex(/^\d+\.\d+\.\d+$/)
+    .describe('The target topic ID to register (e.g., 0.0.123456)'),
+  metadata: z
+    .string()
+    .optional()
+    .describe('Optional metadata URI (HIP-412 format)'),
+  memo: z
+    .string()
+    .max(500)
+    .optional()
+    .describe('Optional memo (max 500 characters)'),
+});
+
+/**
+ * Tool for registering entries in HCS-2 registries
+ */
+export class RegisterEntryTool extends BaseHCS2QueryTool<typeof registerEntrySchema> {
+  name = 'registerHCS2Entry';
+  description = 'Register a new entry in an HCS-2 registry';
+
+  get specificInputSchema() {
+    return registerEntrySchema;
+  }
+
+  protected async executeQuery(
+    params: z.infer<typeof registerEntrySchema>,
+    _runManager?: CallbackManagerForToolRun
+  ): Promise<unknown> {
+    try {
+      const result = await this.hcs2Builder.registerEntry(
+        params.registryTopicId,
+        {
+          targetTopicId: params.targetTopicId,
+          metadata: params.metadata,
+          memo: params.memo,
+        }
+      );
+
+      if (!result.success) {
+        throw new Error(result.error || 'Failed to register entry');
+      }
+
+      return `Successfully registered entry in HCS-2 registry!\n\nRegistry Topic: ${params.registryTopicId}\nTarget Topic ID: ${params.targetTopicId}${params.metadata ? `\nMetadata: ${params.metadata}` : ''}${params.memo ? `\nMemo: ${params.memo}` : ''}\n\nThe entry has been added to the registry.`;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Failed to register entry';
+      throw new Error(`Entry registration failed: ${errorMessage}`);
+    }
+  }
+}

package/src/tools/hcs2/UpdateEntryTool.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import { BaseHCS2QueryTool } from './base-hcs2-tools';
+import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+
+/**
+ * Schema for updating an entry in HCS-2
+ */
+const updateEntrySchema = z.object({
+  registryTopicId: z
+    .string()
+    .regex(/^\d+\.\d+\.\d+$/)
+    .describe('The HCS-2 registry topic ID (must be indexed)'),
+  targetTopicId: z
+    .string()
+    .regex(/^\d+\.\d+\.\d+$/)
+    .describe('The new topic ID to point to'),
+  uid: z
+    .string()
+    .describe('The unique ID of the entry to update'),
+  metadata: z
+    .string()
+    .optional()
+    .describe('Optional metadata URI (HIP-412 format)'),
+  memo: z
+    .string()
+    .max(500)
+    .optional()
+    .describe('Optional memo (max 500 characters)'),
+});
+
+
+/**
+ * Tool for updating entries in HCS-2 registries
+ */
+export class UpdateEntryTool extends BaseHCS2QueryTool<typeof updateEntrySchema> {
+  name = 'updateHCS2Entry';
+  description = 'Update an existing entry in an indexed HCS-2 registry';
+
+  get specificInputSchema() {
+    return updateEntrySchema;
+  }
+
+  protected async executeQuery(
+    params: z.infer<typeof updateEntrySchema>,
+    _runManager?: CallbackManagerForToolRun
+  ): Promise<unknown> {
+    try {
+      const result = await this.hcs2Builder.updateEntry(
+        params.registryTopicId,
+        {
+          targetTopicId: params.targetTopicId,
+          uid: params.uid,
+          metadata: params.metadata,
+          memo: params.memo,
+        }
+      );
+
+      if (!result.success) {
+        throw new Error(result.error || 'Failed to update entry');
+      }
+
+      return `Successfully updated entry in HCS-2 registry!\n\nRegistry Topic: ${params.registryTopicId}\nUID: ${params.uid}\nNew Target Topic ID: ${params.targetTopicId}${params.metadata ? `\nMetadata: ${params.metadata}` : ''}${params.memo ? `\nMemo: ${params.memo}` : ''}\n\nThe entry has been updated in the registry.`;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Failed to update entry';
+      throw new Error(`Entry update failed: ${errorMessage}`);
+    }
+  }
+}

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

@@ -0,0 +1,65 @@
+import {
+  BaseHederaTransactionTool,
+  BaseHederaQueryTool,
+  BaseServiceBuilder,
+} from 'hedera-agent-kit';
+import { HCS2Builder } from '../../builders/hcs2/hcs2-builder';
+import {
+  HCS2TransactionToolParams,
+  HCS2QueryToolParams,
+} from './hcs2-tool-params';
+import { z } from 'zod';
+
+/**
+ * Base class for HCS2 transaction tools
+ */
+export abstract class BaseHCS2TransactionTool<
+  T extends z.ZodObject<
+    z.ZodRawShape,
+    z.UnknownKeysParam,
+    z.ZodTypeAny
+  > = z.ZodObject<z.ZodRawShape>
+> extends BaseHederaTransactionTool<T> {
+  protected hcs2Builder: HCS2Builder;
+  namespace = 'hcs2' as const;
+
+  constructor(params: HCS2TransactionToolParams) {
+    super(params);
+    this.hcs2Builder = params.hcs2Builder;
+  }
+
+  /**
+   * Override to return the HCS2Builder
+   */
+  protected getServiceBuilder(): BaseServiceBuilder {
+    return this.hcs2Builder;
+  }
+}
+
+/**
+ * Base class for HCS2 query tools
+ */
+export abstract class BaseHCS2QueryTool<
+  T extends z.ZodObject<
+    z.ZodRawShape,
+    z.UnknownKeysParam,
+    z.ZodTypeAny,
+    Record<string, unknown>,
+    Record<string, unknown>
+  > = z.ZodObject<z.ZodRawShape>
+> extends BaseHederaQueryTool<T> {
+  protected hcs2Builder: HCS2Builder;
+  namespace = 'hcs2' as const;
+
+  constructor(params: HCS2QueryToolParams) {
+    super(params);
+    this.hcs2Builder = params.hcs2Builder;
+  }
+
+  /**
+   * Override to return the HCS2Builder
+   */
+  protected getServiceBuilder(): BaseServiceBuilder {
+    return this.hcs2Builder;
+  }
+}

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

@@ -0,0 +1,21 @@
+import { HederaAgentKit } from 'hedera-agent-kit';
+import type { BasePluginContext } from 'hedera-agent-kit';
+import { HCS2Builder } from '../../builders/hcs2/hcs2-builder';
+
+/**
+ * Parameters for HCS2 transaction tools
+ */
+export interface HCS2TransactionToolParams {
+  hederaKit: HederaAgentKit;
+  hcs2Builder: HCS2Builder;
+  logger?: BasePluginContext['logger'];
+}
+
+/**
+ * Parameters for HCS2 query tools
+ */
+export interface HCS2QueryToolParams {
+  hederaKit: HederaAgentKit;
+  hcs2Builder: HCS2Builder;
+  logger?: BasePluginContext['logger'];
+}

package/src/tools/hcs2/index.ts

@@ -0,0 +1,8 @@
+export * from './base-hcs2-tools';
+export * from './hcs2-tool-params';
+export * from './CreateRegistryTool';
+export * from './RegisterEntryTool';
+export * from './UpdateEntryTool';
+export * from './DeleteEntryTool';
+export * from './MigrateRegistryTool';
+export * from './QueryRegistryTool';

package/src/tools/index.ts

@@ -1,2 +1,3 @@
-// Export all HCS10 tools from the subdirectory
-export * from './hcs10';
+export * from './hcs10';
+export * from './hcs2';
+export * from './inscriber';

package/src/tools/inscriber/InscribeFromBufferTool.ts

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+import { BaseInscriberQueryTool } from './base-inscriber-tools';
+import { InscriptionOptions } from '@hashgraphonline/standards-sdk';
+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'),
+  mimeType: z
+    .string()
+    .optional()
+    .describe('MIME type of the content'),
+  mode: z
+    .enum(['file', 'hashinal'])
+    .optional()
+    .describe('Inscription mode: file or hashinal NFT'),
+  metadata: z
+    .record(z.unknown())
+    .optional()
+    .describe('Metadata to attach to the inscription'),
+  tags: z
+    .array(z.string())
+    .optional()
+    .describe('Tags to categorize the inscription'),
+  chunkSize: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Chunk size for large files'),
+  waitForConfirmation: z
+    .boolean()
+    .optional()
+    .describe('Whether to wait for inscription confirmation'),
+  apiKey: z
+    .string()
+    .optional()
+    .describe('API key for inscription service'),
+});
+
+
+/**
+ * Tool for inscribing content from buffer
+ */
+export class InscribeFromBufferTool extends BaseInscriberQueryTool<typeof inscribeFromBufferSchema> {
+  name = 'inscribeFromBuffer';
+  description = 'Inscribe content from a buffer/base64 data to the Hedera network';
+
+  get specificInputSchema() {
+    return inscribeFromBufferSchema;
+  }
+
+  protected async executeQuery(
+    params: z.infer<typeof inscribeFromBufferSchema>,
+    _runManager?: CallbackManagerForToolRun
+  ): Promise<unknown> {
+    const buffer = Buffer.from(params.base64Data, 'base64');
+
+    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',
+    };
+
+    try {
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error('Inscription timed out after 30 seconds')), 30000);
+      });
+
+      const result = await Promise.race([
+        this.inscriberBuilder.inscribe(
+          {
+            type: 'buffer',
+            buffer,
+            fileName: params.fileName,
+            mimeType: params.mimeType,
+          },
+          options
+        ),
+        timeoutPromise
+      ]) as any;
+
+      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.`;
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Failed to inscribe from buffer';
+      throw new Error(`Inscription failed: ${errorMessage}`);
+    }
+  }
+}

package/src/tools/inscriber/InscribeFromFileTool.ts

@@ -0,0 +1,93 @@
+import { z } from 'zod';
+import { BaseInscriberQueryTool } from './base-inscriber-tools';
+import { InscriptionOptions } from '@hashgraphonline/standards-sdk';
+import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+
+/**
+ * Schema for inscribing from file
+ */
+const inscribeFromFileSchema = z.object({
+  filePath: z.string().describe('The file path of the content to inscribe'),
+  mode: z
+    .enum(['file', 'hashinal'])
+    .optional()
+    .describe('Inscription mode: file or hashinal NFT'),
+  metadata: z
+    .record(z.unknown())
+    .optional()
+    .describe('Metadata to attach to the inscription'),
+  tags: z
+    .array(z.string())
+    .optional()
+    .describe('Tags to categorize the inscription'),
+  chunkSize: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Chunk size for large files'),
+  waitForConfirmation: z
+    .boolean()
+    .optional()
+    .describe('Whether to wait for inscription confirmation'),
+  apiKey: z
+    .string()
+    .optional()
+    .describe('API key for inscription service'),
+});
+
+
+/**
+ * Tool for inscribing content from file
+ */
+export class InscribeFromFileTool extends BaseInscriberQueryTool<typeof inscribeFromFileSchema> {
+  name = 'inscribeFromFile';
+  description = 'Inscribe content from a local file to the Hedera network';
+
+  get specificInputSchema() {
+    return inscribeFromFileSchema;
+  }
+
+  protected async executeQuery(
+    params: z.infer<typeof inscribeFromFileSchema>,
+    _runManager?: CallbackManagerForToolRun
+  ): Promise<unknown> {
+    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',
+    };
+
+    try {
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error('Inscription timed out after 30 seconds')), 30000);
+      });
+
+      const result = await Promise.race([
+        this.inscriberBuilder.inscribe(
+          { type: 'file', path: params.filePath },
+          options
+        ),
+        timeoutPromise
+      ]) as any;
+
+      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.`;
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Failed to inscribe from file';
+      throw new Error(`Inscription failed: ${errorMessage}`);
+    }
+  }
+}