@hashgraphonline/conversational-agent 0.2.215 → 0.2.217

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

@@ -0,0 +1,148 @@
+import { describe, it, expect, beforeEach, jest } from '@jest/globals';
+import './SwarmTool.mocks';
+import crypto from 'crypto';
+import { UpdateFeedTool } from '../../tools/UpdateFeedTool';
+import { beeMock, contextMock, mockedUtils, swarmConfigMock } from './SwarmTool.mocks';
+import { getErrorMessage } from '../../utils';
+import { BAD_REQUEST_STATUS } from '../../constants';
+
+describe('UpdateFeedTool', () => {
+  let tool: UpdateFeedTool;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    tool = new UpdateFeedTool({
+      hederaKit: {} as any,
+      config: { ...swarmConfigMock, beeFeedPK: 'a'.repeat(64) },
+      bee: beeMock,
+      logger: contextMock.logger,
+    });
+  });
+
+  it('should throw if data is missing', async () => {
+    await expect(tool['executeQuery']({ memoryTopic: 'topic', data: '' } as any))
+      .rejects.toThrow('Missing required parameter: data.');
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Missing required parameter: data.'
+    );
+  });
+
+  it('should throw if topic is missing', async () => {
+    await expect(tool['executeQuery']({ data: 'some data', memoryTopic: '' } as any))
+      .rejects.toThrow('Missing required parameter: topic.');
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Missing required parameter: topic.'
+    );
+  });
+
+  it('should throw if getUploadPostageBatchId fails', async () => {
+    const error = new Error('Failed to get postage batch');
+    mockedUtils.getUploadPostageBatchId.mockRejectedValue(
+      error
+    );
+
+    await expect(tool['executeQuery']({ data: 'hello', memoryTopic: 'topic' }))
+      .rejects.toThrow('Failed to get postage batch');
+
+    expect(contextMock.logger.error).toHaveBeenCalledWith('Failed to get postage batch');
+  });
+
+  it('should throw if feed private key is not configured', async () => {
+    tool.config.beeFeedPK = '';
+    mockedUtils.getUploadPostageBatchId.mockResolvedValue('batch-id');
+
+    await expect(tool['executeQuery']({ data: 'hi', memoryTopic: 'topic' }))
+      .rejects.toThrow('Feed private key not configured.');
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Feed private key not configured.'
+    );
+  });
+
+  it('should hash non-hex topic and call bee.makeFeedWriter', async () => {
+    const topic = 'nonHexTopic';
+    const hash = crypto.createHash('sha256').update(topic).digest('hex');
+
+    mockedUtils.getUploadPostageBatchId.mockResolvedValue('batch-id');
+
+    const uploadPayloadMock = jest.fn().mockReturnValueOnce({
+      reference: { toString: () => 'ref123' },
+    });
+    const makeFeedWriterMock = jest.fn().mockReturnValue({
+      uploadPayload: uploadPayloadMock,
+    });
+    
+    (beeMock.makeFeedWriter as unknown as jest.Mock).mockImplementation(makeFeedWriterMock);
+    const result = await tool['executeQuery']({ data: 'hi', memoryTopic: topic });
+
+    expect(makeFeedWriterMock).toHaveBeenCalled();
+    expect(result["structuredContent"]).toStrictEqual({
+      reference: 'ref123',
+      topicString: 'nonHexTopic',
+      topic: '186143fbcbf933508c828567e5ebffa2cbfa34d7066b15d42ad1eb8c62a7d5db',
+      feedUrl: 'http://127.0.0.1:1633/feeds/8fd379246834eac74b8419ffda202cf8051f7a03/186143fbcbf933508c828567e5ebffa2cbfa34d7066b15d42ad1eb8c62a7d5db',
+      message: 'Data successfully uploaded to Swarm and linked to feed.'
+    });
+  });
+
+  it('should remove 0x prefix from hex topic and succeed', async () => {
+    const topic = '0x' + 'a'.repeat(64);
+    mockedUtils.getUploadPostageBatchId.mockResolvedValue('batch-id');
+    const uploadPayloadMock = jest.fn().mockReturnValueOnce({
+      reference: { toString: () => 'ref123' },
+    });
+    const makeFeedWriterMock = jest.fn().mockReturnValue({
+      uploadPayload: uploadPayloadMock,
+    });
+    (beeMock.makeFeedWriter as unknown as jest.Mock).mockImplementation(makeFeedWriterMock);
+
+    const result = await tool['executeQuery']({ data: 'hello', memoryTopic: topic });
+
+    expect(makeFeedWriterMock).toHaveBeenCalled();
+    expect(result["structuredContent"]).toStrictEqual({
+      reference: 'ref123',
+        topicString: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+        topic: '8d8b3cc160bb728e13db1c032741ad9566b3affd16fc0c805d3caf863694643e',
+        feedUrl: 'http://127.0.0.1:1633/feeds/8fd379246834eac74b8419ffda202cf8051f7a03/8d8b3cc160bb728e13db1c032741ad9566b3affd16fc0c805d3caf863694643e',
+        message: 'Data successfully uploaded to Swarm and linked to feed.'
+    });
+  });
+
+  it('should handle BAD_REQUEST_STATUS error', async () => {
+    mockedUtils.getUploadPostageBatchId.mockResolvedValue('batch-id');
+    getErrorMessage as jest.MockedFunction<typeof getErrorMessage>;
+    (getErrorMessage as jest.Mock).mockReturnValue('Custom bad request message.');
+    const error = new Error('Custom bad request message.');
+    (error as any).status = BAD_REQUEST_STATUS;
+
+    (beeMock.makeFeedWriter as unknown as jest.Mock).mockImplementation(() => {
+      throw error;
+    });
+    
+    await expect(tool['executeQuery']({ data: 'test', memoryTopic: '0x' + 'a'.repeat(64) }))
+      .rejects.toThrow('Custom bad request message.');
+
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Custom bad request message.',
+      expect.anything()
+    );    
+  });
+
+  it('should handle generic feed upload error', async () => {
+    mockedUtils.getUploadPostageBatchId.mockResolvedValue('batch-id');
+
+    const error = new Error('Unable to update feed.');
+
+    (beeMock.makeFeedWriter as unknown as jest.Mock).mockImplementation(() => {
+      throw error;
+    });
+
+    await expect(
+      tool['executeQuery']({ data: 'abc', memoryTopic: 'topic' })
+    ).rejects.toThrow('Unable to update feed.');
+
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Unable to update feed.',
+      expect.any(Error)
+    );
+  });
+});

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

@@ -0,0 +1,125 @@
+import { describe, expect, it, beforeEach, jest } from '@jest/globals';
+import './SwarmTool.mocks';
+import { UploadDataTool } from '../../tools/UploadDataTool';
+import { beeMock, contextMock, mockedUtils, swarmConfigMock } from './SwarmTool.mocks';
+import { HederaAgentKit } from 'hedera-agent-kit';
+import { Reference, UploadResult } from '@ethersphere/bee-js';
+import { BAD_REQUEST_STATUS } from '../../constants';
+
+describe('UploadDataTool', () => {
+  let tool: UploadDataTool;
+  const hederaKitMock = {} as HederaAgentKit;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+
+    tool = new UploadDataTool({
+      hederaKit: hederaKitMock,
+      config: swarmConfigMock,
+      bee: beeMock,
+      logger: contextMock.logger,
+    });
+
+    // Mock successful postage batch ID fetch
+    mockedUtils.getUploadPostageBatchId.mockResolvedValue('postage123');
+
+    // Mock upload result
+    const reference = { toString: () => 'data123' } as unknown as Reference;
+    const uploadResult = { reference } as unknown as UploadResult;
+    beeMock.uploadData.mockResolvedValue(uploadResult);
+  });
+
+  it('uploads simple data successfully', async () => {
+    const result = await tool['executeQuery']({ data: 'hello swarm' });
+
+    expect(mockedUtils.getUploadPostageBatchId).toHaveBeenCalledWith(
+      undefined,
+      beeMock,
+      swarmConfigMock
+    );
+
+    expect(beeMock.uploadData).toHaveBeenCalledWith(
+      'postage123',
+      expect.any(Buffer),
+      undefined
+    );
+
+    expect(result['structuredContent']).toEqual(
+      expect.objectContaining({
+        reference: 'data123',
+        url: 'http://127.0.0.1:1633/bytes/data123',
+        message: 'Data successfully uploaded to Swarm',
+      })
+    );
+  });
+
+  it('uploads data with redundancy level', async () => {
+    const result = await tool['executeQuery']({
+      data: 'redundant swarm data',
+      redundancyLevel: 3,
+    });
+
+    expect(beeMock.uploadData).toHaveBeenCalledWith(
+      'postage123',
+      expect.any(Buffer),
+      { redundancyLevel: 3 }
+    );
+
+    expect(result['structuredContent'].message).toBe(
+      'Data successfully uploaded to Swarm'
+    );
+  });
+
+  it('throws error if data is missing', async () => {
+    await expect(
+      tool['executeQuery']({ data: '' })
+    ).rejects.toThrow('Missing required parameter: data.');
+
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Missing required parameter: data.'
+    );
+  });
+
+  it('throws error if getUploadPostageBatchId fails', async () => {
+    const error = new Error('Failed to get postage batch');
+    mockedUtils.getUploadPostageBatchId.mockRejectedValue(error);
+
+    await expect(tool['executeQuery']({ data: 'abc' })).rejects.toThrow(
+      'Failed to get postage batch'
+    );
+
+    expect(contextMock.logger.error).toHaveBeenCalledWith('Failed to get postage batch');
+  });
+
+  it('handles uploadData error gracefully', async () => {
+    const error = new Error('Upload failed');
+    beeMock.uploadData.mockRejectedValueOnce(error);
+
+    await expect(tool['executeQuery']({ data: 'abc' })).rejects.toThrow(
+      'Unable to upload data.'
+    );
+
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Unable to upload data.',
+      error
+    );
+  });
+
+  it('handles BAD_REQUEST_STATUS errors using getErrorMessage', async () => {
+    const error = new Error();
+    (error as any).status = BAD_REQUEST_STATUS;
+    beeMock.uploadData.mockRejectedValueOnce(error);
+
+    mockedUtils.getErrorMessage.mockReturnValue('Bad request: malformed data');
+
+    await expect(tool['executeQuery']({ data: 'abc' })).rejects.toThrow(
+      'Bad request: malformed data'
+    );
+
+    expect(mockedUtils.getErrorMessage).toHaveBeenCalledWith(error);
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Bad request: malformed data',
+      error
+    );
+  });
+});

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

@@ -0,0 +1,194 @@
+import { describe, expect, it, beforeEach, jest } from '@jest/globals';
+import './SwarmTool.mocks';
+import { UploadFileTool } from '../../tools/UploadFileTool';
+import { beeMock, contextMock, mockedUtils, swarmConfigMock } from './SwarmTool.mocks';
+import { HederaAgentKit } from 'hedera-agent-kit';
+import { Reference, UploadResult } from '@ethersphere/bee-js';
+import { GATEWAY_TAG_ERROR_MESSAGE } from '../../constants';
+
+describe('UploadFileTool', () => {
+  let tool: UploadFileTool;
+  const hederaKitMock = {} as HederaAgentKit;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+
+    tool = new UploadFileTool({
+      hederaKit: hederaKitMock,
+      config: swarmConfigMock,
+      bee: beeMock,
+      logger: contextMock.logger,
+    });
+
+    // Default mocks
+    mockedUtils.getUploadPostageBatchId.mockResolvedValue('postage123');
+
+    const reference = { toString: () => 'postage123' } as unknown as Reference;
+    const uploadResult = { reference } as unknown as UploadResult;
+    beeMock.uploadFile.mockResolvedValue(uploadResult);
+
+    const tagDataMock = {
+      address: '0x123',
+      synced: 50,
+      seen: 25,
+      split: 100,
+      stored: 10,
+      sent: 10,
+      uid: 123,
+      startedAt: '2025-11-04T12:00:00Z',
+    };
+    beeMock.createTag.mockResolvedValue(tagDataMock);
+  });
+
+  it('uploads base64 data successfully', async () => {
+    const data = Buffer.from('hello world').toString('base64');
+
+    const result = await tool['executeQuery']({
+      data,
+      isPath: false,
+    });
+
+    expect(mockedUtils.getUploadPostageBatchId).toHaveBeenCalledWith(
+      undefined,
+      beeMock,
+      swarmConfigMock
+    );
+
+    expect(beeMock.uploadFile).toHaveBeenCalledWith(
+      'postage123',
+      expect.any(Buffer),
+      undefined,
+      expect.objectContaining({ deferred: false })
+    );
+
+    expect(result['structuredContent']).toEqual(
+      expect.objectContaining({
+        reference: "postage123",
+        url: "http://127.0.0.1:1633/bzz/postage123",
+        message: "File successfully uploaded to Swarm",
+      })
+    );
+  });
+
+  it('uploads file from path successfully', async () => {
+    const readFileMock = jest.fn<any>().mockResolvedValue(Buffer.from('file content'));
+    jest.spyOn(require('util'), 'promisify').mockReturnValue(readFileMock);
+    
+    const result = await tool['executeQuery']({
+      data: '/mock/path/file.txt',
+      isPath: true,
+    });
+
+    expect(readFileMock).toHaveBeenCalledWith('/mock/path/file.txt');
+    expect(beeMock.uploadFile).toHaveBeenCalledWith(
+      'postage123',
+      expect.any(Buffer),
+      'file.txt',
+      expect.objectContaining({ deferred: false })
+    );
+
+    expect(result['structuredContent']).toEqual(
+      expect.objectContaining({
+        reference: 'postage123',
+        url: 'http://127.0.0.1:1633/bzz/postage123',
+        message: 'File successfully uploaded to Swarm',
+      })
+    );
+  });
+
+  it('throws error if data is missing', async () => {
+    await expect(
+      tool['executeQuery']({ data: '', isPath: false })
+    ).rejects.toThrow('Missing required parameter: data.');
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Missing required parameter: data.'
+    );
+  });
+
+  it('throws error if reading file fails', async () => {
+    
+    const readFileMock = jest.fn<any>().mockRejectedValue(new Error('File read failed'));
+    jest.spyOn(require('util'), 'promisify').mockReturnValue(readFileMock);
+    jest.spyOn(require('util'), 'promisify').mockReturnValue(readFileMock);
+
+    await expect(
+      tool['executeQuery']({ data: '/bad/path.txt', isPath: true })
+    ).rejects.toThrow('Unable to read file at path: /bad/path.txt.');
+
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Unable to read file at path: /bad/path.txt.',
+      expect.any(Error)
+    );
+  });
+
+  it('throws error if getUploadPostageBatchId fails', async () => {
+    const error = new Error('Failed to get postage batch');
+    mockedUtils.getUploadPostageBatchId.mockRejectedValue(error);
+
+    await expect(
+      tool['executeQuery']({ data: 'abc', isPath: false })
+    ).rejects.toThrow('Failed to get postage batch');
+
+    expect(contextMock.logger.error).toHaveBeenCalledWith('Failed to get postage batch');
+  });
+
+  it('uploads large file in deferred mode and creates tag', async () => {
+    // Pretend threshold is small so any data triggers deferred mode
+    swarmConfigMock.deferredUploadSizeThresholdMB = 0.000001;
+
+    const bigData = Buffer.alloc(1024 * 1024, 'a').toString('base64'); // 1MB
+    const result = await tool['executeQuery']({
+      data: bigData,
+      isPath: false,
+    });
+
+    expect(beeMock.createTag).toHaveBeenCalled();
+    expect(beeMock.uploadFile).toHaveBeenCalledWith(
+      'postage123',
+      expect.any(Buffer),
+      undefined,
+      expect.objectContaining({
+        deferred: true,
+        tag: 123,
+      })
+    );
+
+    expect(result['structuredContent']).toEqual(
+      expect.objectContaining({
+        tagId: '123',
+        message:
+          'File upload started in deferred mode. Use query_upload_progress to track progress.',
+      })
+    );
+  });
+
+  it('handles createTag 404 and throws GATEWAY_TAG_ERROR_MESSAGE', async () => {
+    beeMock.createTag.mockRejectedValue({ status: 404 });
+
+    swarmConfigMock.deferredUploadSizeThresholdMB = 0.000001;
+    const bigData = Buffer.alloc(1024 * 1024, 'a').toString('base64');
+
+    await expect(
+      tool['executeQuery']({ data: bigData, isPath: false })
+    ).rejects.toThrow(GATEWAY_TAG_ERROR_MESSAGE);
+
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      GATEWAY_TAG_ERROR_MESSAGE,
+      expect.any(Object)
+    );
+  });
+
+  it('handles uploadFile error gracefully', async () => {
+    const error = new Error('Upload failed');
+    beeMock.uploadFile.mockRejectedValueOnce(error);
+
+    await expect(
+      tool['executeQuery']({ data: 'abc', isPath: false })
+    ).rejects.toThrow('Unable to upload file.');
+
+    expect(contextMock.logger.error).toHaveBeenCalledWith(
+      'Unable to upload file.',
+      error
+    );
+  });
+});

package/src/plugins/community/swarm/__tests__/tools/UploadFolderTool.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it, beforeEach, jest } from '@jest/globals';
+import './SwarmTool.mocks';
+import { UploadFolderTool } from "../../tools/UploadFolderTool";
+import fs from "fs";
+import { beeMock, contextMock, mockedUtils, swarmConfigMock } from './SwarmTool.mocks';
+import { HederaAgentKit } from "hedera-agent-kit";
+import { Reference, UploadResult } from '@ethersphere/bee-js';
+
+describe("UploadFolderTool", () => {
+  let tool: UploadFolderTool;
+
+  const hederaKitMock = {} as HederaAgentKit;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    
+    tool = new UploadFolderTool({
+      hederaKit: hederaKitMock,
+      config: swarmConfigMock,
+      bee: beeMock,
+      logger: contextMock.logger,
+    });
+
+    mockedUtils.getUploadPostageBatchId.mockResolvedValue('postage123');
+    const reference = {
+      toString: () => "postage123",
+    } as unknown as Reference;
+    
+    const uploadResult = {
+      reference
+    } as unknown as UploadResult;
+    
+    beeMock.uploadFilesFromDirectory.mockResolvedValue(uploadResult);
+    
+    const tagDataMock = {
+      address: '0x123',
+      synced: 50,
+      seen: 25,
+      split: 100,
+      stored: 10,
+      sent: 10,
+      uid: 123,
+      startedAt: '2025-11-04T12:00:00Z',
+    };
+    
+    beeMock.createTag.mockResolvedValue(tagDataMock);
+    
+    const mockStats: fs.Stats = {
+      isDirectory: () => true,
+    } as unknown as fs.Stats;
+    const mockStatFn = jest.fn<any>().mockResolvedValue(mockStats);
+    jest.spyOn(require("util"), "promisify").mockReturnValue(mockStatFn);
+  });
+
+  it("uploads folder successfully in deferred mode", async () => {
+    const folderPath = "/mock/folder";
+
+    const result = await tool['executeQuery']({ folderPath });
+
+    expect(mockedUtils.getUploadPostageBatchId).toHaveBeenCalledWith(undefined, beeMock, swarmConfigMock);
+    expect(beeMock.createTag).toHaveBeenCalled();
+    expect(beeMock.uploadFilesFromDirectory).toHaveBeenCalledWith(
+      "postage123",
+      folderPath,
+      expect.objectContaining({
+        deferred: true,
+        tag: 123,
+      })
+    );
+
+    expect(result["structuredContent"]).toEqual(expect.objectContaining({
+      reference: "postage123",
+      url: "http://127.0.0.1:1633/bzz/postage123",
+      message: "Folder upload started in deferred mode. Use swarm-query-upload-progress to track progress.",
+      tagId: "123",
+    }));
+  });
+
+  it("throws error if folderPath is missing", async () => {
+    await expect(tool['executeQuery']({ folderPath: "" }))
+      .rejects.toThrow("Missing required parameter: folderPath.");
+    expect(contextMock.logger.error).toHaveBeenCalledWith("Missing required parameter: folderPath.");
+  });
+
+  it("throws error if path is not a directory", async () => {
+    const mockStats: fs.Stats = {
+      isDirectory: () => false,
+    } as unknown as fs.Stats;
+    const mockStatFn = jest.fn<any>().mockResolvedValue(mockStats);
+    jest.spyOn(require("util"), "promisify").mockReturnValue(mockStatFn);
+
+    const folderPath = "/not/a/dir";
+
+    await expect(tool['executeQuery']({ folderPath }))
+      .rejects.toThrow(`Path is not a directory: ${folderPath}.`);
+    expect(contextMock.logger.error).toHaveBeenCalledWith(`Path is not a directory: ${folderPath}.`);
+  });
+
+  it("throws error if getUploadPostageBatchId fails", async () => {
+    const error = new Error('Failed to get postage batch');
+    mockedUtils.getUploadPostageBatchId.mockRejectedValue(
+      error
+    );
+
+    await expect(tool['executeQuery']({ folderPath: "/mock/folder" }))
+      .rejects.toThrow("Failed to get postage batch");
+    expect(contextMock.logger.error).toHaveBeenCalledWith("Failed to get postage batch");
+  });
+
+  it("handles uploadFilesFromDirectory error", async () => {
+    const error = new Error("Upload failed");
+    beeMock.uploadFilesFromDirectory.mockRejectedValueOnce(error);
+
+    await expect(tool['executeQuery']({ folderPath: "/mock/folder" }))
+      .rejects.toThrow("Unable to upload folder.");
+    expect(contextMock.logger.error).toHaveBeenCalledWith("Unable to upload folder.", error);
+  });
+});

package/src/plugins/community/swarm/config.ts

@@ -0,0 +1,6 @@
+export interface SwarmConfig {
+  beeApiUrl: string;
+  beeFeedPK: string;
+  autoAssignStamp?: boolean;
+  deferredUploadSizeThresholdMB?: number;
+}

package/src/plugins/community/swarm/constants.ts

@@ -0,0 +1,12 @@
+export const NOT_FOUND_STATUS = 404;
+export const BAD_REQUEST_STATUS = 400;
+export const GATEWAY_STAMP_ERROR_MESSAGE =
+  "Endpoint not found. If using Swarm Gateway, postage stamp management endpoints are not available.";
+export const GATEWAY_TAG_ERROR_MESSAGE =
+  "If using Swarm Gateway, tag endpoints are not available.";
+export const POSTAGE_CREATE_TIMEOUT_MESSAGE =
+  "Purchase of postage batch is in progress, it may take a few minutes. Please list you batches after a few minutes to find it.";
+export const CALL_TIMEOUT = 30000;
+export const DEFAULT_DEFERRED_UPLOAD_SIZE_THRESHOLD_MB = 5;
+export const DEFAULT_GATEWAY_BATCH_ID =
+  "0000000000000000000000000000000000000000000000000000000000000000";

package/src/plugins/community/swarm/index.ts

@@ -0,0 +1,2 @@
+export * from "./config";
+export * from "./SwarmPlugin";

package/src/plugins/community/swarm/model.ts

@@ -0,0 +1,23 @@
+import { PostageBatch } from "@ethersphere/bee-js";
+
+export type PostageBatchCurated = Omit<PostageBatch, "batchID"> & {
+  batchID: string;
+};
+
+export interface PostageBatchSummary {
+  stampID: string;
+  usage: string;
+  capacity: string;
+  ttl: string;
+  immutable: boolean;
+}
+
+export interface ResponseContent<U, V> {
+  raw: U;
+  summary: V;
+}
+
+export interface ResponseWithStructuredContent<T> {
+  content: Array<{ type: "text"; text: string }>;
+  structuredContent: T;
+}