@hashgraphonline/standards-agent-kit 0.0.37 → 0.2.0

package/src/tools/hcs10/InitiateConnectionTool.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import { BaseHCS10TransactionTool } from './base-hcs10-tools';
+import { HCS10Builder } from '../../builders/hcs10/hcs10-builder';
+import { HCS10TransactionToolParams } from './hcs10-tool-params';
+import { BaseServiceBuilder } from 'hedera-agent-kit';
+
+const InitiateConnectionZodSchema = z.object({
+  targetAccountId: z
+    .string()
+    .describe(
+      'The Hedera account ID (e.g., 0.0.12345) of the agent you want to connect with.'
+    ),
+  disableMonitor: z
+    .boolean()
+    .optional()
+    .describe(
+      'If true, does not wait for connection confirmation. Returns immediately after sending the request.'
+    ),
+  memo: z
+    .string()
+    .optional()
+    .describe(
+      'Optional memo to include with the connection request (e.g., "Hello from Alice"). If not provided, defaults to "true" or "false" based on monitoring preference.'
+    ),
+});
+
+/**
+ * A tool to actively START a NEW HCS-10 connection TO a target agent.
+ * Requires the target agent's account ID.
+ * It retrieves their profile, sends a connection request, and optionally waits for confirmation.
+ * Use this tool ONLY to actively INITIATE an OUTGOING connection.
+ */
+export class InitiateConnectionTool extends BaseHCS10TransactionTool<
+  typeof InitiateConnectionZodSchema
+> {
+  name = 'initiate_connection';
+  description =
+    'Actively STARTS a NEW HCS-10 connection TO a specific target agent identified by their account ID. Requires the targetAccountId parameter. Use this ONLY to INITIATE an OUTGOING connection request.';
+  specificInputSchema = InitiateConnectionZodSchema;
+  constructor(params: HCS10TransactionToolParams) {
+    super(params);
+    this.neverScheduleThisTool = true;
+    this.requiresMultipleTransactions = true;
+  }
+
+  protected async callBuilderMethod(
+    builder: BaseServiceBuilder,
+    specificArgs: z.infer<typeof InitiateConnectionZodSchema>
+  ): Promise<void> {
+    const hcs10Builder = builder as HCS10Builder;
+    const params: {
+      targetAccountId: string;
+      disableMonitor?: boolean;
+      memo?: string;
+    } = {
+      targetAccountId: specificArgs.targetAccountId,
+    };
+    if (specificArgs.disableMonitor !== undefined) {
+      params.disableMonitor = specificArgs.disableMonitor;
+    }
+    if (specificArgs.memo !== undefined) {
+      params.memo = specificArgs.memo;
+    }
+    await hcs10Builder.initiateConnection(params);
+  }
+}

package/src/tools/hcs10/ListConnectionsTool.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { BaseHCS10QueryTool } from './base-hcs10-tools';
+import { HCS10QueryToolParams } from './hcs10-tool-params';
+
+/**
+ * A tool to list currently active HCS-10 connections stored in the state manager.
+ * Enhanced to show more details similar to moonscape's implementation.
+ */
+const ListConnectionsZodSchema = z.object({
+  includeDetails: z
+    .boolean()
+    .optional()
+    .describe(
+      'Whether to include detailed information about each connection'
+    ),
+  showPending: z
+    .boolean()
+    .optional()
+    .describe('Whether to include pending connection requests'),
+});
+
+export class ListConnectionsTool extends BaseHCS10QueryTool<
+  typeof ListConnectionsZodSchema
+> {
+  name = 'list_connections';
+  description =
+    'Lists the currently active HCS-10 connections with detailed information. Shows connection status, agent details, and recent activity. Use this to get a comprehensive view of all active connections.';
+  specificInputSchema = ListConnectionsZodSchema;
+  constructor(params: HCS10QueryToolParams) {
+    super(params);
+  }
+
+  protected async executeQuery(
+    args: z.infer<typeof ListConnectionsZodSchema>
+  ): Promise<unknown> {
+    const hcs10Builder = this.hcs10Builder;
+    const params: { includeDetails?: boolean; showPending?: boolean } = {};
+    if (args.includeDetails !== undefined) {
+      params.includeDetails = args.includeDetails;
+    }
+    if (args.showPending !== undefined) {
+      params.showPending = args.showPending;
+    }
+    await hcs10Builder.listConnections(params);
+
+    const result = await hcs10Builder.execute();
+
+    if (result.success && 'rawResult' in result && result.rawResult) {
+      const raw = result.rawResult as { formattedOutput?: string; message?: string };
+      return {
+        success: true,
+        data: raw.formattedOutput || raw.message || 'Connections listed'
+      };
+    }
+
+    return result;
+  }
+}

package/src/tools/hcs10/ListUnapprovedConnectionRequestsTool.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { BaseHCS10QueryTool } from './base-hcs10-tools';
+import { HCS10QueryToolParams } from './hcs10-tool-params';
+const ListUnapprovedConnectionRequestsZodSchema = z.object({});
+
+/**
+ * Lists all connection requests that are not fully established
+ */
+export class ListUnapprovedConnectionRequestsTool extends BaseHCS10QueryTool<
+  typeof ListUnapprovedConnectionRequestsZodSchema
+> {
+  name = 'list_unapproved_connection_requests';
+  description =
+    'Lists all connection requests that are not fully established, including incoming requests needing approval and outgoing requests waiting for confirmation.';
+  specificInputSchema = ListUnapprovedConnectionRequestsZodSchema;
+  constructor(params: HCS10QueryToolParams) {
+    super(params);
+  }
+
+  protected async executeQuery(): Promise<unknown> {
+    const hcs10Builder = this.hcs10Builder;
+    await hcs10Builder.listUnapprovedConnectionRequests();
+    const result = await hcs10Builder.execute();
+    return 'rawResult' in result ? result.rawResult : result;
+  }
+}

package/src/tools/hcs10/ManageConnectionRequestsTool.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { BaseHCS10QueryTool } from './base-hcs10-tools';
+import { HCS10QueryToolParams } from './hcs10-tool-params';
+
+const ManageConnectionRequestsZodSchema = z.object({
+  action: z
+    .enum(['list', 'view', 'reject'])
+    .describe(
+      'The action to perform: list all requests, view details of a specific request, or reject a request'
+    ),
+  requestKey: z
+    .string()
+    .optional()
+    .describe(
+      'The unique request key to view or reject (required for view and reject actions)'
+    ),
+});
+
+/**
+ * A tool for managing incoming connection requests in a LangChain-compatible way.
+ * This tool allows an agent to list, view details of, and reject incoming connection requests.
+ */
+export class ManageConnectionRequestsTool extends BaseHCS10QueryTool<
+  typeof ManageConnectionRequestsZodSchema
+> {
+  name = 'manage_connection_requests';
+  description =
+    'Manage incoming connection requests. List pending requests, view details about requesting agents, and reject connection requests. Use the separate "accept_connection_request" tool to accept.';
+  specificInputSchema = ManageConnectionRequestsZodSchema;
+  constructor(params: HCS10QueryToolParams) {
+    super(params);
+  }
+
+  protected async executeQuery({
+    action,
+    requestKey,
+  }: z.infer<typeof ManageConnectionRequestsZodSchema>): Promise<unknown> {
+    const hcs10Builder = this.hcs10Builder;
+    const params: { action: 'list' | 'view' | 'reject'; requestKey?: string } =
+      { action };
+    if (requestKey !== undefined) {
+      params.requestKey = requestKey;
+    }
+    await hcs10Builder.manageConnectionRequests(params);
+    const result = await hcs10Builder.execute();
+    return 'rawResult' in result ? result.rawResult : result;
+  }
+}

package/src/tools/hcs10/RegisterAgentTool.ts

@@ -0,0 +1,213 @@
+import { AIAgentCapability } from '@hashgraphonline/standards-sdk';
+import { z } from 'zod';
+import { BaseServiceBuilder } from 'hedera-agent-kit';
+import { HCS10Builder, RegisterAgentParams } from '../../builders/hcs10/hcs10-builder';
+import { BaseHCS10TransactionTool } from './base-hcs10-tools';
+import { HCS10TransactionToolParams } from './hcs10-tool-params';
+
+const RegisterAgentZodSchema = z.object({
+  name: z
+    .string()
+    .min(1)
+    .max(50)
+    .describe('A unique name for the agent (1-50 characters)'),
+  description: z
+    .string()
+    .max(500)
+    .optional()
+    .describe('Optional bio description for the agent (max 500 characters)'),
+  alias: z
+    .string()
+    .optional()
+    .describe('Optional custom username/alias for the agent'),
+  type: z
+    .enum(['autonomous', 'manual'])
+    .optional()
+    .describe('Agent type (default: autonomous)'),
+  model: z
+    .string()
+    .optional()
+    .describe('AI model identifier (default: agent-model-2024)'),
+  capabilities: z
+    .array(z.nativeEnum(AIAgentCapability))
+    .optional()
+    .describe('Array of agent capabilities (default: [TEXT_GENERATION])'),
+  creator: z.string().optional().describe('Creator attribution for the agent'),
+  socials: z
+    .record(
+      z.enum([
+        'twitter',
+        'github',
+        'discord',
+        'telegram',
+        'linkedin',
+        'youtube',
+        'website',
+        'x',
+      ] as const),
+      z.string()
+    )
+    .optional()
+    .describe(
+      'Social media links (e.g., {"twitter": "@handle", "discord": "username"})'
+    ),
+  properties: z
+    .record(z.unknown())
+    .optional()
+    .describe('Custom metadata properties for the agent'),
+  profilePicture: z
+    .union([
+      z.string().describe('URL or local file path to profile picture'),
+      z.object({
+        url: z.string().optional(),
+        path: z.string().optional(),
+        filename: z.string().optional(),
+      }),
+    ])
+    .optional()
+    .describe(
+      'Optional profile picture as URL, file path, or object with url/path/filename'
+    ),
+  existingProfilePictureTopicId: z
+    .string()
+    .optional()
+    .describe(
+      'Topic ID of an existing profile picture to reuse (e.g., 0.0.12345)'
+    ),
+  initialBalance: z
+    .number()
+    .positive()
+    .optional()
+    .describe(
+      'Optional initial HBAR balance for the new agent account (will create new account if provided)'
+    ),
+  userAccountId: z
+    .string()
+    .optional()
+    .describe(
+      'Optional account ID (e.g., 0.0.12345) to use as the agent account instead of creating a new one'
+    ),
+  hbarFee: z
+    .number()
+    .positive()
+    .optional()
+    .describe(
+      'Optional HBAR fee amount to charge per message on the inbound topic'
+    ),
+  tokenFees: z
+    .array(
+      z.object({
+        amount: z.number().positive(),
+        tokenId: z.string(),
+      })
+    )
+    .optional()
+    .describe('Optional token fees to charge per message'),
+  exemptAccountIds: z
+    .array(z.string())
+    .optional()
+    .describe('Optional account IDs to exempt from fees'),
+  setAsCurrent: z
+    .boolean()
+    .optional()
+    .describe('Whether to set as current agent (default: true)'),
+  persistence: z
+    .object({
+      prefix: z.string().optional(),
+    })
+    .optional()
+    .describe('Optional persistence configuration'),
+});
+
+export class RegisterAgentTool extends BaseHCS10TransactionTool<
+  typeof RegisterAgentZodSchema
+> {
+  name = 'register_agent';
+  description =
+    'Creates and registers the AI agent on the Hedera network. Returns JSON string with agent details (accountId, privateKey, topics) on success. Note: This tool requires multiple transactions and cannot be used in returnBytes mode.';
+  specificInputSchema = RegisterAgentZodSchema;
+
+  constructor(params: HCS10TransactionToolParams) {
+    super(params);
+    this.neverScheduleThisTool = true;
+    this.requiresMultipleTransactions = true;
+  }
+
+  protected async callBuilderMethod(
+    builder: BaseServiceBuilder,
+    specificArgs: z.infer<typeof RegisterAgentZodSchema>
+  ): Promise<void> {
+    const hcs10Builder = builder as HCS10Builder;
+
+    const params: RegisterAgentParams = {
+      name: specificArgs.name,
+    };
+
+    if (specificArgs.description !== undefined) {
+      params.bio = specificArgs.description;
+    }
+    if (specificArgs.alias !== undefined) {
+      params.alias = specificArgs.alias;
+    }
+    if (specificArgs.type !== undefined) {
+      params.type = specificArgs.type;
+    }
+    if (specificArgs.model !== undefined) {
+      params.model = specificArgs.model;
+    }
+    if (specificArgs.capabilities !== undefined) {
+      params.capabilities = specificArgs.capabilities;
+    }
+    if (specificArgs.creator !== undefined) {
+      params.creator = specificArgs.creator;
+    }
+    if (specificArgs.socials !== undefined) {
+      params.socials = specificArgs.socials;
+    }
+    if (specificArgs.properties !== undefined) {
+      params.properties = specificArgs.properties;
+    }
+    if (specificArgs.profilePicture !== undefined) {
+      if (typeof specificArgs.profilePicture === 'string') {
+        params.profilePicture = specificArgs.profilePicture;
+      } else {
+        const profilePicObj: {
+          url?: string;
+          path?: string;
+          filename?: string;
+        } = {};
+        if (specificArgs.profilePicture.url !== undefined) {
+          profilePicObj.url = specificArgs.profilePicture.url;
+        }
+        if (specificArgs.profilePicture.path !== undefined) {
+          profilePicObj.path = specificArgs.profilePicture.path;
+        }
+        if (specificArgs.profilePicture.filename !== undefined) {
+          profilePicObj.filename = specificArgs.profilePicture.filename;
+        }
+        params.profilePicture = profilePicObj;
+      }
+    }
+    if (specificArgs.existingProfilePictureTopicId !== undefined) {
+      params.existingProfilePictureTopicId =
+        specificArgs.existingProfilePictureTopicId;
+    }
+    if (specificArgs.userAccountId !== undefined) {
+      params.userAccountId = specificArgs.userAccountId;
+    }
+    if (specificArgs.hbarFee !== undefined) {
+      params.hbarFee = specificArgs.hbarFee;
+    }
+    if (specificArgs.tokenFees !== undefined) {
+      params.tokenFees = specificArgs.tokenFees;
+    }
+    if (specificArgs.exemptAccountIds !== undefined) {
+      params.exemptAccountIds = specificArgs.exemptAccountIds;
+    }
+    if (specificArgs.initialBalance !== undefined) {
+      params.initialBalance = specificArgs.initialBalance;
+    }
+
+    await hcs10Builder.registerAgent(params);
+  }
+}

package/src/tools/hcs10/RetrieveProfileTool.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { BaseHCS10QueryTool } from './base-hcs10-tools';
+import { HCS10QueryToolParams } from './hcs10-tool-params';
+const RetrieveProfileZodSchema = z.object({
+  accountId: z
+    .string()
+    .describe(
+      'The Hedera account ID of the agent whose profile you want to retrieve (e.g., 0.0.12345).'
+    ),
+  disableCache: z
+    .boolean()
+    .optional()
+    .describe(
+      'Optional: Force refresh from the network instead of using cache.'
+    ),
+});
+
+/**
+ * Tool to retrieve detailed profile information for a specific HCS-10 agent
+ */
+export class RetrieveProfileTool extends BaseHCS10QueryTool<
+  typeof RetrieveProfileZodSchema
+> {
+  name = 'retrieve_profile';
+  description =
+    'Gets the detailed profile information for a specific HCS-10 agent by their account ID. Returns name, bio, capabilities, topics, and other metadata.';
+  specificInputSchema = RetrieveProfileZodSchema;
+  constructor(params: HCS10QueryToolParams) {
+    super(params);
+  }
+
+  protected async executeQuery({
+    accountId,
+    disableCache,
+  }: z.infer<typeof RetrieveProfileZodSchema>): Promise<unknown> {
+    const hcs10Builder = this.hcs10Builder;
+    const params: { accountId: string; disableCache?: boolean } = {
+      accountId,
+    };
+    if (disableCache !== undefined) {
+      params.disableCache = disableCache;
+    }
+    await hcs10Builder.retrieveProfile(params);
+
+    const result = await hcs10Builder.execute();
+
+    if (result.success && 'rawResult' in result && result.rawResult) {
+      const raw = result.rawResult as {
+        profileDetails?: string;
+        rawProfile?: unknown;
+      };
+      return {
+        success: true,
+        data: raw.profileDetails || 'Profile retrieved',
+        rawProfile: raw.rawProfile,
+      };
+    }
+
+    return result;
+  }
+}

package/src/tools/hcs10/SendMessageToConnectionTool.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { BaseHCS10TransactionTool } from './base-hcs10-tools';
+import { HCS10Builder } from '../../builders/hcs10/hcs10-builder';
+import { HCS10TransactionToolParams } from './hcs10-tool-params';
+import { BaseServiceBuilder } from 'hedera-agent-kit';
+
+const SendMessageToConnectionZodSchema = z.object({
+  targetIdentifier: z
+    .string()
+    .describe(
+      "The request key (e.g., 'req-1:0.0.6155171@0.0.6154875'), account ID (e.g., 0.0.12345) of the target agent, OR the connection number (e.g., '1', '2') from the 'list_connections' tool. Request key is most deterministic."
+    ),
+  message: z.string().describe('The text message content to send.'),
+  disableMonitoring: z.boolean().optional().default(false),
+});
+
+/**
+ * A tool to send a message to an agent over an established HCS-10 connection.
+ */
+export class SendMessageToConnectionTool extends BaseHCS10TransactionTool<
+  typeof SendMessageToConnectionZodSchema
+> {
+  name = 'send_message_to_connection';
+  description =
+    "Sends a text message to another agent using an existing active connection. Identify the target agent using their account ID (e.g., 0.0.12345) or the connection number shown in 'list_connections'. Return back the reply from the target agent if possible";
+  specificInputSchema = SendMessageToConnectionZodSchema;
+  constructor(params: HCS10TransactionToolParams) {
+    super(params);
+    this.requiresMultipleTransactions = true;
+    this.neverScheduleThisTool = true;
+  }
+
+  protected async callBuilderMethod(
+    builder: BaseServiceBuilder,
+    specificArgs: z.infer<typeof SendMessageToConnectionZodSchema>
+  ): Promise<void> {
+    const hcs10Builder = builder as HCS10Builder;
+
+    await hcs10Builder.sendMessageToConnection({
+      targetIdentifier: specificArgs.targetIdentifier,
+      message: specificArgs.message,
+      disableMonitoring: specificArgs.disableMonitoring,
+    });
+  }
+}

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

@@ -0,0 +1,65 @@
+import {
+  BaseHederaTransactionTool,
+  BaseHederaQueryTool,
+  BaseServiceBuilder,
+} from 'hedera-agent-kit';
+import { HCS10Builder } from '../../builders/hcs10/hcs10-builder';
+import {
+  HCS10TransactionToolParams,
+  HCS10QueryToolParams,
+} from './hcs10-tool-params';
+import { z } from 'zod';
+
+/**
+ * Base class for HCS10 transaction tools
+ */
+export abstract class BaseHCS10TransactionTool<
+  T extends z.ZodObject<
+    z.ZodRawShape,
+    z.UnknownKeysParam,
+    z.ZodTypeAny
+  > = z.ZodObject<z.ZodRawShape>
+> extends BaseHederaTransactionTool<T> {
+  protected hcs10Builder: HCS10Builder;
+  namespace = 'hcs10' as const;
+
+  constructor(params: HCS10TransactionToolParams) {
+    super(params);
+    this.hcs10Builder = params.hcs10Builder;
+  }
+
+  /**
+   * Override to return the HCS10Builder
+   */
+  protected getServiceBuilder(): BaseServiceBuilder {
+    return this.hcs10Builder;
+  }
+}
+
+/**
+ * Base class for HCS10 query tools
+ */
+export abstract class BaseHCS10QueryTool<
+  T extends z.ZodObject<
+    z.ZodRawShape,
+    z.UnknownKeysParam,
+    z.ZodTypeAny,
+    Record<string, unknown>,
+    Record<string, unknown>
+  > = z.ZodObject<z.ZodRawShape>
+> extends BaseHederaQueryTool<T> {
+  protected hcs10Builder: HCS10Builder;
+  namespace = 'hcs10' as const;
+
+  constructor(params: HCS10QueryToolParams) {
+    super(params);
+    this.hcs10Builder = params.hcs10Builder;
+  }
+
+  /**
+   * Override to return the HCS10Builder
+   */
+  protected getServiceBuilder(): BaseServiceBuilder {
+    return this.hcs10Builder;
+  }
+}

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

@@ -0,0 +1,21 @@
+import { HederaAgentKit } from 'hedera-agent-kit';
+import type { BasePluginContext } from 'hedera-agent-kit';
+import { HCS10Builder } from '../../builders/hcs10/hcs10-builder';
+
+/**
+ * Parameters for HCS10 transaction tools
+ */
+export interface HCS10TransactionToolParams {
+  hederaKit: HederaAgentKit;
+  hcs10Builder: HCS10Builder;
+  logger?: BasePluginContext['logger'];
+}
+
+/**
+ * Parameters for HCS10 query tools
+ */
+export interface HCS10QueryToolParams {
+  hederaKit: HederaAgentKit;
+  hcs10Builder: HCS10Builder;
+  logger?: BasePluginContext['logger'];
+}

package/src/tools/hcs10/index.ts

@@ -0,0 +1,13 @@
+export * from './base-hcs10-tools';
+export * from './hcs10-tool-params';
+export * from './RegisterAgentTool';
+export * from './SendMessageToConnectionTool';
+export * from './InitiateConnectionTool';
+export * from './ListConnectionsTool';
+export * from './CheckMessagesTool';
+export * from './FindRegistrationsTool';
+export * from './ConnectionMonitorTool';
+export * from './ManageConnectionRequestsTool';
+export * from './AcceptConnectionRequestTool';
+export * from './RetrieveProfileTool';
+export * from './ListUnapprovedConnectionRequestsTool';

package/src/tools/index.ts

@@ -1,13 +1,2 @@
-export * from './RegisterAgentTool';
-export * from './SendMessageTool';
-export * from './ConnectionTool';
-export * from './SendMessageToConnectionTool';
-export * from './InitiateConnectionTool';
-export * from './ListConnectionsTool';
-export * from './CheckMessagesTool';
-export * from './FindRegistrationsTool';
-export * from './ConnectionMonitorTool';
-export * from './ManageConnectionRequestsTool';
-export * from './AcceptConnectionRequestTool';
-export * from './RetrieveProfileTool';
-export * from './ListUnapprovedConnectionRequestsTool';
+// Export all HCS10 tools from the subdirectory
+export * from './hcs10';

package/src/utils/HederaClient.ts

@@ -44,9 +44,9 @@ export class HederaClient {
             .setStartTime(0);
 
         try {
-            const subscription = query.subscribe(
+            query.subscribe(
                 this.client,
-                (message: TopicMessage | null, error: Error) => {
+                (_message: TopicMessage | null, error: Error) => {
                     if (error) {
                         onError(error);
                     }

package/src/utils/ensure-agent-has-hbar.ts

@@ -1,5 +1,4 @@
-import { Hbar } from "@hashgraph/sdk";
-import { TransferTransaction } from "@hashgraph/sdk";
+import { Hbar, TransferTransaction, Client } from "@hashgraph/sdk";
 import { Logger, HCS10Client, HederaMirrorNode } from "@hashgraphonline/standards-sdk";
 
 export const MIN_REQUIRED_USD = 2.0;
@@ -60,9 +59,9 @@ export async function ensureAgentHasEnoughHbar(
               );
 
               const fundTxResponse = await transferTx.execute(
-                baseClient.getClient() as any
+                baseClient.getClient() as Client
               );
-              await fundTxResponse.getReceipt(baseClient.getClient() as any);
+              await fundTxResponse.getReceipt(baseClient.getClient() as Client);
               logger.info(
                 `Successfully funded ${agentName} account ${accountId}.`
               );