@hashgraphonline/conversational-agent 0.2.215 → 0.2.217

package/src/plugins/community/swarm/tools/QueryUploadProgressTool.ts

@@ -0,0 +1,109 @@
+import {
+  type GenericPluginContext,
+  BaseHederaQueryTool,
+  type HederaAgentKit,
+} from "hedera-agent-kit";
+import { Bee } from "@ethersphere/bee-js";
+import { z } from "zod";
+import {
+  errorHasStatus,
+  getResponseWithStructuredContent,
+  ToolResponse,
+} from "../utils";
+import { GATEWAY_TAG_ERROR_MESSAGE } from "../constants";
+import { SwarmConfig } from "../config";
+
+const QueryUploadProgressSchema = z.object({
+  tagId: z.string(),
+});
+
+export class QueryUploadProgressTool extends BaseHederaQueryTool<typeof QueryUploadProgressSchema> {
+  name = "swarm-query-upload-progress";
+  description = `Query upload progress for a specific upload session identified with the returned Tag ID.
+    tagId: Tag ID returned by swarm-upload-file and swarm-upload-folder tools to track upload progress.
+  `;
+  namespace = "swarm";
+  specificInputSchema = QueryUploadProgressSchema;
+  bee: Bee;
+  config: SwarmConfig;
+    
+  constructor(params: {
+    hederaKit: HederaAgentKit;
+    config: SwarmConfig;
+    logger?: GenericPluginContext['logger'];
+    bee: Bee;
+  }) {
+    const { bee, config, ...rest } = params;
+    super(rest);
+    this.bee = bee;
+    this.config = config;
+  }
+
+  protected async executeQuery(
+      input: z.infer<typeof QueryUploadProgressSchema>
+  ): Promise<ToolResponse | string> {
+    if (!input?.tagId) {
+      this.logger.error(
+        'Missing required parameter: tagId.'
+      );
+
+      throw new Error('Missing required parameter: tagId.');
+    }
+
+    const tagUid = Number.parseInt(input.tagId, 10);
+    if (Number.isNaN(tagUid)) {
+      this.logger.error(
+        'Invalid tagId format. Expected a numeric string.'
+      );
+
+      throw new Error('Invalid tagId format. Expected a numeric string.');
+    }
+
+    try {
+      const tag = await this.bee.retrieveTag(tagUid);
+
+      const synced = tag.synced ?? 0;
+      const seen = tag.seen ?? 0;
+      const processed = synced + seen;
+      const total = tag.split ?? 0;
+      const startedAt = tag.startedAt;
+
+      const processedPercentage =
+        total > 0 ? Math.round((processed / total) * 100) : 0;
+      const isComplete = processedPercentage === 100;
+
+      let tagDeleted = false;
+      if (isComplete) {
+        try {
+          await this.bee.deleteTag(tagUid);
+          tagDeleted = true;
+        } catch {
+          // Non-fatal: if deletion fails we still return progress
+        }
+      }
+
+      return getResponseWithStructuredContent({
+        processedPercentage,
+        message: isComplete
+          ? "Upload completed successfully."
+          : `Upload progress: ${processedPercentage}% processed`,
+        startedAt,
+        tagAddress: tag.address,
+      });
+    } catch (error: any) {
+      let errorMessage = `Failed to retrieve upload progress: ${error?.message ?? "Unknown error"}`;
+      
+      const status = error?.status ?? error?.response?.status;
+      if (status === 404) {
+        errorMessage = `Tag with ID ${input.tagId} does not exist or has been deleted. ` + GATEWAY_TAG_ERROR_MESSAGE;
+      }
+      
+      this.logger.error(
+        errorMessage,
+        error
+      );
+      
+      throw new Error(errorMessage);
+    }
+  }
+}

package/src/plugins/community/swarm/tools/ReadFeedTool.ts

@@ -0,0 +1,110 @@
+import { Bee } from "@ethersphere/bee-js";
+import { Wallet } from "@ethereumjs/wallet";
+import { z } from "zod";
+import crypto from "crypto";
+import { errorHasStatus, getErrorMessage, getResponseWithStructuredContent, hexToBytes, ToolResponse } from "../utils";
+import { BaseHederaQueryTool, GenericPluginContext, HederaAgentKit } from "hedera-agent-kit";
+import { SwarmConfig } from "../config";
+import { BAD_REQUEST_STATUS } from "../constants";
+
+const ReadFeedSchema = z.object({
+  memoryTopic: z.string(),
+  owner: z.string().optional()
+});
+
+export class ReadFeedTool extends BaseHederaQueryTool<typeof ReadFeedSchema> {
+  name = "swarm-read-feed";
+  description = `Retrieve the latest data from the feed of a given topic.
+    memoryTopic: Feed topic.
+    owner: When accessing external memory or feed, ethereum address of the owner must be set.
+  `;
+  namespace = "swarm";
+  specificInputSchema = ReadFeedSchema;
+  bee: Bee;
+  config: SwarmConfig;
+      
+  constructor(params: {
+    hederaKit: HederaAgentKit;
+    config: SwarmConfig;
+    logger?: GenericPluginContext['logger'];
+    bee: Bee;
+  }) {
+    const { bee, config, ...rest } = params;
+    super(rest);
+    this.bee = bee;
+    this.config = config;
+  }
+
+  protected async executeQuery(
+      input: z.infer<typeof ReadFeedSchema>
+  ): Promise<ToolResponse | string> {
+   const { memoryTopic, owner } = input;
+
+    if (!memoryTopic) {
+      this.logger.error(
+        'Missing required parameter: memoryTopic.'
+      );
+
+      throw new Error('Missing required parameter: memoryTopic.');
+    }
+
+    this.logger.info(`[API] Downloading text from Swarm feed with topic: ${memoryTopic}.`);
+
+    if (!this.config.beeFeedPK) {
+      this.logger.error('Feed private key not configured.');
+
+      throw new Error('Feed private key not configured.');
+    }
+
+    // Process topic - if not a hex string, hash it
+    let topic = memoryTopic;
+    if (topic.startsWith("0x")) {
+      topic = topic.slice(2);
+    }
+    const isHexString = /^[0-9a-fA-F]{64}$/.test(topic);
+
+    if (!isHexString) {
+      // Hash the topic string using SHA-256
+      const hash = crypto.createHash("sha256").update(memoryTopic).digest("hex");
+      topic = hash;
+    }
+
+    // Convert topic string to bytes
+    const topicBytes = hexToBytes(topic);
+
+    let feedOwner = owner;
+    if (!feedOwner) {
+      const feedPrivateKey = hexToBytes(this.config.beeFeedPK);
+      const signer = new Wallet(feedPrivateKey);
+      feedOwner = signer.getAddressString().slice(2);
+    } else {
+      if (feedOwner.startsWith("0x")) {
+        feedOwner = feedOwner.slice(2);
+      }
+      if (feedOwner.length !== 40) {
+        this.logger.error('Owner must be a valid Ethereum address.');
+
+        throw new Error('Owner must be a valid Ethereum address.');
+      }
+    }
+
+    let textData;
+    
+    try {
+      const feedReader = this.bee.makeFeedReader(topicBytes, feedOwner);
+      const latestUpdate = await feedReader.downloadPayload();
+      textData = latestUpdate.payload.toUtf8();
+    } catch (error) {
+      let errorMessage = 'Reading feed failed.';
+      if (errorHasStatus(error, BAD_REQUEST_STATUS)) {
+        errorMessage = getErrorMessage(error);
+      }
+      this.logger.error(errorMessage, error);
+      throw new Error(errorMessage);
+    }
+    
+    return getResponseWithStructuredContent({
+      textData,
+    });
+  }
+}

package/src/plugins/community/swarm/tools/UpdateFeedTool.ts

@@ -0,0 +1,149 @@
+import {
+  BaseHederaQueryTool,
+  HederaAgentKit,
+  type GenericPluginContext,
+} from "hedera-agent-kit";
+import { Bee } from "@ethersphere/bee-js";
+import { z } from "zod";
+import crypto from "crypto";
+import {
+  errorHasStatus,
+  getErrorMessage,
+  getResponseWithStructuredContent,
+  getUploadPostageBatchId,
+  hexToBytes,
+  ToolResponse,
+} from "../utils";
+import { BAD_REQUEST_STATUS } from "../constants";
+import { Wallet } from "@ethereumjs/wallet";
+import { SwarmConfig } from "../config";
+
+const UpdateFeedSchema = z.object({
+  data: z.string(),
+  memoryTopic: z.string(),
+  postageBatchId: z.string().optional(),
+});
+
+export class UpdateFeedTool extends BaseHederaQueryTool<typeof UpdateFeedSchema> {
+  name = "swarm-update-feed";
+  description = `Update the feed of a given topic with new data.
+    data: Arbitrary string to upload.
+    memoryTopic: If provided, uploads the data to a feed with this topic. It is the label of the memory that can be used later to retrieve the data instead of its content hash. If not a hex string, it will be hashed to create a feed topic.
+    postageBatchId: The postage stamp batch ID which will be used to perform the upload, if it is provided.`;
+  namespace = "swarm";
+  specificInputSchema = UpdateFeedSchema;
+  bee: Bee;
+  config: SwarmConfig;
+        
+  constructor(params: {
+    hederaKit: HederaAgentKit;
+    config: SwarmConfig;
+    logger?: GenericPluginContext['logger'];
+    bee: Bee;
+  }) {
+    const { bee, config, ...rest } = params;
+    super(rest);
+    this.bee = bee;
+    this.config = config;
+  }
+  
+  protected async executeQuery(
+      input: z.infer<typeof UpdateFeedSchema>
+  ): Promise<ToolResponse | string> {
+    const { data, memoryTopic, postageBatchId: inputPostageBatchId  } = input;
+     if (!data) {
+      this.logger.error(
+        'Missing required parameter: data.'
+      );
+
+      throw new Error('Missing required parameter: data.');
+    } else if (!memoryTopic) {
+      this.logger.error(
+        'Missing required parameter: topic.'
+      );
+
+      throw new Error('Missing required parameter: topic.');
+    }
+    
+    let postageBatchId = "";
+
+    try {
+      postageBatchId = await getUploadPostageBatchId(
+        inputPostageBatchId,
+        this.bee,
+        this.config,
+      );
+    } catch (error) {
+      let errorMessage = 'Update feed failed.';
+      if (error instanceof Error) {
+        errorMessage = error.message;
+      }
+      this.logger.error(errorMessage);
+
+      throw new Error(errorMessage);
+    }
+
+    const binaryData = Buffer.from(data);
+
+    // Feed upload if memoryTopic is specified
+    if (!this.config.beeFeedPK) {
+      this.logger.error('Feed private key not configured.');
+
+      throw new Error('Feed private key not configured.');
+    }
+
+    // Process topic - if not a hex string, hash it
+    let topic = memoryTopic;
+    if (topic.startsWith("0x")) {
+      topic = topic.slice(2);
+    }
+    const isHexString = /^[0-9a-fA-F]{64}$/.test(memoryTopic);
+
+    if (!isHexString) {
+      // Hash the topic string using SHA-256
+      const hash = crypto
+        .createHash("sha256")
+        .update(memoryTopic)
+        .digest("hex");
+      topic = hash;
+    }
+
+    // Convert topic string to bytes
+    const topicBytes = hexToBytes(topic);
+
+    const feedPrivateKey = hexToBytes(this.config.beeFeedPK);
+    const signer = new Wallet(feedPrivateKey);
+    const owner = signer.getAddressString().slice(2);
+
+    let result;
+
+    try {
+      const feedWriter = this.bee.makeFeedWriter(topicBytes, feedPrivateKey);
+
+      result = await feedWriter.uploadPayload(postageBatchId!, binaryData);
+    } catch (error) {
+      let errorMessage = 'Unable to update feed.';
+
+      if (errorHasStatus(error, BAD_REQUEST_STATUS)) {
+        errorMessage = getErrorMessage(error);
+      }
+
+      this.logger.error(
+        errorMessage,
+        error
+      );
+      
+      throw new Error(errorMessage);
+    }
+
+    const reference = result.reference.toString();
+
+    return getResponseWithStructuredContent({
+      reference,
+      topicString: memoryTopic,
+      topic: topic,
+      feedUrl: `${this.bee.url}/feeds/${owner}/${topic}`,
+      message: 'Data successfully uploaded to Swarm and linked to feed.',
+    });
+  }
+}

package/src/plugins/community/swarm/tools/UploadDataTool.ts

@@ -0,0 +1,109 @@
+import {
+  BaseHederaQueryTool,
+  HederaAgentKit,
+  type GenericPluginContext,
+} from "hedera-agent-kit";
+import { Bee } from "@ethersphere/bee-js";
+import { z } from "zod";
+import {
+  errorHasStatus,
+  getErrorMessage,
+  getResponseWithStructuredContent,
+  getUploadPostageBatchId,
+  ToolResponse,
+} from "../utils";
+import { BAD_REQUEST_STATUS } from "../constants";
+import { SwarmConfig } from "../config";
+
+const UploadDataSchema = z.object({
+  data: z.string(),
+  redundancyLevel: z.number().optional(),
+  postageBatchId: z.string().optional(),
+});
+
+export class UploadDataTool extends BaseHederaQueryTool<typeof UploadDataSchema> {
+  name = "swarm-upload-data";
+  description = `
+    Upload text data to Swarm.
+    data: Arbitrary string to upload.
+    redundancyLevel: Redundancy level for fault tolerance: 0 - none, 1 - medium, 2 - strong, 3 - insane, 4 - paranoid (higher values provide better fault tolerance but increase storage overhead). Optional, value is 0 if not requested.
+    postageBatchId: The postage stamp batch ID which will be used to perform the upload, if it is provided.
+  `;
+  namespace = "swarm";
+  specificInputSchema = UploadDataSchema;
+  bee: Bee;
+  config: SwarmConfig;
+          
+  constructor(params: {
+    hederaKit: HederaAgentKit;
+    config: SwarmConfig;
+    logger?: GenericPluginContext['logger'];
+    bee: Bee;
+  }) {
+    const { bee, config, ...rest } = params;
+    super(rest);
+    this.bee = bee;
+    this.config = config;
+  }
+  
+  protected async executeQuery(
+      input: z.infer<typeof UploadDataSchema>
+  ): Promise<ToolResponse | string> {
+    const { data, redundancyLevel, postageBatchId: inputPostageBatchId } = input;
+
+    if (!data) {
+      this.logger.error(
+        'Missing required parameter: data.'
+      );
+
+      throw new Error('Missing required parameter: data.');
+    }
+
+    let postageBatchId = "";
+
+    try {
+      postageBatchId = await getUploadPostageBatchId(
+        inputPostageBatchId,
+        this.bee,
+        this.config,
+      );
+    } catch (error) {
+      let errorMessage = 'Upload data failed.';
+      if (error instanceof Error) {
+        errorMessage = error.message;
+      }
+      this.logger.error(errorMessage);
+
+      throw new Error(errorMessage);
+    }
+
+    const binaryData = Buffer.from(data);
+
+    const options = redundancyLevel ? { redundancyLevel } : undefined;
+
+    let result;
+
+    try {
+      result = await this.bee.uploadData(postageBatchId, binaryData, options);
+    } catch (error) {
+      let errorMessage = 'Unable to upload data.';
+
+      if (errorHasStatus(error, BAD_REQUEST_STATUS)) {
+        errorMessage = getErrorMessage(error);
+      }
+
+      this.logger.error(
+        errorMessage,
+        error
+      );
+      
+      throw new Error(errorMessage);
+    }
+
+    return getResponseWithStructuredContent({
+        reference: result.reference.toString(),
+        url: this.bee.url + "/bytes/" + result.reference.toString(),
+        message: 'Data successfully uploaded to Swarm',
+      });
+  }
+}

package/src/plugins/community/swarm/tools/UploadFileTool.ts

@@ -0,0 +1,163 @@
+import {
+  BaseHederaQueryTool,
+  HederaAgentKit,
+  type GenericPluginContext,
+} from "hedera-agent-kit";
+import { Bee, FileUploadOptions } from "@ethersphere/bee-js";
+import { z } from "zod";
+import { promisify } from "util";
+import fs from "fs";
+import {
+  errorHasStatus,
+  getErrorMessage,
+  getResponseWithStructuredContent,
+  getUploadPostageBatchId,
+  ToolResponse,
+} from "../utils";
+import { BAD_REQUEST_STATUS, DEFAULT_DEFERRED_UPLOAD_SIZE_THRESHOLD_MB, GATEWAY_TAG_ERROR_MESSAGE, NOT_FOUND_STATUS } from "../constants";
+import { SwarmConfig } from "../config";
+
+const UploadFileSchema = z.object({
+  data: z.string(),
+  isPath: z.boolean(),
+  redundancyLevel: z.number().optional(),
+  postageBatchId: z.string().optional(),
+});
+
+export class UploadFileTool extends BaseHederaQueryTool<typeof UploadFileSchema> {
+  name = "swarm-upload-file";
+  description = `Upload a file to Swarm.
+    data: base64 encoded file content or file path.
+    isPath: Wether the data parameter is a path.
+    redundancyLevel: Redundancy level for fault tolerance (higher values provide better fault tolerance but increase storage overhead). 0 - none, 1 - medium, 2 - strong, 3 - insane, 4 - paranoid.
+    postageBatchId: The postage stamp batch ID which will be used to perform the upload, if it is provided.`;
+  namespace = "swarm";
+  specificInputSchema = UploadFileSchema;
+  bee: Bee;
+  config: SwarmConfig;
+
+  constructor(params: {
+    hederaKit: HederaAgentKit;
+    config: SwarmConfig;
+    logger?: GenericPluginContext['logger'];
+    bee: Bee;
+  }) {
+    const { bee, config, ...rest } = params;
+    super(rest);
+    this.bee = bee;
+    this.config = config;
+  }
+  
+  protected async executeQuery(
+      input: z.infer<typeof UploadFileSchema>
+  ): Promise<ToolResponse | string> {
+    const { data, isPath, redundancyLevel: inputRedundancyLevel, postageBatchId: inputPostageBatchId  } = input;
+
+    if (!data) {
+      this.logger.error(
+        'Missing required parameter: data.'
+      );
+
+      throw new Error('Missing required parameter: data.');
+    }
+
+    let postageBatchId = "";
+
+    try {
+      postageBatchId = await getUploadPostageBatchId(
+        inputPostageBatchId,
+        this.bee,
+        this.config,
+      );
+    } catch (error) {
+      let errorMessage = 'Upload file failed.';
+      if (error instanceof Error) {
+        errorMessage = error.message;
+      }
+      this.logger.error(errorMessage);
+
+      throw new Error(errorMessage);
+    }
+
+    let binaryData: Buffer;
+    let name: string | undefined;
+
+    if (isPath) {
+      // Read file from path
+      try {
+        binaryData = await promisify(fs.readFile)(data);
+      } catch (fileError) {
+        this.logger.error(
+          `Unable to read file at path: ${data}.`,
+          fileError
+        );
+
+        throw new Error(`Unable to read file at path: ${data}.`);
+      }
+
+      name = data.split("/").pop();
+    } else {
+      binaryData = Buffer.from(data, "base64");
+    }
+
+    const redundancyLevel = inputRedundancyLevel;
+    const options: FileUploadOptions = {};
+    const deferredUploadSizeThreshold = Number(this.config.deferredUploadSizeThresholdMB) ||
+      DEFAULT_DEFERRED_UPLOAD_SIZE_THRESHOLD_MB;
+    const deferred =
+      binaryData.length > deferredUploadSizeThreshold * 1024 * 1024;
+    options.deferred = deferred;
+    if (redundancyLevel) {
+      options.redundancyLevel = redundancyLevel;
+    }
+
+    let message = "File successfully uploaded to Swarm";
+    let tagId: string | undefined = undefined;
+    // Create tag for deferred uploads or when explicitly requested
+    if (deferred) {
+      try {
+        const tag = await this.bee.createTag();
+        options.tag = tag.uid;
+        tagId = tag.uid.toString();
+        message =
+          "File upload started in deferred mode. Use query_upload_progress to track progress.";
+      } catch (error) {
+        if (errorHasStatus(error, NOT_FOUND_STATUS)) {
+          this.logger.error(
+            GATEWAY_TAG_ERROR_MESSAGE,
+            error
+          );
+
+          throw new Error(GATEWAY_TAG_ERROR_MESSAGE);
+        }
+      }
+    }
+
+    let result;
+
+    try {
+      // Start the deferred upload
+      result = await this.bee.uploadFile(postageBatchId, binaryData, name, options);
+    } catch (error) {
+      let errorMessage = 'Unable to upload file.';
+
+      if (errorHasStatus(error, BAD_REQUEST_STATUS)) {
+        errorMessage = getErrorMessage(error);
+      }
+
+      this.logger.error(
+        errorMessage,
+        error
+      );
+      
+      throw new Error(errorMessage);
+    }
+
+    return getResponseWithStructuredContent({
+      reference: result.reference.toString(),
+      url: this.bee.url + "/bzz/" + result.reference.toString(),
+      message,
+      tagId,
+    });
+  }
+}