@robota-sdk/agent-plugin 3.0.0-beta.64

package/src/conversation-history/__tests__/conversation-history-plugin.test.ts

@@ -0,0 +1,221 @@
+import { randomUUID } from 'node:crypto';
+import { describe, it, expect, afterEach } from 'vitest';
+import { ConversationHistoryPlugin } from '../conversation-history-plugin';
+import { ConfigurationError, PluginError } from '@robota-sdk/agent-core';
+import type { TUniversalMessage } from '@robota-sdk/agent-core';
+
+function createUserMessage(content: string): TUniversalMessage {
+  return {
+    id: randomUUID(),
+    role: 'user',
+    content,
+    state: 'complete',
+    timestamp: new Date(),
+  };
+}
+
+function createAssistantMessage(content: string): TUniversalMessage {
+  return {
+    id: randomUUID(),
+    role: 'assistant',
+    content,
+    state: 'complete',
+    timestamp: new Date(),
+  };
+}
+
+describe('ConversationHistoryPlugin', () => {
+  let plugin: ConversationHistoryPlugin;
+
+  afterEach(async () => {
+    if (plugin) {
+      await plugin.destroy();
+    }
+  });
+
+  describe('constructor', () => {
+    it('initializes with memory storage', () => {
+      plugin = new ConversationHistoryPlugin({ storage: 'memory' });
+      expect(plugin.name).toBe('ConversationHistoryPlugin');
+    });
+
+    it('throws on missing storage strategy', () => {
+      expect(() => new ConversationHistoryPlugin({ storage: '' as any })).toThrow(
+        ConfigurationError,
+      );
+    });
+
+    it('throws on invalid storage strategy', () => {
+      expect(() => new ConversationHistoryPlugin({ storage: 'redis' as any })).toThrow(
+        ConfigurationError,
+      );
+    });
+
+    it('throws on non-positive maxConversations', () => {
+      expect(
+        () => new ConversationHistoryPlugin({ storage: 'memory', maxConversations: 0 }),
+      ).toThrow(ConfigurationError);
+    });
+
+    it('throws on non-positive maxMessagesPerConversation', () => {
+      expect(
+        () => new ConversationHistoryPlugin({ storage: 'memory', maxMessagesPerConversation: -1 }),
+      ).toThrow(ConfigurationError);
+    });
+
+    it('throws when file storage is missing filePath', () => {
+      expect(() => new ConversationHistoryPlugin({ storage: 'file', filePath: '' })).toThrow(
+        ConfigurationError,
+      );
+    });
+
+    it('throws when database storage is missing connectionString', () => {
+      expect(
+        () => new ConversationHistoryPlugin({ storage: 'database', connectionString: '' }),
+      ).toThrow(ConfigurationError);
+    });
+  });
+
+  describe('conversation CRUD', () => {
+    it('starts a conversation and retrieves it', async () => {
+      plugin = new ConversationHistoryPlugin({ storage: 'memory' });
+      await plugin.startConversation('conv-1');
+
+      const entry = await plugin.loadConversation('conv-1');
+      expect(entry).toBeDefined();
+      expect(entry!.conversationId).toBe('conv-1');
+      expect(entry!.messages).toEqual([]);
+    });
+
+    it('adds messages to a conversation', async () => {
+      plugin = new ConversationHistoryPlugin({ storage: 'memory' });
+      await plugin.startConversation('conv-1');
+
+      await plugin.addMessage(createUserMessage('hello'));
+      await plugin.addMessage(createAssistantMessage('hi there'));
+
+      const messages = await plugin.getHistory('conv-1');
+      expect(messages).toHaveLength(2);
+      expect(messages[0].role).toBe('user');
+      expect(messages[1].role).toBe('assistant');
+    });
+
+    it('throws when adding message without active conversation', async () => {
+      plugin = new ConversationHistoryPlugin({ storage: 'memory' });
+
+      await expect(plugin.addMessage(createUserMessage('hello'))).rejects.toThrow(PluginError);
+    });
+
+    it('lists conversations', async () => {
+      plugin = new ConversationHistoryPlugin({ storage: 'memory' });
+      await plugin.startConversation('conv-1');
+      await plugin.startConversation('conv-2');
+
+      const ids = await plugin.listConversations();
+      expect(ids).toContain('conv-1');
+      expect(ids).toContain('conv-2');
+    });
+
+    it('deletes a conversation', async () => {
+      plugin = new ConversationHistoryPlugin({ storage: 'memory' });
+      await plugin.startConversation('conv-1');
+
+      const deleted = await plugin.deleteConversation('conv-1');
+      expect(deleted).toBe(true);
+
+      const entry = await plugin.loadConversation('conv-1');
+      expect(entry).toBeUndefined();
+    });
+
+    it('clears all conversations', async () => {
+      plugin = new ConversationHistoryPlugin({ storage: 'memory' });
+      await plugin.startConversation('conv-1');
+      await plugin.startConversation('conv-2');
+
+      await plugin.clearAllConversations();
+
+      const ids = await plugin.listConversations();
+      expect(ids).toHaveLength(0);
+    });
+  });
+
+  describe('message trimming', () => {
+    it('trims messages when exceeding maxMessagesPerConversation', async () => {
+      plugin = new ConversationHistoryPlugin({
+        storage: 'memory',
+        maxMessagesPerConversation: 3,
+      });
+      await plugin.startConversation('conv-1');
+
+      for (let i = 0; i < 5; i++) {
+        await plugin.addMessage(createUserMessage(`msg-${i}`));
+      }
+
+      const messages = await plugin.getHistory('conv-1');
+      expect(messages).toHaveLength(3);
+      // Should keep the last 3 messages
+      expect(messages[0].content).toBe('msg-2');
+      expect(messages[2].content).toBe('msg-4');
+    });
+  });
+
+  describe('getHistory', () => {
+    it('returns empty array for unknown conversation', async () => {
+      plugin = new ConversationHistoryPlugin({ storage: 'memory' });
+
+      const messages = await plugin.getHistory('nonexistent');
+      expect(messages).toEqual([]);
+    });
+  });
+
+  describe('autoSave: false (batch mode)', () => {
+    it('startConversation persists to storage and queues conversationId in pendingSaves', async () => {
+      plugin = new ConversationHistoryPlugin({ storage: 'memory', autoSave: false });
+      await plugin.startConversation('conv-1');
+      // always persisted immediately so subsequent loads can find it
+      const entry = await plugin.loadConversation('conv-1');
+      expect(entry).toBeDefined();
+      expect(entry!.conversationId).toBe('conv-1');
+    });
+
+    it('addMessage persists to storage and queues conversationId in pendingSaves', async () => {
+      plugin = new ConversationHistoryPlugin({ storage: 'memory', autoSave: false });
+      await plugin.startConversation('conv-1');
+      await plugin.addMessage(createUserMessage('hello'));
+      // always persisted immediately so reads return current state
+      const msgs = await plugin.getHistory('conv-1');
+      expect(msgs).toHaveLength(1);
+      expect(msgs[0].content).toBe('hello');
+    });
+
+    it('savePending flushes pending saves', async () => {
+      plugin = new ConversationHistoryPlugin({ storage: 'memory', autoSave: false });
+      await plugin.startConversation('conv-1');
+      await plugin.savePending();
+      // no error — empty pendingSaves is a no-op
+    });
+
+    it('setupBatchSaving timer runs on autoSave: false', async () => {
+      plugin = new ConversationHistoryPlugin({
+        storage: 'memory',
+        autoSave: false,
+        saveInterval: 50,
+      });
+      expect(plugin).toBeDefined();
+      // timer cleaned up in afterEach via destroy()
+    });
+  });
+
+  describe('destroy', () => {
+    it('completes without error', async () => {
+      plugin = new ConversationHistoryPlugin({ storage: 'memory' });
+      await expect(plugin.destroy()).resolves.not.toThrow();
+    });
+
+    it('completes without error in batch mode', async () => {
+      plugin = new ConversationHistoryPlugin({ storage: 'memory', autoSave: false });
+      await plugin.startConversation('conv-1');
+      await expect(plugin.destroy()).resolves.not.toThrow();
+    });
+  });
+});

package/src/conversation-history/__tests__/history-storages.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect } from 'vitest';
+import { DatabaseHistoryStorage } from '../storages/database-storage';
+import { FileHistoryStorage } from '../storages/file-storage';
+import { MemoryHistoryStorage } from '../storages/memory-storage';
+import type { IConversationHistoryEntry } from '../types';
+
+const entry: IConversationHistoryEntry = {
+  conversationId: 'conv-1',
+  messages: [
+    {
+      id: 'msg-1',
+      role: 'user',
+      content: 'hello',
+      state: 'complete' as const,
+      timestamp: new Date(),
+    },
+  ],
+  startTime: new Date(),
+  lastUpdated: new Date(),
+  metadata: {},
+};
+
+describe('MemoryHistoryStorage', () => {
+  it('saves and loads entries', async () => {
+    const storage = new MemoryHistoryStorage();
+    await storage.save('conv-1', entry);
+    const loaded = await storage.load('conv-1');
+    expect(loaded).toBeDefined();
+    expect(loaded!.conversationId).toBe('conv-1');
+  });
+
+  it('returns undefined for missing conversation', async () => {
+    const storage = new MemoryHistoryStorage();
+    expect(await storage.load('missing')).toBeUndefined();
+  });
+
+  it('lists conversation IDs', async () => {
+    const storage = new MemoryHistoryStorage();
+    await storage.save('conv-1', entry);
+    await storage.save('conv-2', { ...entry, conversationId: 'conv-2' });
+    const list = await storage.list();
+    expect(list).toContain('conv-1');
+    expect(list).toContain('conv-2');
+  });
+
+  it('deletes a conversation', async () => {
+    const storage = new MemoryHistoryStorage();
+    await storage.save('conv-1', entry);
+    const deleted = await storage.delete('conv-1');
+    expect(deleted).toBe(true);
+    expect(await storage.load('conv-1')).toBeUndefined();
+  });
+
+  it('returns false when deleting non-existent', async () => {
+    const storage = new MemoryHistoryStorage();
+    expect(await storage.delete('missing')).toBe(false);
+  });
+
+  it('clears all conversations', async () => {
+    const storage = new MemoryHistoryStorage();
+    await storage.save('conv-1', entry);
+    await storage.clear();
+    expect(await storage.list()).toHaveLength(0);
+  });
+});
+
+describe('DatabaseHistoryStorage', () => {
+  // Placeholder implementation - tests verify it does not throw
+  const storage = new DatabaseHistoryStorage('postgres://user:pass@host/db');
+
+  it('save does not throw', async () => {
+    await expect(storage.save('conv-1', entry)).resolves.toBeUndefined();
+  });
+
+  it('load returns undefined', async () => {
+    expect(await storage.load('conv-1')).toBeUndefined();
+  });
+
+  it('list returns empty array', async () => {
+    expect(await storage.list()).toEqual([]);
+  });
+
+  it('delete returns false', async () => {
+    expect(await storage.delete('conv-1')).toBe(false);
+  });
+
+  it('clear does not throw', async () => {
+    await expect(storage.clear()).resolves.toBeUndefined();
+  });
+});
+
+describe('FileHistoryStorage', () => {
+  // Placeholder implementation - tests verify it does not throw
+  const storage = new FileHistoryStorage('/tmp/history.json');
+
+  it('save does not throw', async () => {
+    await expect(storage.save('conv-1', entry)).resolves.toBeUndefined();
+  });
+
+  it('load returns undefined', async () => {
+    expect(await storage.load('conv-1')).toBeUndefined();
+  });
+
+  it('list returns empty array', async () => {
+    expect(await storage.list()).toEqual([]);
+  });
+
+  it('delete returns false', async () => {
+    expect(await storage.delete('conv-1')).toBe(false);
+  });
+
+  it('clear does not throw', async () => {
+    await expect(storage.clear()).resolves.toBeUndefined();
+  });
+});

package/src/conversation-history/conversation-history-helpers.ts

@@ -0,0 +1,120 @@
+/**
+ * Conversation History Plugin - Validation and storage factory helpers.
+ *
+ * Extracted from conversation-history-plugin.ts to keep each file under 300 lines.
+ * @internal
+ */
+
+import { ConfigurationError, PluginError, type ILogger } from '@robota-sdk/agent-core';
+import { MemoryHistoryStorage, FileHistoryStorage, DatabaseHistoryStorage } from './storages/index';
+import type {
+  IConversationHistoryPluginOptions,
+  IHistoryStorage,
+  IConversationHistoryEntry,
+} from './types';
+
+/** Validate ConversationHistoryPlugin constructor options. @internal */
+export function validateConversationHistoryOptions(
+  options: IConversationHistoryPluginOptions,
+): void {
+  if (!options.storage) {
+    throw new ConfigurationError('Storage strategy is required');
+  }
+
+  if (!['memory', 'file', 'database'].includes(options.storage)) {
+    throw new ConfigurationError('Invalid storage strategy', {
+      validStrategies: ['memory', 'file', 'database'],
+      provided: options.storage,
+    });
+  }
+
+  if (options.storage === 'file' && !options.filePath) {
+    throw new ConfigurationError('File path is required for file storage strategy');
+  }
+
+  if (options.storage === 'database' && !options.connectionString) {
+    throw new ConfigurationError('Connection string is required for database storage strategy');
+  }
+
+  if (options.maxConversations !== undefined && options.maxConversations <= 0) {
+    throw new ConfigurationError('Max conversations must be positive');
+  }
+
+  if (options.maxMessagesPerConversation !== undefined && options.maxMessagesPerConversation <= 0) {
+    throw new ConfigurationError('Max messages per conversation must be positive');
+  }
+}
+
+/**
+ * Load a conversation entry from storage with error wrapping. @internal
+ */
+export async function loadConversationEntry(
+  storage: IHistoryStorage,
+  conversationId: string,
+  pluginName: string,
+  logger: ILogger,
+): Promise<IConversationHistoryEntry | undefined> {
+  try {
+    const entry = await storage.load(conversationId);
+    logger.debug('Loaded conversation', {
+      conversationId,
+      found: !!entry,
+      messageCount: entry?.messages.length ?? 0,
+    });
+    return entry;
+  } catch (error) {
+    throw new PluginError('Failed to load conversation', pluginName, {
+      conversationId,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+/**
+ * Flush all pending conversation saves to storage, logging individual failures. @internal
+ */
+export async function savePendingConversations(
+  storage: IHistoryStorage,
+  pendingSaves: Set<string>,
+  pluginName: string,
+  logger: ILogger,
+): Promise<void> {
+  if (pendingSaves.size === 0) return;
+
+  const conversationIds = Array.from(pendingSaves);
+  logger.debug('Saving pending conversations', { count: conversationIds.length });
+
+  for (const conversationId of conversationIds) {
+    try {
+      const entry = await storage.load(conversationId);
+      if (entry) {
+        await storage.save(conversationId, entry);
+      }
+      pendingSaves.delete(conversationId);
+    } catch (error) {
+      logger.error('Failed to save pending conversation', {
+        conversationId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+}
+
+/** Create IHistoryStorage instance for the given strategy. @internal */
+export function createHistoryStorage(
+  strategy: string,
+  maxConversations: number,
+  filePath: string,
+  connectionString: string,
+): IHistoryStorage {
+  switch (strategy) {
+    case 'memory':
+      return new MemoryHistoryStorage(maxConversations);
+    case 'file':
+      return new FileHistoryStorage(filePath);
+    case 'database':
+      return new DatabaseHistoryStorage(connectionString);
+    default:
+      throw new ConfigurationError('Unknown storage strategy', { strategy });
+  }
+}