@hashgraphonline/standards-agent-kit 0.0.18 → 0.0.19

package/dist/state/open-convai-state.d.ts

@@ -0,0 +1,84 @@
+import { RegisteredAgent, ActiveConnection, ConnectionRequestInfo, IStateManager, AgentPersistenceOptions } from './state-types';
+/**
+ * Implementation of the IStateManager interface for the OpenConvai system.
+ * Manages agent state and connection information with thread safety and
+ * proper timestamp tracking.
+ */
+export declare class OpenConvaiState implements IStateManager {
+    private currentAgent;
+    private activeConnections;
+    private connectionMessageTimestamps;
+    private connectionRequests;
+    private defaultEnvFilePath?;
+    private defaultPrefix;
+    /**
+     * Creates a new OpenConvaiState instance
+     * @param options - Options for environment variable persistence
+     */
+    constructor(options?: {
+        defaultEnvFilePath?: string;
+        defaultPrefix?: string;
+    });
+    /**
+     * Sets the current active agent and clears any previous connection data.
+     * This should be called when switching between agents.
+     */
+    setCurrentAgent(agent: RegisteredAgent | null): void;
+    /**
+     * Returns the currently active agent or null if none is set.
+     */
+    getCurrentAgent(): RegisteredAgent | null;
+    /**
+     * Adds a new connection to the active connections list.
+     * Ensures no duplicates are added based on connectionTopicId.
+     * Initializes timestamp tracking for the connection.
+     */
+    addActiveConnection(connection: ActiveConnection): void;
+    /**
+     * Updates an existing connection or adds it if not found.
+     * Preserves existing properties when updating by merging objects.
+     */
+    updateOrAddConnection(connection: ActiveConnection): void;
+    /**
+     * Returns a copy of all active connections.
+     */
+    listConnections(): ActiveConnection[];
+    /**
+     * Finds a connection by its identifier, which can be:
+     * - A 1-based index as displayed in the connection list
+     * - A target account ID string
+     * - A connection topic ID string
+     */
+    getConnectionByIdentifier(identifier: string): ActiveConnection | undefined;
+    /**
+     * Gets the last processed message timestamp for a connection.
+     * Returns 0 if no timestamp has been recorded.
+     */
+    getLastTimestamp(connectionTopicId: string): number;
+    /**
+     * Updates the last processed message timestamp for a connection,
+     * but only if the new timestamp is more recent than the existing one.
+     */
+    updateTimestamp(connectionTopicId: string, timestampNanos: number): void;
+    /**
+     * Helper method to find a connection's index by its topic ID.
+     * Returns -1 if not found.
+     */
+    private findConnectionIndex;
+    /**
+     * Helper method to initialize timestamp tracking for a connection
+     * if it doesn't already exist.
+     */
+    private initializeTimestampIfNeeded;
+    addConnectionRequest(request: ConnectionRequestInfo): void;
+    listConnectionRequests(): ConnectionRequestInfo[];
+    getConnectionRequestById(requestId: number): ConnectionRequestInfo | undefined;
+    removeConnectionRequest(requestId: number): void;
+    clearConnectionRequests(): void;
+    /**
+     * Persists agent data to environment variables
+     * @param agent - The agent data to persist
+     * @param options - Environment file persistence options
+     */
+    persistAgentData(agent: RegisteredAgent, options?: AgentPersistenceOptions): Promise<void>;
+}

package/dist/state/open-convai-state.js

@@ -0,0 +1,132 @@
+import { updateEnvFile as c } from "../utils/state-tools.js";
+class o {
+  /**
+   * Creates a new OpenConvaiState instance
+   * @param options - Options for environment variable persistence
+   */
+  constructor(e) {
+    this.currentAgent = null, this.activeConnections = [], this.connectionMessageTimestamps = {}, this.connectionRequests = /* @__PURE__ */ new Map(), this.defaultEnvFilePath = e == null ? void 0 : e.defaultEnvFilePath, this.defaultPrefix = (e == null ? void 0 : e.defaultPrefix) ?? "TODD";
+  }
+  /**
+   * Sets the current active agent and clears any previous connection data.
+   * This should be called when switching between agents.
+   */
+  setCurrentAgent(e) {
+    this.currentAgent = e, this.activeConnections = [], this.connectionMessageTimestamps = {}, this.connectionRequests.clear();
+  }
+  /**
+   * Returns the currently active agent or null if none is set.
+   */
+  getCurrentAgent() {
+    return this.currentAgent;
+  }
+  /**
+   * Adds a new connection to the active connections list.
+   * Ensures no duplicates are added based on connectionTopicId.
+   * Initializes timestamp tracking for the connection.
+   */
+  addActiveConnection(e) {
+    this.findConnectionIndex(e.connectionTopicId) === -1 && (this.activeConnections.push({ ...e }), this.initializeTimestampIfNeeded(e.connectionTopicId));
+  }
+  /**
+   * Updates an existing connection or adds it if not found.
+   * Preserves existing properties when updating by merging objects.
+   */
+  updateOrAddConnection(e) {
+    const t = this.findConnectionIndex(e.connectionTopicId);
+    t !== -1 ? this.activeConnections[t] = {
+      ...this.activeConnections[t],
+      ...e
+    } : this.addActiveConnection(e), this.initializeTimestampIfNeeded(e.connectionTopicId);
+  }
+  /**
+   * Returns a copy of all active connections.
+   */
+  listConnections() {
+    return [...this.activeConnections];
+  }
+  /**
+   * Finds a connection by its identifier, which can be:
+   * - A 1-based index as displayed in the connection list
+   * - A target account ID string
+   * - A connection topic ID string
+   */
+  getConnectionByIdentifier(e) {
+    const t = parseInt(e) - 1;
+    return !isNaN(t) && t >= 0 && t < this.activeConnections.length ? this.activeConnections[t] : this.activeConnections.find(
+      (n) => n.targetAccountId === e || n.connectionTopicId === e
+    );
+  }
+  /**
+   * Gets the last processed message timestamp for a connection.
+   * Returns 0 if no timestamp has been recorded.
+   */
+  getLastTimestamp(e) {
+    return this.connectionMessageTimestamps[e] || 0;
+  }
+  /**
+   * Updates the last processed message timestamp for a connection,
+   * but only if the new timestamp is more recent than the existing one.
+   */
+  updateTimestamp(e, t) {
+    if (e in this.connectionMessageTimestamps) {
+      const n = this.connectionMessageTimestamps[e];
+      t > n && (this.connectionMessageTimestamps[e] = t);
+    }
+  }
+  /**
+   * Helper method to find a connection's index by its topic ID.
+   * Returns -1 if not found.
+   */
+  findConnectionIndex(e) {
+    return this.activeConnections.findIndex(
+      (t) => t.connectionTopicId === e
+    );
+  }
+  /**
+   * Helper method to initialize timestamp tracking for a connection
+   * if it doesn't already exist.
+   */
+  initializeTimestampIfNeeded(e) {
+    e in this.connectionMessageTimestamps || (this.connectionMessageTimestamps[e] = Date.now() * 1e6);
+  }
+  addConnectionRequest(e) {
+    this.connectionRequests.set(e.id, { ...e });
+  }
+  listConnectionRequests() {
+    return Array.from(this.connectionRequests.values());
+  }
+  getConnectionRequestById(e) {
+    return this.connectionRequests.get(e);
+  }
+  removeConnectionRequest(e) {
+    this.connectionRequests.delete(e);
+  }
+  clearConnectionRequests() {
+    this.connectionRequests.clear();
+  }
+  /**
+   * Persists agent data to environment variables
+   * @param agent - The agent data to persist
+   * @param options - Environment file persistence options
+   */
+  async persistAgentData(e, t) {
+    if (t != null && t.type && t.type !== "env-file")
+      throw new Error(
+        `Unsupported persistence type: ${t.type}. Only 'env-file' is supported.`
+      );
+    const n = (t == null ? void 0 : t.envFilePath) || this.defaultEnvFilePath || process.env.ENV_FILE_PATH || ".env", i = (t == null ? void 0 : t.prefix) || this.defaultPrefix;
+    if (!e.accountId || !e.inboundTopicId || !e.outboundTopicId)
+      throw new Error("Agent data incomplete, cannot persist to environment");
+    const s = {
+      [`${i}_ACCOUNT_ID`]: e.accountId,
+      [`${i}_INBOUND_TOPIC_ID`]: e.inboundTopicId,
+      [`${i}_OUTBOUND_TOPIC_ID`]: e.outboundTopicId
+    };
+    e.privateKey && (s[`${i}_PRIVATE_KEY`] = e.privateKey), e.profileTopicId && (s[`${i}_PROFILE_TOPIC_ID`] = e.profileTopicId), await c(n, s);
+  }
+}
+export {
+  o as OpenConvaiState
+};
+//# sourceMappingURL=open-convai-state.js.map

package/dist/state/open-convai-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-convai-state.js","sources":["../../src/state/open-convai-state.ts"],"sourcesContent":["import { updateEnvFile } from '../utils/state-tools';\nimport {\n  RegisteredAgent,\n  ActiveConnection,\n  ConnectionRequestInfo,\n  IStateManager,\n  AgentPersistenceOptions,\n  EnvFilePersistenceOptions,\n} from './state-types';\n\n/**\n * Implementation of the IStateManager interface for the OpenConvai system.\n * Manages agent state and connection information with thread safety and\n * proper timestamp tracking.\n */\nexport class OpenConvaiState implements IStateManager {\n  private currentAgent: RegisteredAgent | null = null;\n  private activeConnections: ActiveConnection[] = [];\n  private connectionMessageTimestamps: Record<string, number> = {};\n  private connectionRequests: Map<number, ConnectionRequestInfo> = new Map();\n  private defaultEnvFilePath?: string;\n  private defaultPrefix: string;\n\n  /**\n   * Creates a new OpenConvaiState instance\n   * @param options - Options for environment variable persistence\n   */\n  constructor(options?: {\n    defaultEnvFilePath?: string;\n    defaultPrefix?: string;\n  }) {\n    this.defaultEnvFilePath = options?.defaultEnvFilePath;\n    this.defaultPrefix = options?.defaultPrefix ?? 'TODD';\n  }\n\n  /**\n   * Sets the current active agent and clears any previous connection data.\n   * This should be called when switching between agents.\n   */\n  setCurrentAgent(agent: RegisteredAgent | null): void {\n    this.currentAgent = agent;\n    this.activeConnections = [];\n    this.connectionMessageTimestamps = {};\n    this.connectionRequests.clear();\n  }\n\n  /**\n   * Returns the currently active agent or null if none is set.\n   */\n  getCurrentAgent(): RegisteredAgent | null {\n    return this.currentAgent;\n  }\n\n  /**\n   * Adds a new connection to the active connections list.\n   * Ensures no duplicates are added based on connectionTopicId.\n   * Initializes timestamp tracking for the connection.\n   */\n  addActiveConnection(connection: ActiveConnection): void {\n    if (this.findConnectionIndex(connection.connectionTopicId) !== -1) {\n      return;\n    }\n\n    this.activeConnections.push({ ...connection });\n\n    this.initializeTimestampIfNeeded(connection.connectionTopicId);\n  }\n\n  /**\n   * Updates an existing connection or adds it if not found.\n   * Preserves existing properties when updating by merging objects.\n   */\n  updateOrAddConnection(connection: ActiveConnection): void {\n    const index = this.findConnectionIndex(connection.connectionTopicId);\n\n    if (index !== -1) {\n      this.activeConnections[index] = {\n        ...this.activeConnections[index],\n        ...connection,\n      };\n    } else {\n      this.addActiveConnection(connection);\n    }\n\n    this.initializeTimestampIfNeeded(connection.connectionTopicId);\n  }\n\n  /**\n   * Returns a copy of all active connections.\n   */\n  listConnections(): ActiveConnection[] {\n    return [...this.activeConnections];\n  }\n\n  /**\n   * Finds a connection by its identifier, which can be:\n   * - A 1-based index as displayed in the connection list\n   * - A target account ID string\n   * - A connection topic ID string\n   */\n  getConnectionByIdentifier(identifier: string): ActiveConnection | undefined {\n    const numericIndex = parseInt(identifier) - 1;\n    if (\n      !isNaN(numericIndex) &&\n      numericIndex >= 0 &&\n      numericIndex < this.activeConnections.length\n    ) {\n      return this.activeConnections[numericIndex];\n    }\n\n    return this.activeConnections.find(\n      (conn) =>\n        conn.targetAccountId === identifier ||\n        conn.connectionTopicId === identifier\n    );\n  }\n\n  /**\n   * Gets the last processed message timestamp for a connection.\n   * Returns 0 if no timestamp has been recorded.\n   */\n  getLastTimestamp(connectionTopicId: string): number {\n    return this.connectionMessageTimestamps[connectionTopicId] || 0;\n  }\n\n  /**\n   * Updates the last processed message timestamp for a connection,\n   * but only if the new timestamp is more recent than the existing one.\n   */\n  updateTimestamp(connectionTopicId: string, timestampNanos: number): void {\n    if (connectionTopicId in this.connectionMessageTimestamps) {\n      const currentTimestamp =\n        this.connectionMessageTimestamps[connectionTopicId];\n      if (timestampNanos > currentTimestamp) {\n        this.connectionMessageTimestamps[connectionTopicId] = timestampNanos;\n      }\n    }\n  }\n\n  /**\n   * Helper method to find a connection's index by its topic ID.\n   * Returns -1 if not found.\n   */\n  private findConnectionIndex(connectionTopicId: string): number {\n    return this.activeConnections.findIndex(\n      (conn) => conn.connectionTopicId === connectionTopicId\n    );\n  }\n\n  /**\n   * Helper method to initialize timestamp tracking for a connection\n   * if it doesn't already exist.\n   */\n  private initializeTimestampIfNeeded(connectionTopicId: string): void {\n    if (!(connectionTopicId in this.connectionMessageTimestamps)) {\n      this.connectionMessageTimestamps[connectionTopicId] =\n        Date.now() * 1_000_000;\n    }\n  }\n\n  addConnectionRequest(request: ConnectionRequestInfo): void {\n    this.connectionRequests.set(request.id, { ...request });\n  }\n\n  listConnectionRequests(): ConnectionRequestInfo[] {\n    return Array.from(this.connectionRequests.values());\n  }\n\n  getConnectionRequestById(\n    requestId: number\n  ): ConnectionRequestInfo | undefined {\n    return this.connectionRequests.get(requestId);\n  }\n\n  removeConnectionRequest(requestId: number): void {\n    this.connectionRequests.delete(requestId);\n  }\n\n  clearConnectionRequests(): void {\n    this.connectionRequests.clear();\n  }\n\n  /**\n   * Persists agent data to environment variables\n   * @param agent - The agent data to persist\n   * @param options - Environment file persistence options\n   */\n  async persistAgentData(\n    agent: RegisteredAgent,\n    options?: AgentPersistenceOptions\n  ): Promise<void> {\n    if (options?.type && options.type !== 'env-file') {\n      throw new Error(\n        `Unsupported persistence type: ${options.type}. Only 'env-file' is supported.`\n      );\n    }\n\n    const envFilePath =\n      (options as EnvFilePersistenceOptions)?.envFilePath ||\n      this.defaultEnvFilePath ||\n      process.env.ENV_FILE_PATH ||\n      '.env';\n\n    if (!envFilePath) {\n      throw new Error(\n        'Environment file path could not be determined for agent data persistence'\n      );\n    }\n\n    const prefix =\n      (options as EnvFilePersistenceOptions)?.prefix || this.defaultPrefix;\n\n    if (!agent.accountId || !agent.inboundTopicId || !agent.outboundTopicId) {\n      throw new Error('Agent data incomplete, cannot persist to environment');\n    }\n\n    const updates: Record<string, string> = {\n      [`${prefix}_ACCOUNT_ID`]: agent.accountId,\n      [`${prefix}_INBOUND_TOPIC_ID`]: agent.inboundTopicId,\n      [`${prefix}_OUTBOUND_TOPIC_ID`]: agent.outboundTopicId,\n    };\n\n    if (agent.privateKey) {\n      updates[`${prefix}_PRIVATE_KEY`] = agent.privateKey;\n    }\n\n    if (agent.profileTopicId) {\n      updates[`${prefix}_PROFILE_TOPIC_ID`] = agent.profileTopicId;\n    }\n\n    await updateEnvFile(envFilePath, updates);\n  }\n}\n"],"names":["OpenConvaiState","options","agent","connection","index","identifier","numericIndex","conn","connectionTopicId","timestampNanos","currentTimestamp","request","requestId","envFilePath","prefix","updates","updateEnvFile"],"mappings":"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"}

package/dist/state/state-types.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Basic registered agent information
+ */
+export interface RegisteredAgent {
+    name: string;
+    accountId: string;
+    inboundTopicId: string;
+    outboundTopicId: string;
+    profileTopicId?: string;
+    privateKey?: string;
+}
+/**
+ * Connection status types
+ */
+export type ConnectionStatus = 'established' | 'pending' | 'needs confirmation' | 'unknown';
+/**
+ * Basic agent profile information
+ */
+export interface AgentProfileInfo {
+    name?: string;
+    bio?: string;
+    avatar?: string;
+    type?: string;
+}
+/**
+ * Information about a connection request
+ */
+export interface ConnectionRequestInfo {
+    id: number;
+    requestorId: string;
+    requestorName: string;
+    timestamp: Date;
+    memo?: string;
+    profile?: AgentProfileInfo;
+}
+/**
+ * Information about an active connection
+ */
+export interface ActiveConnection {
+    targetAccountId: string;
+    targetAgentName: string;
+    targetInboundTopicId: string;
+    connectionTopicId: string;
+    status?: ConnectionStatus;
+    created?: Date;
+    lastActivity?: Date;
+    isPending?: boolean;
+    needsConfirmation?: boolean;
+    profileInfo?: AgentProfileInfo;
+}
+/**
+ * Options for environment variable persistence
+ */
+export interface EnvPersistenceOptions {
+    prefix?: string;
+    envFilePath?: string;
+}
+/**
+ * Base persistence options interface
+ */
+export interface PersistenceOptions {
+    type: string;
+}
+/**
+ * Environment file persistence options
+ */
+export interface EnvFilePersistenceOptions extends PersistenceOptions {
+    type: 'env-file';
+    prefix?: string;
+    envFilePath?: string;
+}
+/**
+ * Persistence options union type
+ */
+export type AgentPersistenceOptions = EnvFilePersistenceOptions;
+/**
+ * Core state management interface for the standards agent toolkit.
+ * All tools that need to maintain state should use an implementation of this interface.
+ */
+export interface IStateManager {
+    /**
+     * Sets the current active agent, clearing any previous connections.
+     */
+    setCurrentAgent(agent: RegisteredAgent | null): void;
+    /**
+     * Gets the current active agent.
+     */
+    getCurrentAgent(): RegisteredAgent | null;
+    /**
+     * Adds a new active connection to the state.
+     * Will not add duplicates based on connectionTopicId.
+     */
+    addActiveConnection(connection: ActiveConnection): void;
+    /**
+     * Updates an existing connection or adds it if not found.
+     * Preserves existing properties when updating.
+     */
+    updateOrAddConnection(connection: ActiveConnection): void;
+    /**
+     * Lists all active connections for the current agent.
+     */
+    listConnections(): ActiveConnection[];
+    /**
+     * Finds a connection by identifier, which can be:
+     * - A 1-based index number as shown in the connection list
+     * - A target account ID
+     * - A connection topic ID
+     */
+    getConnectionByIdentifier(identifier: string): ActiveConnection | undefined;
+    /**
+     * Gets the last processed message timestamp for a connection.
+     */
+    getLastTimestamp(connectionTopicId: string): number;
+    /**
+     * Updates the last processed message timestamp for a connection.
+     */
+    updateTimestamp(connectionTopicId: string, timestampNanos: number): void;
+    /**
+     * Stores a connection request in the state.
+     */
+    addConnectionRequest(request: ConnectionRequestInfo): void;
+    /**
+     * Lists all pending connection requests.
+     */
+    listConnectionRequests(): ConnectionRequestInfo[];
+    /**
+     * Finds a connection request by its ID.
+     */
+    getConnectionRequestById(requestId: number): ConnectionRequestInfo | undefined;
+    /**
+     * Removes a connection request from the state.
+     */
+    removeConnectionRequest(requestId: number): void;
+    /**
+     * Clears all connection requests from the state.
+     */
+    clearConnectionRequests(): void;
+    /**
+     * Persists agent data to storage
+     * Implementation may vary depending on the state manager
+     */
+    persistAgentData?(agent: RegisteredAgent, options?: AgentPersistenceOptions): Promise<void>;
+}

package/dist/tools/AcceptConnectionRequestTool.d.ts

@@ -0,0 +1,33 @@
+import { StructuredTool, ToolParams } from '@langchain/core/tools';
+import { z } from 'zod';
+import { HCS10Client } from '../hcs10/HCS10Client';
+import { IStateManager } from '../state/state-types';
+export interface AcceptConnectionRequestToolParams extends ToolParams {
+    hcsClient: HCS10Client;
+    stateManager: IStateManager;
+}
+/**
+ * A tool specifically for accepting incoming connection requests.
+ */
+export declare class AcceptConnectionRequestTool extends StructuredTool {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        requestId: z.ZodNumber;
+        hbarFee: z.ZodOptional<z.ZodNumber>;
+        exemptAccountIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        requestId: number;
+        hbarFee?: number | undefined;
+        exemptAccountIds?: string[] | undefined;
+    }, {
+        requestId: number;
+        hbarFee?: number | undefined;
+        exemptAccountIds?: string[] | undefined;
+    }>;
+    private hcsClient;
+    private stateManager;
+    private logger;
+    constructor({ hcsClient, stateManager, ...rest }: AcceptConnectionRequestToolParams);
+    protected _call({ requestId, hbarFee, exemptAccountIds, }: z.infer<this['schema']>): Promise<string>;
+}

package/dist/tools/AcceptConnectionRequestTool.js

@@ -0,0 +1,116 @@
+import { StructuredTool as p } from "../node_modules/@langchain/core/dist/tools.js";
+import { z as s } from "zod";
+import { Logger as m, FeeConfigBuilder as q } from "@hashgraphonline/standards-sdk";
+import { ManageConnectionRequestsTool as C } from "./ManageConnectionRequestsTool.js";
+class y extends p {
+  constructor({
+    hcsClient: e,
+    stateManager: o,
+    ...a
+  }) {
+    super(a), this.name = "accept_connection_request", this.description = "Accepts a specific pending connection request from another agent, establishing a communication channel.", this.schema = s.object({
+      requestId: s.number().describe(
+        'The ID of the specific request to accept. Use the "manage_connection_requests" tool with action="list" first to get valid IDs.'
+      ),
+      hbarFee: s.number().optional().describe(
+        "Optional HBAR fee amount to charge the connecting agent per message on the new connection topic."
+      ),
+      exemptAccountIds: s.array(s.string()).optional().describe(
+        "Optional list of account IDs to exempt from any configured fees on the new connection topic."
+      )
+    }), this.hcsClient = e, this.stateManager = o, this.logger = m.getInstance({
+      module: "AcceptConnectionRequestTool"
+    });
+  }
+  async _call({
+    requestId: e,
+    hbarFee: o,
+    exemptAccountIds: a
+  }) {
+    var u;
+    if (!this.stateManager.getCurrentAgent())
+      return "Error: Cannot accept connection request. No agent is currently active. Please register or select an agent first.";
+    await new C({
+      hcsClient: this.hcsClient,
+      stateManager: this.stateManager
+    }).refreshRequests();
+    const t = this.stateManager.getConnectionRequestById(e);
+    if (!t)
+      return `Error: Request ID ${e} not found or no longer pending. Use the manage_connection_requests tool with action="list" to verify.`;
+    try {
+      const r = await this.hcsClient.getInboundTopicId();
+      let c;
+      if (o && o > 0) {
+        const n = this.hcsClient.getAccountAndSigner().accountId;
+        try {
+          c = new q({
+            network: this.hcsClient.getNetwork(),
+            logger: this.logger,
+            defaultCollectorAccountId: n
+          });
+          const l = [
+            ...a || [],
+            t.requestorId
+          ];
+          c.addHbarFee(o, n, l), this.logger.info(
+            `Setting HBAR fee: ${o} HBAR to be collected by ${n}`
+          );
+        } catch (l) {
+          this.logger.error(
+            `Error creating fee configuration: ${l}`
+          ), c = void 0, this.logger.warn(
+            "Proceeding to accept request without fees due to configuration error."
+          );
+        }
+      }
+      this.logger.info(
+        `Attempting to accept request ID: ${e} from ${t.requestorId}`
+      );
+      const i = await this.hcsClient.handleConnectionRequest(
+        r,
+        t.requestorId,
+        e,
+        c
+      );
+      if (!(i != null && i.connectionTopicId))
+        return `Error: Failed to accept connection request #${e}. The SDK did not return a connection topic ID.`;
+      this.logger.info(
+        `Successfully created connection topic: ${i.connectionTopicId}`
+      );
+      const f = i.connectionTopicId;
+      let g = "";
+      try {
+        const n = await this.hcsClient.getAgentProfile(
+          t.requestorId
+        );
+        g = ((u = n == null ? void 0 : n.topicInfo) == null ? void 0 : u.inboundTopic) || "", g || this.logger.warn(
+          `Could not resolve target inbound topic for ${t.requestorId}`
+        );
+      } catch (n) {
+        this.logger.warn(
+          `Error fetching target profile/topic for ${t.requestorId}: ${n}`
+        );
+      }
+      const h = {
+        targetAccountId: t.requestorId,
+        targetAgentName: t.requestorName,
+        targetInboundTopicId: g,
+        connectionTopicId: f,
+        profileInfo: t.profile,
+        created: /* @__PURE__ */ new Date(),
+        status: "established"
+      };
+      this.stateManager.addActiveConnection(h), this.stateManager.removeConnectionRequest(e), this.logger.info(`Removed request ${e} from pending requests`);
+      let d = "";
+      return o && o > 0 && c && (d = ` with a ${o} HBAR fee per message`), `Successfully accepted connection request #${e} from ${t.requestorName}${d}. Connection established on topic: ${f}.`;
+    } catch (r) {
+      return this.logger.error(
+        `Error accepting connection request #${e}: ${r}`
+      ), `Error accepting connection request #${e}: ${r instanceof Error ? r.message : String(r)}`;
+    }
+  }
+}
+export {
+  y as AcceptConnectionRequestTool
+};
+//# sourceMappingURL=AcceptConnectionRequestTool.js.map

package/dist/tools/AcceptConnectionRequestTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AcceptConnectionRequestTool.js","sources":["../../src/tools/AcceptConnectionRequestTool.ts"],"sourcesContent":["import { StructuredTool, ToolParams } from '@langchain/core/tools';\nimport { z } from 'zod';\nimport { HCS10Client } from '../hcs10/HCS10Client';\nimport { IStateManager, ActiveConnection } from '../state/state-types';\nimport { Logger, FeeConfigBuilder } from '@hashgraphonline/standards-sdk';\nimport { ManageConnectionRequestsTool } from './ManageConnectionRequestsTool';\n\nexport interface AcceptConnectionRequestToolParams extends ToolParams {\n  hcsClient: HCS10Client;\n  stateManager: IStateManager;\n}\n\n/**\n * A tool specifically for accepting incoming connection requests.\n */\nexport class AcceptConnectionRequestTool extends StructuredTool {\n  name = 'accept_connection_request';\n  description =\n    'Accepts a specific pending connection request from another agent, establishing a communication channel.';\n  schema = z.object({\n    requestId: z\n      .number()\n      .describe(\n        'The ID of the specific request to accept. Use the \"manage_connection_requests\" tool with action=\"list\" first to get valid IDs.'\n      ),\n    hbarFee: z\n      .number()\n      .optional()\n      .describe(\n        'Optional HBAR fee amount to charge the connecting agent per message on the new connection topic.'\n      ),\n    exemptAccountIds: z\n      .array(z.string())\n      .optional()\n      .describe(\n        'Optional list of account IDs to exempt from any configured fees on the new connection topic.'\n      ),\n  });\n\n  private hcsClient: HCS10Client;\n  private stateManager: IStateManager;\n  private logger: Logger;\n\n  constructor({\n    hcsClient,\n    stateManager,\n    ...rest\n  }: AcceptConnectionRequestToolParams) {\n    super(rest);\n    this.hcsClient = hcsClient;\n    this.stateManager = stateManager;\n    this.logger = Logger.getInstance({\n      module: 'AcceptConnectionRequestTool',\n    });\n  }\n\n  protected async _call({\n    requestId,\n    hbarFee,\n    exemptAccountIds,\n  }: z.infer<this['schema']>): Promise<string> {\n    const currentAgent = this.stateManager.getCurrentAgent();\n    if (!currentAgent) {\n      return 'Error: Cannot accept connection request. No agent is currently active. Please register or select an agent first.';\n    }\n\n    const manageConnectionRequestsTool = new ManageConnectionRequestsTool({\n      hcsClient: this.hcsClient,\n      stateManager: this.stateManager,\n    });\n\n    await manageConnectionRequestsTool.refreshRequests();\n\n    const request = this.stateManager.getConnectionRequestById(requestId);\n    if (!request) {\n      return `Error: Request ID ${requestId} not found or no longer pending. Use the manage_connection_requests tool with action=\"list\" to verify.`;\n    }\n\n    try {\n      const inboundTopicId = await this.hcsClient.getInboundTopicId();\n      let feeConfigBuilder = undefined;\n\n      if (hbarFee && hbarFee > 0) {\n        const collectorId = this.hcsClient.getAccountAndSigner().accountId;\n        try {\n          feeConfigBuilder = new FeeConfigBuilder({\n            network: this.hcsClient.getNetwork(),\n            logger: this.logger,\n            defaultCollectorAccountId: collectorId,\n          });\n\n          const finalExemptions = [\n            ...(exemptAccountIds || []),\n            request.requestorId,\n          ];\n          feeConfigBuilder.addHbarFee(hbarFee, collectorId, finalExemptions);\n          this.logger.info(\n            `Setting HBAR fee: ${hbarFee} HBAR to be collected by ${collectorId}`\n          );\n        } catch (feeConfigError) {\n          this.logger.error(\n            `Error creating fee configuration: ${feeConfigError}`\n          );\n\n          feeConfigBuilder = undefined;\n          this.logger.warn(\n            'Proceeding to accept request without fees due to configuration error.'\n          );\n        }\n      }\n\n      this.logger.info(\n        `Attempting to accept request ID: ${requestId} from ${request.requestorId}`\n      );\n      const result = await this.hcsClient.handleConnectionRequest(\n        inboundTopicId,\n        request.requestorId,\n        requestId,\n        feeConfigBuilder\n      );\n\n      if (!result?.connectionTopicId) {\n        return `Error: Failed to accept connection request #${requestId}. The SDK did not return a connection topic ID.`;\n      }\n      this.logger.info(\n        `Successfully created connection topic: ${result.connectionTopicId}`\n      );\n\n      const connectionTopicId = result.connectionTopicId;\n\n      let targetInboundTopic = '';\n      try {\n        const targetProfileData = await this.hcsClient.getAgentProfile(\n          request.requestorId\n        );\n        targetInboundTopic =\n          targetProfileData?.['topicInfo']?.['inboundTopic'] || '';\n        if (!targetInboundTopic) {\n          this.logger.warn(\n            `Could not resolve target inbound topic for ${request.requestorId}`\n          );\n        }\n      } catch (e) {\n        this.logger.warn(\n          `Error fetching target profile/topic for ${request.requestorId}: ${e}`\n        );\n      }\n\n      const newConnection: ActiveConnection = {\n        targetAccountId: request.requestorId,\n        targetAgentName: request.requestorName,\n        targetInboundTopicId: targetInboundTopic,\n        connectionTopicId,\n        profileInfo: request.profile,\n        created: new Date(),\n        status: 'established',\n      };\n\n      this.stateManager.addActiveConnection(newConnection);\n      this.stateManager.removeConnectionRequest(requestId);\n      this.logger.info(`Removed request ${requestId} from pending requests`);\n\n      let feeMessage = '';\n      if (hbarFee && hbarFee > 0 && feeConfigBuilder) {\n        feeMessage = ` with a ${hbarFee} HBAR fee per message`;\n      }\n\n      return `Successfully accepted connection request #${requestId} from ${request.requestorName}${feeMessage}. Connection established on topic: ${connectionTopicId}.`;\n    } catch (error) {\n      this.logger.error(\n        `Error accepting connection request #${requestId}: ${error}`\n      );\n\n      return `Error accepting connection request #${requestId}: ${\n        error instanceof Error ? error.message : String(error)\n      }`;\n    }\n  }\n}\n"],"names":["AcceptConnectionRequestTool","StructuredTool","hcsClient","stateManager","rest","z","Logger","requestId","hbarFee","exemptAccountIds","ManageConnectionRequestsTool","request","inboundTopicId","feeConfigBuilder","collectorId","FeeConfigBuilder","finalExemptions","feeConfigError","result","connectionTopicId","targetInboundTopic","targetProfileData","_a","e","newConnection","feeMessage","error"],"mappings":"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"}

package/dist/tools/CheckMessagesTool.d.ts

@@ -0,0 +1,34 @@
+import { StructuredTool, ToolParams } from '@langchain/core/tools';
+import { z } from 'zod';
+import { HCS10Client } from '../hcs10/HCS10Client';
+import { IStateManager } from '../state/state-types';
+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 declare class CheckMessagesTool extends StructuredTool {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        targetIdentifier: z.ZodString;
+        fetchLatest: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        lastMessagesCount: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        targetIdentifier: string;
+        fetchLatest: boolean;
+        lastMessagesCount?: number | undefined;
+    }, {
+        targetIdentifier: string;
+        fetchLatest?: boolean | undefined;
+        lastMessagesCount?: number | undefined;
+    }>;
+    hcsClient: HCS10Client;
+    private stateManager;
+    private logger;
+    constructor({ hcsClient, stateManager, ...rest }: CheckMessagesToolParams);
+    protected _call({ targetIdentifier, fetchLatest, lastMessagesCount, }: z.infer<this['schema']>): Promise<string>;
+}