@hashgraphonline/standards-agent-kit 0.0.37 → 0.2.0

package/src/plugins/hedera/HbarPricePlugin.ts

@@ -1,118 +1,37 @@
-import { StructuredTool } from '@langchain/core/tools';
-import { z } from 'zod';
-import { IPlugin /*, PluginContext */ } from '../PluginInterface';
-import axios from 'axios'; // Use axios instead of node-fetch
+// Re-export the HBAR price tool from hedera-agent-kit
+export { HederaGetHbarPriceTool as GetHbarPriceTool } from 'hedera-agent-kit';
 
-const HEDERA_MIRROR_NODE_API = 'https://mainnet.mirrornode.hedera.com/api/v1';
+import { BasePlugin, GenericPluginContext, HederaTool, HederaAgentKit } from 'hedera-agent-kit';
+import { HederaGetHbarPriceTool } from 'hedera-agent-kit';
 
 /**
- * Defines the schema for the HBAR price API response.
- */
-const ExchangeRateResponseSchema = z.object({
-  current_rate: z.object({
-    cent_equivalent: z.number(),
-    hbar_equivalent: z.number(),
-    expiration_time: z.number(),
-  }),
-  next_rate: z.object({
-    cent_equivalent: z.number(),
-    hbar_equivalent: z.number(),
-    expiration_time: z.number(),
-  }),
-  timestamp: z.string(),
-});
-
-/**
- * A Langchain tool to get the current HBAR price in USD.
- */
-// Export the class for testing purposes
-export class GetHbarPriceTool extends StructuredTool {
-  name = 'getHbarPrice';
-  description = 'Retrieves the current price of HBAR in USD from the Hedera Mirror Node.';
-  schema = z.object({}); // No input required for this tool
-
-  /**
-   * DISCLAIMER: THIS TOOL USES THE EXCHANGE RATE ENDPOINT FROM THE MIRROR NODE, AND IT IS NOT GUARANTEED TO BE ACCURATE.
-   * USE AN ORACLE OR OTHER SOURCES FOR PRODUCTION USE WHERE PRICE IS IMPORTANT.
-   * Retrieves the current price of HBAR in USD from the Hedera Mirror Node.
-   * @returns A promise that resolves to a string containing the current HBAR price in USD.
-   */
-  protected async _call(): Promise<string> {
-    try {
-      // Use axios.get instead of fetch
-      const response = await axios.get(`${HEDERA_MIRROR_NODE_API}/network/exchangerate`);
-
-      // Axios puts data directly in response.data
-      const data: unknown = response.data;
-
-      // Validate the response structure
-      const parsedData = ExchangeRateResponseSchema.safeParse(data);
-      if (!parsedData.success) {
-         console.error("Failed to parse exchange rate response:", parsedData.error);
-         throw new Error('Invalid API response format');
-      }
-
-      const { current_rate } = parsedData.data;
-      const priceUsd = current_rate.cent_equivalent / current_rate.hbar_equivalent / 100;
-
-      return `The current price of HBAR is $${priceUsd.toFixed(6)} USD.`;
-    } catch (error) {
-      console.error('Error fetching HBAR price:', error);
-      // Handle axios errors specifically if needed, otherwise generic handling
-      let errorMessage = 'An unknown error occurred';
-      if (axios.isAxiosError(error)) {
-        errorMessage = error.message;
-        if (error.response) {
-          errorMessage += ` (Status: ${error.response.status})`;
-        }
-      } else if (error instanceof Error) {
-        errorMessage = error.message;
-      }
-      return `Failed to retrieve HBAR price: ${errorMessage}`;
-    }
-  }
-}
-
-
-/**
- * DISCLAIMER: THIS PLUGIN USES THE EXCHANGE RATE ENDPOINT FROM THE MIRROR NODE, AND IT IS NOT GUARANTEED TO BE ACCURATE.
- * USE AN ORACLE OR OTHER SOURCES FOR PRODUCTION USE WHERE PRICE IS IMPORTANT.
  * Plugin to provide tools related to Hedera network information, like HBAR price.
+ * Uses the built-in HederaGetHbarPriceTool from hedera-agent-kit.
  */
-export class HbarPricePlugin implements IPlugin {
+export class HbarPricePlugin extends BasePlugin<GenericPluginContext> {
   id = 'hedera-hbar-price';
   name = 'Hedera HBAR Price Plugin';
   description = 'Provides tools to interact with Hedera network data, specifically HBAR price.';
   version = '1.0.0';
-  author = 'Hedera Agent'; // Replace with actual author/team name if desired
+  author = 'Hashgraph Online';
 
-  private tools: StructuredTool[];
+  private tools: HederaTool[] = [];
 
-  constructor() {
-    this.tools = [new GetHbarPriceTool()];
+  override async initialize(context: GenericPluginContext): Promise<void> {
+    await super.initialize(context);
+    this.initializeTools();
   }
 
-  /**
-   * Initializes the plugin. Currently no specific initialization needed.
-   */
-  async initialize(): Promise<void> {
-    // No specific initialization required for this plugin yet
-    return Promise.resolve();
+  private initializeTools(): void {
+    this.tools = [
+      new HederaGetHbarPriceTool({
+        hederaKit: this.context.config.hederaKit as HederaAgentKit,
+        logger: this.context.logger
+      })
+    ];
   }
 
-  /**
-   * Returns the tools provided by this plugin.
-   * @returns An array containing the GetHbarPriceTool.
-   */
-  getTools(): StructuredTool[] {
+  getTools(): HederaTool[] {
     return this.tools;
   }
-
-  /**
-   * Cleans up resources. Currently no cleanup needed.
-   */
-  async cleanup(): Promise<void> {
-    // No cleanup necessary
-    return Promise.resolve();
-  }
 }

package/src/plugins/index.ts

@@ -1,8 +1,3 @@
 export * from './PluginInterface';
 export * from './PluginRegistry';
-export * from './BasePlugin';
-export * from './PluginLoader';
 export * from './hedera/HbarPricePlugin';
-export * from './GenericPlugin';
-export * from './openconvai';
-export * from './HCS10Plugin';

package/src/plugins/weather/index.ts

@@ -1,5 +1,4 @@
-import { GenericPlugin, GenericPluginContext } from '../../../src/plugins';
-import { StructuredTool } from '@langchain/core/tools';
+import { BasePlugin, GenericPluginContext, BaseHederaQueryTool, HederaTool, HederaAgentKit } from 'hedera-agent-kit';
 import { z } from 'zod';
 import axios from 'axios';
 
@@ -22,26 +21,31 @@ interface ForecastDayData {
  * an external web service (Weather API in this case).
  */
 
+const GetCurrentWeatherSchema = z.object({
+  location: z.string().describe('The city and state, e.g. San Francisco, CA'),
+  unit: z
+    .enum(['celsius', 'fahrenheit'])
+    .optional()
+    .describe('The unit of temperature'),
+});
+
 /**
  * Tool for getting current weather information
  */
-class GetCurrentWeatherTool extends StructuredTool {
+class GetCurrentWeatherTool extends BaseHederaQueryTool<typeof GetCurrentWeatherSchema> {
   name = 'get_current_weather';
   description = 'Get the current weather for a location';
+  specificInputSchema = GetCurrentWeatherSchema;
+  namespace = 'weather';
 
-  schema = z.object({
-    location: z.string().describe('The city and state, e.g. San Francisco, CA'),
-    unit: z
-      .enum(['celsius', 'fahrenheit'])
-      .optional()
-      .describe('The unit of temperature'),
-  });
-
-  constructor(private apiKey?: string) {
-    super();
+  constructor(params: { hederaKit: HederaAgentKit; logger?: any; apiKey?: string }) {
+    super(params);
+    this.apiKey = params.apiKey;
   }
 
-  async _call(input: z.infer<typeof this.schema>): Promise<string> {
+  private apiKey?: string;
+
+  protected async executeQuery(input: z.infer<typeof GetCurrentWeatherSchema>): Promise<string> {
     if (!this.apiKey) {
       return 'Error: Weather API key not configured. Please set weatherApiKey in the plugin configuration.';
     }
@@ -72,35 +76,37 @@ class GetCurrentWeatherTool extends StructuredTool {
   }
 }
 
+const GetWeatherForecastSchema = z.object({
+  location: z.string().describe('The city and state, e.g. San Francisco, CA'),
+  days: z
+    .number()
+    .min(1)
+    .max(7)
+    .optional()
+    .describe('Number of days for the forecast (1-7, default: 3)'),
+  unit: z
+    .enum(['celsius', 'fahrenheit'])
+    .optional()
+    .describe('The unit of temperature'),
+});
+
 /**
  * Tool for getting weather forecast
  */
-class GetWeatherForecastTool extends StructuredTool {
+class GetWeatherForecastTool extends BaseHederaQueryTool<typeof GetWeatherForecastSchema> {
   name = 'get_weather_forecast';
   description = 'Get the weather forecast for a location';
+  specificInputSchema = GetWeatherForecastSchema;
+  namespace = 'weather';
 
-  schema = z.object({
-    location: z.string().describe('The city and state, e.g. San Francisco, CA'),
-    days: z
-      .number()
-      .min(1)
-      .max(7)
-      .optional()
-      .describe('Number of days for the forecast (1-7, default: 3)'),
-    unit: z
-      .enum(['celsius', 'fahrenheit'])
-      .optional()
-      .describe('The unit of temperature'),
-  });
+  constructor(params: { hederaKit: HederaAgentKit; logger?: any; apiKey?: string }) {
+    super(params);
+    this.apiKey = params.apiKey;
+  }
 
   private apiKey?: string;
 
-  constructor(apiKey?: string) {
-    super();
-    this.apiKey = apiKey;
-  }
-
-  async _call(input: z.infer<typeof this.schema>): Promise<string> {
+  protected async executeQuery(input: z.infer<typeof GetWeatherForecastSchema>): Promise<string> {
     if (!this.apiKey) {
       return 'Error: Weather API key not configured. Please set weatherApiKey in the plugin configuration.';
     }
@@ -148,16 +154,17 @@ class GetWeatherForecastTool extends StructuredTool {
 
 /**
  * Weather API Plugin for the Standards Agent Kit
+ * Uses BaseHederaQueryTool for consistent tool architecture
  */
-export default class WeatherPlugin extends GenericPlugin {
+export default class WeatherPlugin extends BasePlugin<GenericPluginContext> {
   id = 'weather-api';
   name = 'Weather API Plugin';
   description = 'Provides tools to access weather data';
   version = '1.0.0';
   author = 'Hashgraph Online';
-  namespace = 'weather';
 
   private apiKey?: string;
+  private tools: HederaTool[] = [];
 
   override async initialize(context: GenericPluginContext): Promise<void> {
     await super.initialize(context);
@@ -168,12 +175,21 @@ export default class WeatherPlugin extends GenericPlugin {
         'Weather API key not provided. Weather tools will not function correctly.'
       );
     }
+
+    this.initializeTools();
   }
 
-  getTools(): StructuredTool[] {
-    return [
-      new GetCurrentWeatherTool(this.apiKey),
-      new GetWeatherForecastTool(this.apiKey),
+  private initializeTools(): void {
+    const hederaKit = this.context.config.hederaKit as HederaAgentKit;
+    const logger = this.context.logger;
+
+    this.tools = [
+      new GetCurrentWeatherTool({ hederaKit, logger, apiKey: this.apiKey }),
+      new GetWeatherForecastTool({ hederaKit, logger, apiKey: this.apiKey }),
     ];
   }
+
+  override getTools(): HederaTool[] {
+    return this.tools;
+  }
 }

package/src/state/state-types.ts

@@ -1,8 +1,6 @@
 import {
   HCS10BaseClient,
-  ConnectionsManager,
   AIAgentProfile,
-  Connection,
   IConnectionsManager,
 } from '@hashgraphonline/standards-sdk';
 
@@ -106,7 +104,7 @@ export interface IStateManager {
   /**
    * Sets the current active agent, clearing any previous connections.
    */
-  setCurrentAgent(agent: RegisteredAgent | null): void;
+  setCurrentAgent(_agent: RegisteredAgent | null): void;
 
   /**
    * Gets the current active agent.
@@ -117,13 +115,13 @@ export interface IStateManager {
    * Adds a new active connection to the state.
    * Will not add duplicates based on connectionTopicId.
    */
-  addActiveConnection(connection: ActiveConnection): void;
+  addActiveConnection(_connection: ActiveConnection): void;
 
   /**
    * Updates an existing connection or adds it if not found.
    * Preserves existing properties when updating.
    */
-  updateOrAddConnection(connection: ActiveConnection): void;
+  updateOrAddConnection(_connection: ActiveConnection): void;
 
   /**
    * Lists all active connections for the current agent.
@@ -136,25 +134,25 @@ export interface IStateManager {
    * - A target account ID
    * - A connection topic ID
    */
-  getConnectionByIdentifier(identifier: string): ActiveConnection | undefined;
+  getConnectionByIdentifier(_identifier: string): ActiveConnection | undefined;
 
   /**
    * Gets the last processed message timestamp for a connection.
    */
-  getLastTimestamp(connectionTopicId: string): number;
+  getLastTimestamp(_connectionTopicId: string): number;
 
   /**
    * Updates the last processed message timestamp for a connection.
    */
-  updateTimestamp(connectionTopicId: string, timestampNanos: number): void;
+  updateTimestamp(_connectionTopicId: string, _timestampNanos: number): void;
 
   /**
    * Persists agent data to storage
    * Implementation may vary depending on the state manager
    */
   persistAgentData?(
-    agent: RegisteredAgent,
-    options?: AgentPersistenceOptions
+    _agent: RegisteredAgent,
+    _options?: AgentPersistenceOptions
   ): Promise<void>;
 
   /**
@@ -162,7 +160,7 @@ export interface IStateManager {
    * @param baseClient - The HCS10BaseClient instance to use
    * @returns The initialized ConnectionsManager
    */
-  initializeConnectionsManager(baseClient: HCS10BaseClient): IConnectionsManager;
+  initializeConnectionsManager(_baseClient: HCS10BaseClient): IConnectionsManager;
 
   /**
    * Gets the ConnectionsManager instance

package/src/tools/hcs10/AcceptConnectionRequestTool.ts

@@ -0,0 +1,56 @@
+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 AcceptConnectionRequestZodSchema = z.object({
+  requestKey: z
+    .string()
+    .describe(
+      'The unique request key of the specific request to accept. Use the "manage_connection_requests" tool with action="list" first to get valid keys.'
+    ),
+  hbarFee: z
+    .number()
+    .optional()
+    .describe(
+      'Optional HBAR fee amount to charge the connecting agent per message on the new connection topic.'
+    ),
+  exemptAccountIds: z
+    .array(z.string())
+    .optional()
+    .describe(
+      'Optional list of account IDs to exempt from any configured fees on the new connection topic.'
+    ),
+});
+
+/**
+ * Tool for accepting incoming HCS-10 connection requests
+ */
+export class AcceptConnectionRequestTool extends BaseHCS10TransactionTool<
+  typeof AcceptConnectionRequestZodSchema
+> {
+  name = 'accept_connection_request';
+  description =
+    'Accepts a pending HCS-10 connection request from another agent. Use list_unapproved_connection_requests to see pending requests.';
+  specificInputSchema = AcceptConnectionRequestZodSchema;
+
+  constructor(params: HCS10TransactionToolParams) {
+    super(params);
+    this.neverScheduleThisTool = true;
+    this.requiresMultipleTransactions = true;
+  }
+
+  protected async callBuilderMethod(
+    builder: BaseServiceBuilder,
+    specificArgs: z.infer<typeof AcceptConnectionRequestZodSchema>
+  ): Promise<void> {
+    const hcs10Builder = builder as HCS10Builder;
+
+    await hcs10Builder.acceptConnection({
+      requestKey: specificArgs.requestKey,
+      hbarFee: specificArgs.hbarFee,
+      exemptAccountIds: specificArgs.exemptAccountIds,
+    });
+  }
+}

package/src/tools/hcs10/CheckMessagesTool.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import { BaseHCS10QueryTool } from './base-hcs10-tools';
+import { HCS10QueryToolParams } from './hcs10-tool-params';
+
+/**
+ * A tool to check for new messages on an active HCS-10 connection topic,
+ * or optionally fetch the latest messages regardless of timestamp.
+ */
+const CheckMessagesZodSchema = z.object({
+  targetIdentifier: z
+    .string()
+    .describe(
+      "The account ID (e.g., 0.0.12345) of the target agent OR the connection number (e.g., '1', '2') from the 'list_connections' tool to check messages for."
+    ),
+  fetchLatest: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe(
+      'Set to true to fetch the latest messages even if they have been seen before, ignoring the last checked timestamp. Defaults to false (fetching only new messages).'
+    ),
+  lastMessagesCount: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe(
+      'When fetchLatest is true, specifies how many of the most recent messages to retrieve. Defaults to 1.'
+    ),
+});
+
+export class CheckMessagesTool extends BaseHCS10QueryTool<
+  typeof CheckMessagesZodSchema
+> {
+  name = 'check_messages';
+  description = `Checks for and retrieves messages from an active connection.
+Identify the target agent using their account ID (e.g., 0.0.12345) or the connection number shown in 'list_connections'.
+By default, it only retrieves messages newer than the last check.
+Use 'fetchLatest: true' to get the most recent messages regardless of when they arrived.
+Use 'lastMessagesCount' to specify how many latest messages to retrieve (default 1 when fetchLatest is true).`;
+  specificInputSchema = CheckMessagesZodSchema;
+  constructor(params: HCS10QueryToolParams) {
+    super(params);
+  }
+
+  protected async executeQuery({
+    targetIdentifier,
+    fetchLatest,
+    lastMessagesCount,
+  }: z.infer<typeof CheckMessagesZodSchema>): Promise<unknown> {
+    const hcs10Builder = this.hcs10Builder;
+    await hcs10Builder.checkMessages({
+      targetIdentifier,
+      fetchLatest,
+      lastMessagesCount: lastMessagesCount || 1,
+    });
+
+    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 || 'Messages checked',
+      };
+    }
+
+    return result;
+  }
+}

package/src/tools/hcs10/ConnectionMonitorTool.ts

@@ -0,0 +1,111 @@
+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 ConnectionMonitorZodSchema = z.object({
+  acceptAll: z
+    .boolean()
+    .optional()
+    .describe(
+      'Whether to automatically accept all incoming connection requests. Default is false.'
+    ),
+  targetAccountId: z
+    .string()
+    .optional()
+    .describe(
+      'If provided, only accept connection requests from this specific account ID.'
+    ),
+  hbarFees: z
+    .array(
+      z.object({
+        amount: z.number(),
+        collectorAccount: z.string().optional(),
+      })
+    )
+    .optional()
+    .describe(
+      'Array of HBAR fee amounts to charge per message (with optional collector accounts).'
+    ),
+  tokenFees: z
+    .array(
+      z.object({
+        amount: z.number(),
+        tokenId: z.string(),
+        collectorAccount: z.string().optional(),
+      })
+    )
+    .optional()
+    .describe(
+      'Array of token fee amounts and IDs to charge per message (with optional collector accounts).'
+    ),
+  exemptAccountIds: z
+    .array(z.string())
+    .optional()
+    .describe(
+      'Array of account IDs to exempt from ALL fees set in this request.'
+    ),
+  monitorDurationSeconds: z
+    .number()
+    .optional()
+    .describe(
+      'How long to monitor for incoming requests in seconds. Default is 120.'
+    ),
+  defaultCollectorAccount: z
+    .string()
+    .optional()
+    .describe(
+      'Default account to collect fees if not specified at the fee level. Defaults to the agent account.'
+    ),
+});
+
+/**
+ * A tool for monitoring incoming connection requests and accepting them with optional fee settings.
+ */
+export class ConnectionMonitorTool extends BaseHCS10TransactionTool<
+  typeof ConnectionMonitorZodSchema
+> {
+  name = 'monitor_connections';
+  description =
+    'Monitors for incoming connection requests and accepts them with optional fee settings. Use this to watch for connection requests and accept them, optionally setting HBAR or token fees on the connection. Note: When acceptAll=true, this tool requires multiple transactions and cannot be used in returnBytes mode.';
+  specificInputSchema = ConnectionMonitorZodSchema;
+  constructor(params: HCS10TransactionToolParams) {
+    super(params);
+    this.neverScheduleThisTool = true;
+    this.requiresMultipleTransactions = true;
+  }
+
+  protected async callBuilderMethod(
+    builder: BaseServiceBuilder,
+    specificArgs: z.infer<typeof ConnectionMonitorZodSchema>
+  ): Promise<void> {
+    const hcs10Builder = builder as HCS10Builder;
+    await hcs10Builder.monitorConnections({
+      ...(specificArgs.acceptAll !== undefined && {
+        acceptAll: specificArgs.acceptAll,
+      }),
+      ...(specificArgs.targetAccountId !== undefined && {
+        targetAccountId: specificArgs.targetAccountId,
+      }),
+      ...(specificArgs.monitorDurationSeconds !== undefined && {
+        monitorDurationSeconds: specificArgs.monitorDurationSeconds,
+      }),
+      hbarFees: (specificArgs.hbarFees || []) as Array<{
+        amount: number;
+        collectorAccount?: string;
+      }>,
+      tokenFees: (specificArgs.tokenFees || []) as Array<{
+        amount: number;
+        tokenId: string;
+        collectorAccount?: string;
+      }>,
+      ...(specificArgs.exemptAccountIds !== undefined && {
+        exemptAccountIds: specificArgs.exemptAccountIds,
+      }),
+      ...(specificArgs.defaultCollectorAccount !== undefined && {
+        defaultCollectorAccount: specificArgs.defaultCollectorAccount,
+      }),
+    });
+  }
+}

package/src/tools/hcs10/FindRegistrationsTool.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import { AIAgentCapability } from '@hashgraphonline/standards-sdk';
+import { BaseHCS10QueryTool } from './base-hcs10-tools';
+import { HCS10QueryToolParams } from './hcs10-tool-params';
+
+/**
+ * A tool to search for registered HCS-10 agents using the configured registry.
+ */
+const FindRegistrationsZodSchema = z.object({
+  accountId: z
+    .string()
+    .optional()
+    .describe(
+      'Optional: Filter registrations by a specific Hedera account ID (e.g., 0.0.12345).'
+    ),
+  tags: z
+    .array(z.nativeEnum(AIAgentCapability))
+    .optional()
+    .describe(
+      'Optional: Filter registrations by a list of tags (API filter only).'
+    ),
+});
+
+export class FindRegistrationsTool extends BaseHCS10QueryTool<
+  typeof FindRegistrationsZodSchema
+> {
+  name = 'find_registrations';
+  description =
+    'Searches the configured agent registry for HCS-10 agents. You can filter by account ID or tags. Returns basic registration info.';
+  specificInputSchema = FindRegistrationsZodSchema;
+  constructor(params: HCS10QueryToolParams) {
+    super(params);
+  }
+
+  protected async executeQuery({
+    accountId,
+    tags,
+  }: z.infer<typeof FindRegistrationsZodSchema>): Promise<unknown> {
+    const hcs10Builder = this.hcs10Builder;
+    const params: { accountId?: string; tags?: number[] } = {};
+    if (accountId) {
+      params.accountId = accountId;
+    }
+    if (tags) {
+      params.tags = tags;
+    }
+    await hcs10Builder.findRegistrations(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 || 'Registrations searched',
+      };
+    }
+
+    return result;
+  }
+}