@hashgraphonline/standards-agent-kit 0.0.37 → 0.2.0

package/src/plugins/README.md

@@ -1,113 +0,0 @@
-# Plugin Architecture
-
-This directory contains a flexible plugin architecture that allows for both platform-specific and platform-agnostic plugins. The goal is to maintain type safety while promoting code reuse across different platforms.
-
-## Core Components
-
-### Plugin Interfaces
-
-- **BasePluginContext**: The foundation for all plugin contexts, includes logging and configuration.
-- **IPluginClient**: A minimal client interface that all platforms should implement.
-- **IPluginStateManager**: A minimal state manager interface for plugin operations.
-- **GenericPluginContext**: Context for platform-agnostic plugins.
-- **PluginContext**: Context specifically for HCS10-based plugins.
-
-### Plugin Implementations
-
-- **BasePlugin**: Abstract base class that implements the core plugin functionality.
-- **GenericPlugin**: For platform-agnostic plugins that work across implementations.
-- **HCS10Plugin**: For plugins that require HCS10-specific functionality.
-
-## Creating Plugins
-
-### Generic Plugin Example
-
-Generic plugins can be used across different platforms as long as the platform implements the required interfaces:
-
-```typescript
-import { GenericPlugin } from '../src/plugins/GenericPlugin';
-import { GenericPluginContext } from '../src/plugins/PluginInterface';
-import { StructuredTool } from '@langchain/core/tools';
-import { DynamicStructuredTool } from '@langchain/core/tools';
-import { z } from 'zod';
-
-export class MyGenericPlugin extends GenericPlugin {
-  id = 'my-generic-plugin';
-  name = 'My Plugin';
-  description = 'A cross-platform plugin';
-  version = '1.0.0';
-  author = 'Your Name';
- 
-  async initialize(context: GenericPluginContext): Promise<void> {
-    await super.initialize(context);
-    // Your initialization code
-  }
-
-  getTools(): StructuredTool[] {
-    return [
-      new DynamicStructuredTool({
-        name: 'my_tool',
-        description: 'Does something useful',
-        schema: z.object({
-          param: z.string().describe('Parameter description'),
-        }),
-        func: async ({ param }: { param: string }): Promise<string> => {
-          // Tool implementation
-          return `Result: ${param}, Network: ${this.context.client.getNetwork()}`;
-        },
-      }),
-    ];
-  }
-}
-```
-
-### HCS10-Specific Plugin Example
-
-For plugins that need the full HCS10 functionality:
-
-```typescript
-import { HCS10Plugin } from '../src/plugins/HCS10Plugin';
-import { PluginContext } from '../src/plugins/PluginInterface';
-import { DynamicStructuredTool } from '@langchain/core/tools';
-import { z } from 'zod';
-
-export class MyHCS10Plugin extends HCS10Plugin {
-  id = 'my-hcs10-plugin';
-  name = 'HCS10 Plugin';
-  description = 'An HCS10-specific plugin';
-  version = '1.0.0';
-  author = 'Your Name';
- 
-  async initialize(context: PluginContext): Promise<void> {
-    await super.initialize(context);
-    // Your HCS10-specific initialization
-  }
-
-  getTools(): StructuredTool[] {
-    return [
-      new DynamicStructuredTool({
-        name: 'hcs10_specific_tool',
-        description: 'Uses HCS10-specific functionality',
-        schema: z.object({
-          param: z.string().describe('Parameter description'),
-        }),
-        func: async ({ param }: { param: string }): Promise<string> => {
-          // HCS10-specific implementation
-          return `HCS10 Result for ${param}`;
-        },
-      }),
-    ];
-  }
-}
-```
-
-## Using in Different Platforms
-
-To integrate this plugin system with other platforms:
-
-1. Implement the `IPluginClient` interface in your platform's client
-2. Optionally implement `IPluginStateManager` for state management
-3. Create a context factory that provides the appropriate context type
-4. Load plugins using the same loading mechanism
-
-This architecture allows reusing generic plugins across platforms while maintaining the ability to create platform-specific plugins when needed.

package/src/plugins/openconvai/OpenConvAIPlugin.ts

@@ -1,124 +0,0 @@
-import { GenericPlugin } from '../GenericPlugin';
-import { GenericPluginContext } from '../PluginInterface';
-import { StructuredTool } from '@langchain/core/tools';
-import { HCS10Client } from '../../hcs10/HCS10Client';
-import { IStateManager } from '../../state/state-types';
-import { OpenConvaiState } from '../../state/open-convai-state';
-
-import { RegisterAgentTool } from '../../tools/RegisterAgentTool';
-import { SendMessageTool } from '../../tools/SendMessageTool';
-import { ConnectionTool } from '../../tools/ConnectionTool';
-import { FindRegistrationsTool } from '../../tools/FindRegistrationsTool';
-import { InitiateConnectionTool } from '../../tools/InitiateConnectionTool';
-import { ListConnectionsTool } from '../../tools/ListConnectionsTool';
-import { SendMessageToConnectionTool } from '../../tools/SendMessageToConnectionTool';
-import { CheckMessagesTool } from '../../tools/CheckMessagesTool';
-import { ConnectionMonitorTool } from '../../tools/ConnectionMonitorTool';
-import { ManageConnectionRequestsTool } from '../../tools/ManageConnectionRequestsTool';
-import { AcceptConnectionRequestTool } from '../../tools/AcceptConnectionRequestTool';
-import { RetrieveProfileTool } from '../../tools/RetrieveProfileTool';
-import { ListUnapprovedConnectionRequestsTool } from '../../tools/ListUnapprovedConnectionRequestsTool';
-
-/**
- * OpenConvAI Plugin that provides all the tools from standards-agent-kit
- * This plugin enables full HCS-10 agent functionality including registration,
- * connection management, and messaging capabilities.
- */
-export class OpenConvAIPlugin extends GenericPlugin {
-  id = 'openconvai-standards-agent-kit';
-  name = 'OpenConvAI Standards Agent Kit Plugin';
-  description =
-    'Comprehensive plugin providing all HCS-10 agent tools for registration, connections, and messaging';
-  version = '1.0.0';
-  author = 'Hashgraph Online';
-  namespace = 'openconvai';
-
-  private hcs10Client?: HCS10Client;
-  private stateManager?: IStateManager;
-  private tools: StructuredTool[] = [];
-
-  override async initialize(context: GenericPluginContext): Promise<void> {
-    await super.initialize(context);
-
-    if (!(context.client instanceof HCS10Client)) {
-      throw new Error('OpenConvAIPlugin requires an HCS10Client instance');
-    }
-
-    this.hcs10Client = context.client as HCS10Client;
-
-    this.stateManager =
-      (context.stateManager as IStateManager) || new OpenConvaiState();
-
-    this.initializeTools();
-
-    this.context.logger.info(
-      'OpenConvAI Standards Agent Kit Plugin initialized successfully'
-    );
-  }
-
-  private initializeTools(): void {
-    if (!this.hcs10Client || !this.stateManager) {
-      throw new Error(
-        'HCS10Client and StateManager must be initialized before creating tools'
-      );
-    }
-
-    this.tools = [
-      new RegisterAgentTool(this.hcs10Client, this.stateManager),
-      new SendMessageTool(this.hcs10Client),
-      new ConnectionTool({
-        client: this.hcs10Client,
-        stateManager: this.stateManager,
-      }),
-      new FindRegistrationsTool({
-        hcsClient: this.hcs10Client,
-      }),
-      new RetrieveProfileTool(this.hcs10Client),
-      new InitiateConnectionTool({
-        hcsClient: this.hcs10Client,
-        stateManager: this.stateManager,
-      }),
-      new ListConnectionsTool({
-        hcsClient: this.hcs10Client,
-        stateManager: this.stateManager,
-      }),
-      new SendMessageToConnectionTool({
-        hcsClient: this.hcs10Client,
-        stateManager: this.stateManager,
-      }),
-      new CheckMessagesTool({
-        hcsClient: this.hcs10Client,
-        stateManager: this.stateManager,
-      }),
-      new ConnectionMonitorTool({
-        hcsClient: this.hcs10Client,
-        stateManager: this.stateManager,
-      }),
-      new ManageConnectionRequestsTool({
-        hcsClient: this.hcs10Client,
-        stateManager: this.stateManager,
-      }),
-      new AcceptConnectionRequestTool({
-        hcsClient: this.hcs10Client,
-        stateManager: this.stateManager,
-      }),
-      new ListUnapprovedConnectionRequestsTool({
-        stateManager: this.stateManager,
-        hcsClient: this.hcs10Client,
-      }),
-    ];
-  }
-
-  getTools(): StructuredTool[] {
-    return this.tools;
-  }
-
-  override async cleanup(): Promise<void> {
-    this.tools = [];
-    this.hcs10Client = undefined;
-    this.stateManager = undefined;
-    this.context.logger.info(
-      'OpenConvAI Standards Agent Kit Plugin cleaned up'
-    );
-  }
-}

package/src/plugins/openconvai/index.ts

@@ -1 +0,0 @@
-export * from './OpenConvAIPlugin';

package/src/tools/AcceptConnectionRequestTool.ts

@@ -1,196 +0,0 @@
-import { StructuredTool, ToolParams } from '@langchain/core/tools';
-import { z } from 'zod';
-import { HCS10Client } from '../hcs10/HCS10Client';
-import { IStateManager, ActiveConnection } from '../state/state-types';
-import { Logger, FeeConfigBuilder } from '@hashgraphonline/standards-sdk';
-
-export interface AcceptConnectionRequestToolParams extends ToolParams {
-  hcsClient: HCS10Client;
-  stateManager: IStateManager;
-}
-
-/**
- * A tool specifically for accepting incoming connection requests.
- */
-export class AcceptConnectionRequestTool extends StructuredTool {
-  name = 'accept_connection_request';
-  description =
-    'Accepts a specific pending connection request from another agent, establishing a communication channel.';
-  schema = 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.'
-      ),
-  });
-
-  private hcsClient: HCS10Client;
-  private stateManager: IStateManager;
-  private logger: Logger;
-
-  constructor({
-    hcsClient,
-    stateManager,
-    ...rest
-  }: AcceptConnectionRequestToolParams) {
-    super(rest);
-    this.hcsClient = hcsClient;
-    this.stateManager = stateManager;
-    this.logger = Logger.getInstance({
-      module: 'AcceptConnectionRequestTool',
-    });
-  }
-
-  protected async _call({
-    requestKey,
-    hbarFee,
-    exemptAccountIds,
-  }: z.infer<this['schema']>): Promise<string> {
-    const currentAgent = this.stateManager.getCurrentAgent();
-    if (!currentAgent) {
-      return 'Error: Cannot accept connection request. No agent is currently active. Please register or select an agent first.';
-    }
-
-    const connectionsManager = this.stateManager.getConnectionsManager();
-    if (!connectionsManager) {
-      return 'Error: ConnectionsManager not initialized';
-    }
-
-    await connectionsManager.fetchConnectionData(currentAgent.accountId);
-
-    // Find the request with the matching unique key or fallback to sequence number
-    const allRequests = [
-      ...connectionsManager.getPendingRequests(),
-      ...connectionsManager.getConnectionsNeedingConfirmation()
-    ];
-
-    const request = allRequests.find(
-      (r) => (r.uniqueRequestKey === requestKey) ||
-        (r.connectionRequestId?.toString() === requestKey) ||
-        (r.inboundRequestId?.toString() === requestKey)
-    );
-
-    if (!request) {
-      return `Error: Request with key ${requestKey} not found or no longer pending. Use the manage_connection_requests tool with action="list" to verify.`;
-    }
-
-    // Get the numeric request ID from the request for the SDK call
-    const numericRequestId = request.connectionRequestId || request.inboundRequestId;
-    if (!numericRequestId) {
-      return `Error: Could not determine a valid request ID for the request with key ${requestKey}.`;
-    }
-
-    try {
-      const inboundTopicId = await this.hcsClient.getInboundTopicId();
-      let feeConfigBuilder = undefined;
-
-      if (hbarFee && hbarFee > 0) {
-        const collectorId = this.hcsClient.getAccountAndSigner().accountId;
-        try {
-          feeConfigBuilder = new FeeConfigBuilder({
-            network: this.hcsClient.getNetwork(),
-            logger: this.logger,
-            defaultCollectorAccountId: collectorId,
-          });
-
-          const finalExemptions = [
-            ...(exemptAccountIds || []),
-            currentAgent.accountId,
-          ];
-          feeConfigBuilder.addHbarFee(hbarFee, collectorId, finalExemptions);
-          this.logger.info(
-            `Setting HBAR fee: ${hbarFee} HBAR to be collected by ${collectorId}`
-          );
-        } catch (feeConfigError) {
-          this.logger.error(
-            `Error creating fee configuration: ${feeConfigError}`
-          );
-
-          feeConfigBuilder = undefined;
-          this.logger.warn(
-            'Proceeding to accept request without fees due to configuration error.'
-          );
-        }
-      }
-
-      this.logger.info(
-        `Attempting to accept request Key: ${requestKey} (ID: ${numericRequestId}) from ${request.targetAccountId}`
-      );
-      const result = await this.hcsClient.handleConnectionRequest(
-        inboundTopicId,
-        request.targetAccountId,
-        numericRequestId,
-        feeConfigBuilder
-      );
-
-      if (!result?.connectionTopicId) {
-        return `Error: Failed to accept connection request with key ${requestKey}. The SDK did not return a connection topic ID.`;
-      }
-      this.logger.info(
-        `Successfully created connection topic: ${result.connectionTopicId}`
-      );
-
-      const connectionTopicId = result.connectionTopicId;
-
-      let targetInboundTopic = '';
-      try {
-        const targetProfileData = await this.hcsClient.standardClient.retrieveProfile(request.targetAccountId);
-        targetInboundTopic =
-          targetProfileData?.topicInfo?.inboundTopic || '';
-        if (!targetInboundTopic) {
-          this.logger.warn(
-            `Could not resolve target inbound topic for ${request.targetAccountId}`
-          );
-        }
-      } catch (e) {
-        this.logger.warn(
-          `Error fetching target profile/topic for ${request.targetAccountId}: ${e}`
-        );
-      }
-
-      const name = request.profileInfo?.display_name || request.profileInfo?.alias || `Agent ${request.targetAccountId}`;
-      const newConnection: ActiveConnection = {
-        targetAccountId: request.targetAccountId,
-        targetAgentName: name,
-        targetInboundTopicId: targetInboundTopic,
-        connectionTopicId,
-        profileInfo: request.profileInfo,
-        created: new Date(),
-        status: 'established',
-      };
-
-      this.stateManager.addActiveConnection(newConnection);
-      connectionsManager.fetchConnectionData(request.targetAccountId);
-
-      this.logger.info(`Removed request ${requestKey} from pending requests`);
-
-      let feeMessage = '';
-      if (hbarFee && hbarFee > 0 && feeConfigBuilder) {
-        feeMessage = ` with a ${hbarFee} HBAR fee per message`;
-      }
-
-      const displayKey = request.uniqueRequestKey || requestKey;
-      return `Successfully accepted connection request ${displayKey} from ${name} ${feeMessage}. Connection established on topic: ${connectionTopicId}.`;
-    } catch (error) {
-      this.logger.error(
-        `Error accepting connection request ${requestKey}: ${error}`
-      );
-
-      return `Error accepting connection request ${requestKey}: ${
-        error instanceof Error ? error.message : String(error)
-      }`;
-    }
-  }
-}

package/src/tools/CheckMessagesTool.ts

@@ -1,194 +0,0 @@
-import { StructuredTool, ToolParams } from '@langchain/core/tools';
-import { z } from 'zod';
-import { HCS10Client, HCSMessageWithTimestamp } from '../hcs10/HCS10Client';
-import { IStateManager } from '../state/state-types';
-import { Logger } from '@hashgraphonline/standards-sdk'; // Assuming logger utility
-
-export interface CheckMessagesToolParams extends ToolParams {
-  hcsClient: HCS10Client;
-  stateManager: IStateManager;
-}
-
-/**
- * A tool to check for new messages on an active HCS-10 connection topic,
- * or optionally fetch the latest messages regardless of timestamp.
- */
-export class CheckMessagesTool extends StructuredTool {
-  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).`;
-  schema = 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.'
-      ),
-  });
-
-  public hcsClient: HCS10Client;
-  private stateManager: IStateManager;
-  private logger: Logger;
-
-  constructor({ hcsClient, stateManager, ...rest }: CheckMessagesToolParams) {
-    super(rest);
-    this.hcsClient = hcsClient;
-    this.stateManager = stateManager;
-    this.logger = Logger.getInstance({ module: 'CheckMessagesTool' });
-  }
-
-  protected async _call({
-    targetIdentifier,
-    fetchLatest,
-    lastMessagesCount,
-  }: z.infer<this['schema']>): Promise<string> {
-    const connection =
-      this.stateManager.getConnectionByIdentifier(targetIdentifier);
-
-    if (!connection) {
-      return `Error: Could not find an active connection matching identifier "${targetIdentifier}". Use 'list_connections' to see active connections.`;
-    }
-
-    const connectionTopicId = connection.connectionTopicId;
-    const targetAgentName = connection.targetAgentName;
-    const lastProcessedTimestamp =
-      this.stateManager.getLastTimestamp(connectionTopicId);
-
-    this.logger.info(
-      `Checking messages for connection with ${targetAgentName} (${connection.targetAccountId}) on topic ${connectionTopicId} (fetchLatest: ${fetchLatest}, lastCount: ${lastMessagesCount}, since: ${lastProcessedTimestamp})`
-    );
-
-    try {
-      // 1. Get messages from the topic
-      const result = await this.hcsClient.getMessages(connectionTopicId);
-      const allMessages = result.messages;
-
-      if (!allMessages || allMessages.length === 0) {
-        return `No messages found on connection topic ${connectionTopicId}.`;
-      }
-
-      let messagesToProcess: HCSMessageWithTimestamp[] = [];
-      let latestTimestampNanos = lastProcessedTimestamp;
-      const isFetchingLatest = fetchLatest === true;
-
-      if (isFetchingLatest) {
-        this.logger.info('Fetching latest messages regardless of timestamp.');
-        const count = lastMessagesCount ?? 1;
-        messagesToProcess = allMessages.slice(-count);
-      } else {
-        this.logger.info(
-          `Filtering for messages newer than ${lastProcessedTimestamp}`
-        );
-        messagesToProcess = allMessages.filter((msg) => {
-          const msgTimestampNanos = msg.timestamp * 1_000_000;
-          return msgTimestampNanos > lastProcessedTimestamp;
-        });
-        
-        if (messagesToProcess.length > 0) {
-          latestTimestampNanos = messagesToProcess.reduce(
-            (maxTs, msg) => Math.max(maxTs, msg.timestamp * 1_000_000),
-             lastProcessedTimestamp
-          );
-        }
-      }
-
-      if (messagesToProcess.length === 0) {
-        return isFetchingLatest
-          ? `Could not retrieve the latest message(s). No messages found on topic ${connectionTopicId}.`
-          : `No new messages found for connection with ${targetAgentName} since last check.`;
-      }
-
-      this.logger.info(`Processing ${messagesToProcess.length} message(s).`);
-
-      // 3. Process messages (resolve inscriptions, format)
-      let outputString = isFetchingLatest
-        ? `Latest message(s) from ${targetAgentName}:
-`
-        : `New messages from ${targetAgentName}:
-`;
-
-      for (const msg of messagesToProcess) {
-        let content = msg.data;
-        try {
-          // Check for inscription HRL
-          if (typeof content === 'string' && content.startsWith('hcs://')) {
-            this.logger.debug(`Resolving inscribed message: ${content}`);
-            content = await this.hcsClient.getMessageContent(content);
-            this.logger.debug(`Resolved content length: ${content?.length}`);
-          }
-
-          // Attempt to parse the content as the HCS-10 structure
-          let displayContent = content; // Default to raw content
-          try {
-            const parsed = JSON.parse(content || '{}');
-            if (
-              parsed.p === 'hcs-10' &&
-              parsed.op === 'message' &&
-              parsed.data
-            ) {
-              // Extract sender and actual data from standard message format
-              const senderOpId = parsed.operator_id || 'unknown_sender';
-              displayContent = `[${senderOpId}]: ${parsed.data}`;
-            } else {
-              // If not standard format, maybe just show raw stringified version
-              displayContent = content; // Keep raw if parsing worked but not expected format
-            }
-          } catch (parseError) {
-            // Content wasn't JSON, keep raw content
-            displayContent = content;
-          }
-
-          const messageDate = new Date(msg.timestamp);
-          outputString += `\n[${messageDate.toLocaleString()}] (Seq: ${
-            msg.sequence_number
-          })
-${displayContent}
-`;
-        } catch (error) {
-          const errorMsg = `Error processing message (Seq: ${
-            msg.sequence_number
-          }): ${error instanceof Error ? error.message : String(error)}`;
-          this.logger.error(errorMsg);
-          outputString += `\n[Error processing message Seq: ${msg.sequence_number}]\n`;
-        }
-      }
-
-      // 4. Update the timestamp in demo state ONLY if fetching NEW messages
-      if (!isFetchingLatest && latestTimestampNanos > lastProcessedTimestamp) {
-        this.logger.debug(
-          `Updating timestamp for topic ${connectionTopicId} to ${latestTimestampNanos}`
-        );
-        this.stateManager.updateTimestamp(
-          connectionTopicId,
-          latestTimestampNanos
-        );
-      }
-
-      return outputString.trim();
-    } catch (error) {
-      this.logger.error(
-        `Failed to check messages for topic ${connectionTopicId}: ${error}`
-      );
-      return `Error checking messages for ${targetAgentName}: ${
-        error instanceof Error ? error.message : String(error)
-      }`;
-    }
-  }
-}