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

package/src/usage/__tests__/memory-storage.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { MemoryUsageStorage } from '../storages/memory-storage';
+import type { IUsageStats } from '../types';
+
+function makeEntry(overrides: Partial<IUsageStats> = {}): IUsageStats {
+  return {
+    provider: 'openai',
+    model: 'gpt-4',
+    tokensUsed: { input: 100, output: 50, total: 150 },
+    requestCount: 1,
+    duration: 500,
+    success: true,
+    timestamp: new Date(),
+    ...overrides,
+  };
+}
+
+describe('MemoryUsageStorage', () => {
+  let storage: MemoryUsageStorage;
+
+  beforeEach(() => {
+    storage = new MemoryUsageStorage(100);
+  });
+
+  it('saves and retrieves entries', async () => {
+    await storage.save(makeEntry());
+    const stats = await storage.getStats();
+    expect(stats).toHaveLength(1);
+  });
+
+  it('evicts oldest entries when maxEntries exceeded', async () => {
+    storage = new MemoryUsageStorage(3);
+    await storage.save(makeEntry({ provider: 'first' }));
+    await storage.save(makeEntry({ provider: 'second' }));
+    await storage.save(makeEntry({ provider: 'third' }));
+    await storage.save(makeEntry({ provider: 'fourth' }));
+    const stats = await storage.getStats();
+    expect(stats).toHaveLength(3);
+    // First entry should be evicted
+    expect(stats.some((s) => s.provider === 'first')).toBe(false);
+    expect(stats.some((s) => s.provider === 'fourth')).toBe(true);
+  });
+
+  it('filters by conversationId', async () => {
+    await storage.save(makeEntry({ conversationId: 'conv-1' }));
+    await storage.save(makeEntry({ conversationId: 'conv-2' }));
+    const stats = await storage.getStats('conv-1');
+    expect(stats).toHaveLength(1);
+    expect(stats[0].conversationId).toBe('conv-1');
+  });
+
+  it('filters by time range', async () => {
+    const old = new Date('2024-01-01');
+    const recent = new Date('2025-06-01');
+    await storage.save(makeEntry({ timestamp: old }));
+    await storage.save(makeEntry({ timestamp: recent }));
+    const stats = await storage.getStats(undefined, {
+      start: new Date('2025-01-01'),
+      end: new Date('2026-01-01'),
+    });
+    expect(stats).toHaveLength(1);
+  });
+
+  it('returns aggregated stats', async () => {
+    await storage.save(makeEntry({ success: true }));
+    await storage.save(makeEntry({ success: false }));
+    const aggregated = await storage.getAggregatedStats();
+    expect(aggregated.totalRequests).toBe(2);
+    expect(aggregated.successRate).toBe(0.5);
+  });
+
+  it('clears all entries', async () => {
+    await storage.save(makeEntry());
+    await storage.clear();
+    const stats = await storage.getStats();
+    expect(stats).toHaveLength(0);
+  });
+
+  it('flush and close are no-ops', async () => {
+    await expect(storage.flush()).resolves.toBeUndefined();
+    await expect(storage.close()).resolves.toBeUndefined();
+  });
+});

package/src/usage/__tests__/silent-storage.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest';
+import { SilentUsageStorage } from '../storages/silent-storage';
+import type { IUsageStats } from '../types';
+
+describe('SilentUsageStorage', () => {
+  const storage = new SilentUsageStorage();
+
+  const entry: IUsageStats = {
+    provider: 'openai',
+    model: 'gpt-4',
+    tokensUsed: { input: 100, output: 50, total: 150 },
+    requestCount: 1,
+    duration: 500,
+    success: true,
+    timestamp: new Date(),
+  };
+
+  it('save is a no-op', async () => {
+    await expect(storage.save(entry)).resolves.toBeUndefined();
+  });
+
+  it('getStats returns empty array', async () => {
+    const stats = await storage.getStats();
+    expect(stats).toEqual([]);
+  });
+
+  it('getAggregatedStats returns zeroed aggregation', async () => {
+    const agg = await storage.getAggregatedStats();
+    expect(agg.totalRequests).toBe(0);
+    expect(agg.totalTokens).toBe(0);
+  });
+
+  it('clear is a no-op', async () => {
+    await expect(storage.clear()).resolves.toBeUndefined();
+  });
+
+  it('flush is a no-op', async () => {
+    await expect(storage.flush()).resolves.toBeUndefined();
+  });
+
+  it('close is a no-op', async () => {
+    await expect(storage.close()).resolves.toBeUndefined();
+  });
+});

package/src/usage/__tests__/usage-plugin-helpers.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect } from 'vitest';
+import {
+  resolvePluginOptions,
+  validateUsageOptions,
+  calculateCost,
+  isModuleSuccessEvent,
+  isModuleErrorEvent,
+  extractStringField,
+  resolveOperation,
+} from '../usage-plugin-helpers';
+import { ConfigurationError, EVENT_EMITTER_EVENTS } from '@robota-sdk/agent-core';
+
+describe('usage-plugin-helpers', () => {
+  describe('resolvePluginOptions', () => {
+    it('returns defaults for minimal options', () => {
+      const resolved = resolvePluginOptions({ strategy: 'memory' });
+      expect(resolved.strategy).toBe('memory');
+      expect(resolved.enabled).toBe(true);
+      expect(resolved.trackCosts).toBe(true);
+      expect(resolved.maxEntries).toBe(10000);
+      expect(resolved.batchSize).toBe(50);
+      expect(resolved.flushInterval).toBe(60000);
+      expect(resolved.aggregateStats).toBe(true);
+      expect(resolved.aggregationInterval).toBe(300000);
+    });
+
+    it('preserves explicit costRates', () => {
+      const rates = { 'gpt-4': { input: 0.03, output: 0.06 } };
+      const resolved = resolvePluginOptions({ strategy: 'memory', costRates: rates });
+      expect(resolved.costRates).toEqual(rates);
+    });
+
+    it('omits costRates when not provided', () => {
+      const resolved = resolvePluginOptions({ strategy: 'memory' });
+      expect(resolved.costRates).toBeUndefined();
+    });
+  });
+
+  describe('calculateCost', () => {
+    const rates = { 'gpt-4': { input: 0.03, output: 0.06 } };
+
+    it('calculates cost for known model', () => {
+      const cost = calculateCost(rates, 'gpt-4', { input: 100, output: 50 });
+      expect(cost).toEqual({ input: 3, output: 3, total: 6 });
+    });
+
+    it('returns undefined for unknown model', () => {
+      expect(calculateCost(rates, 'unknown', { input: 100, output: 50 })).toBeUndefined();
+    });
+
+    it('returns undefined when no rates provided', () => {
+      expect(calculateCost(undefined, 'gpt-4', { input: 100, output: 50 })).toBeUndefined();
+    });
+  });
+
+  describe('validateUsageOptions', () => {
+    it('passes for valid memory options', () => {
+      expect(() => validateUsageOptions({ strategy: 'memory' })).not.toThrow();
+    });
+
+    it('passes for valid file options', () => {
+      expect(() =>
+        validateUsageOptions({ strategy: 'file', filePath: '/tmp/usage.json' }),
+      ).not.toThrow();
+    });
+
+    it('passes for valid remote options', () => {
+      expect(() =>
+        validateUsageOptions({ strategy: 'remote', remoteEndpoint: 'http://example.com' }),
+      ).not.toThrow();
+    });
+
+    it('throws for empty strategy', () => {
+      expect(() => validateUsageOptions({ strategy: '' as any })).toThrow(ConfigurationError);
+    });
+
+    it('throws for invalid strategy', () => {
+      expect(() => validateUsageOptions({ strategy: 'invalid' as any })).toThrow(
+        ConfigurationError,
+      );
+    });
+
+    it('throws for file strategy without filePath', () => {
+      expect(() => validateUsageOptions({ strategy: 'file' })).toThrow(ConfigurationError);
+    });
+
+    it('throws for remote strategy without endpoint', () => {
+      expect(() => validateUsageOptions({ strategy: 'remote' })).toThrow(ConfigurationError);
+    });
+  });
+
+  describe('isModuleSuccessEvent', () => {
+    it('returns true for module completion events', () => {
+      expect(isModuleSuccessEvent(EVENT_EMITTER_EVENTS.MODULE_INITIALIZE_COMPLETE)).toBe(true);
+      expect(isModuleSuccessEvent(EVENT_EMITTER_EVENTS.MODULE_EXECUTION_COMPLETE)).toBe(true);
+      expect(isModuleSuccessEvent(EVENT_EMITTER_EVENTS.MODULE_DISPOSE_COMPLETE)).toBe(true);
+    });
+
+    it('returns false for error events', () => {
+      expect(isModuleSuccessEvent(EVENT_EMITTER_EVENTS.MODULE_INITIALIZE_ERROR)).toBe(false);
+    });
+
+    it('returns false for unrelated events', () => {
+      expect(isModuleSuccessEvent('some.random.event' as any)).toBe(false);
+    });
+  });
+
+  describe('isModuleErrorEvent', () => {
+    it('returns true for module error events', () => {
+      expect(isModuleErrorEvent(EVENT_EMITTER_EVENTS.MODULE_INITIALIZE_ERROR)).toBe(true);
+      expect(isModuleErrorEvent(EVENT_EMITTER_EVENTS.MODULE_EXECUTION_ERROR)).toBe(true);
+      expect(isModuleErrorEvent(EVENT_EMITTER_EVENTS.MODULE_DISPOSE_ERROR)).toBe(true);
+    });
+
+    it('returns false for success events', () => {
+      expect(isModuleErrorEvent(EVENT_EMITTER_EVENTS.MODULE_EXECUTION_COMPLETE)).toBe(false);
+    });
+  });
+
+  describe('extractStringField', () => {
+    it('extracts string field from object', () => {
+      expect(extractStringField({ name: 'test' }, 'name')).toBe('test');
+    });
+
+    it('returns "unknown" for missing field', () => {
+      expect(extractStringField({ name: 'test' }, 'missing')).toBe('unknown');
+    });
+
+    it('returns "unknown" for non-string field', () => {
+      expect(extractStringField({ count: 42 }, 'count')).toBe('unknown');
+    });
+
+    it('returns "unknown" for null data', () => {
+      expect(extractStringField(null, 'field')).toBe('unknown');
+    });
+
+    it('returns "unknown" for undefined data', () => {
+      expect(extractStringField(undefined, 'field')).toBe('unknown');
+    });
+  });
+
+  describe('resolveOperation', () => {
+    it('returns "initialization" for initialize events', () => {
+      expect(resolveOperation('module.initialize.complete')).toBe('initialization');
+    });
+
+    it('returns "execution" for execution events', () => {
+      expect(resolveOperation('module.execution.complete')).toBe('execution');
+    });
+
+    it('returns "disposal" for other events', () => {
+      expect(resolveOperation('module.dispose.complete')).toBe('disposal');
+    });
+  });
+});

package/src/usage/__tests__/usage-plugin.test.ts

@@ -0,0 +1,358 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { UsagePlugin } from '../usage-plugin';
+import { ConfigurationError, PluginError } from '@robota-sdk/agent-core';
+
+describe('UsagePlugin', () => {
+  let plugin: UsagePlugin;
+
+  afterEach(async () => {
+    if (plugin) {
+      await plugin.destroy();
+    }
+  });
+
+  describe('constructor', () => {
+    it('creates plugin with memory strategy', () => {
+      plugin = new UsagePlugin({ strategy: 'memory' });
+      expect(plugin.name).toBe('UsagePlugin');
+      expect(plugin.version).toBe('1.0.0');
+    });
+
+    it('creates plugin with silent strategy', () => {
+      plugin = new UsagePlugin({ strategy: 'silent' });
+      expect(plugin.name).toBe('UsagePlugin');
+    });
+
+    it('throws ConfigurationError for missing strategy', () => {
+      expect(() => new UsagePlugin({ strategy: '' as any })).toThrow(ConfigurationError);
+    });
+
+    it('throws ConfigurationError for invalid strategy', () => {
+      expect(() => new UsagePlugin({ strategy: 'invalid' as any })).toThrow(ConfigurationError);
+    });
+
+    it('throws ConfigurationError for file strategy without filePath', () => {
+      expect(() => new UsagePlugin({ strategy: 'file' })).toThrow(ConfigurationError);
+    });
+
+    it('throws ConfigurationError for remote strategy without endpoint', () => {
+      expect(() => new UsagePlugin({ strategy: 'remote' })).toThrow(ConfigurationError);
+    });
+
+    it('throws ConfigurationError for non-positive maxEntries', () => {
+      expect(() => new UsagePlugin({ strategy: 'memory', maxEntries: 0 })).toThrow(
+        ConfigurationError,
+      );
+    });
+
+    it('throws ConfigurationError for non-positive batchSize', () => {
+      expect(() => new UsagePlugin({ strategy: 'memory', batchSize: -1 })).toThrow(
+        ConfigurationError,
+      );
+    });
+
+    it('throws ConfigurationError for non-positive flushInterval', () => {
+      expect(() => new UsagePlugin({ strategy: 'memory', flushInterval: 0 })).toThrow(
+        ConfigurationError,
+      );
+    });
+
+    it('throws ConfigurationError for non-positive aggregationInterval', () => {
+      expect(() => new UsagePlugin({ strategy: 'memory', aggregationInterval: -5 })).toThrow(
+        ConfigurationError,
+      );
+    });
+  });
+
+  describe('recordUsage', () => {
+    beforeEach(() => {
+      plugin = new UsagePlugin({ strategy: 'memory', aggregateStats: false });
+    });
+
+    it('records a usage entry', async () => {
+      await plugin.recordUsage({
+        provider: 'openai',
+        model: 'gpt-4',
+        tokensUsed: { input: 100, output: 50, total: 150 },
+        requestCount: 1,
+        duration: 500,
+        success: true,
+      });
+      const stats = await plugin.getUsageStats();
+      expect(stats).toHaveLength(1);
+      expect(stats[0].provider).toBe('openai');
+      expect(stats[0].model).toBe('gpt-4');
+      expect(stats[0].tokensUsed.total).toBe(150);
+    });
+
+    it('calculates cost when trackCosts is enabled', async () => {
+      plugin = new UsagePlugin({
+        strategy: 'memory',
+        trackCosts: true,
+        costRates: { 'gpt-4': { input: 0.03, output: 0.06 } },
+        aggregateStats: false,
+      });
+
+      await plugin.recordUsage({
+        provider: 'openai',
+        model: 'gpt-4',
+        tokensUsed: { input: 100, output: 50, total: 150 },
+        requestCount: 1,
+        duration: 500,
+        success: true,
+      });
+
+      const stats = await plugin.getUsageStats();
+      expect(stats[0].cost).toBeDefined();
+      expect(stats[0].cost!.input).toBe(3);
+      expect(stats[0].cost!.output).toBe(3);
+      expect(stats[0].cost!.total).toBe(6);
+    });
+
+    it('does not calculate cost when no rate exists for model', async () => {
+      plugin = new UsagePlugin({
+        strategy: 'memory',
+        trackCosts: true,
+        costRates: { 'gpt-4': { input: 0.03, output: 0.06 } },
+        aggregateStats: false,
+      });
+
+      await plugin.recordUsage({
+        provider: 'openai',
+        model: 'gpt-3.5-turbo',
+        tokensUsed: { input: 100, output: 50, total: 150 },
+        requestCount: 1,
+        duration: 300,
+        success: true,
+      });
+
+      const stats = await plugin.getUsageStats();
+      expect(stats[0].cost).toBeUndefined();
+    });
+  });
+
+  describe('getUsageStats', () => {
+    beforeEach(async () => {
+      plugin = new UsagePlugin({ strategy: 'memory', aggregateStats: false });
+      await plugin.recordUsage({
+        provider: 'openai',
+        model: 'gpt-4',
+        tokensUsed: { input: 100, output: 50, total: 150 },
+        requestCount: 1,
+        duration: 500,
+        success: true,
+        conversationId: 'conv-1',
+      });
+      await plugin.recordUsage({
+        provider: 'anthropic',
+        model: 'claude-3',
+        tokensUsed: { input: 200, output: 100, total: 300 },
+        requestCount: 1,
+        duration: 800,
+        success: false,
+        conversationId: 'conv-2',
+      });
+    });
+
+    it('returns all stats when no filter', async () => {
+      const stats = await plugin.getUsageStats();
+      expect(stats).toHaveLength(2);
+    });
+
+    it('filters by conversationId', async () => {
+      const stats = await plugin.getUsageStats('conv-1');
+      expect(stats).toHaveLength(1);
+      expect(stats[0].provider).toBe('openai');
+    });
+  });
+
+  describe('getAggregatedStats', () => {
+    beforeEach(async () => {
+      plugin = new UsagePlugin({ strategy: 'memory', aggregateStats: false });
+      await plugin.recordUsage({
+        provider: 'openai',
+        model: 'gpt-4',
+        tokensUsed: { input: 100, output: 50, total: 150 },
+        requestCount: 1,
+        duration: 500,
+        success: true,
+      });
+      await plugin.recordUsage({
+        provider: 'openai',
+        model: 'gpt-4',
+        tokensUsed: { input: 200, output: 100, total: 300 },
+        requestCount: 1,
+        duration: 800,
+        success: false,
+      });
+    });
+
+    it('aggregates correctly', async () => {
+      const aggregated = await plugin.getAggregatedStats();
+      expect(aggregated.totalRequests).toBe(2);
+      expect(aggregated.totalTokens).toBe(450);
+      expect(aggregated.successRate).toBe(0.5);
+    });
+  });
+
+  describe('clearStats', () => {
+    it('clears all usage statistics', async () => {
+      plugin = new UsagePlugin({ strategy: 'memory', aggregateStats: false });
+      await plugin.recordUsage({
+        provider: 'openai',
+        model: 'gpt-4',
+        tokensUsed: { input: 100, output: 50, total: 150 },
+        requestCount: 1,
+        duration: 500,
+        success: true,
+      });
+      await plugin.clearStats();
+      const stats = await plugin.getUsageStats();
+      expect(stats).toHaveLength(0);
+    });
+  });
+
+  describe('flush', () => {
+    it('flushes without error for memory strategy', async () => {
+      plugin = new UsagePlugin({ strategy: 'memory', aggregateStats: false });
+      await expect(plugin.flush()).resolves.toBeUndefined();
+    });
+  });
+
+  describe('destroy', () => {
+    it('destroys the plugin without error', async () => {
+      plugin = new UsagePlugin({ strategy: 'memory', aggregateStats: false });
+      await expect(plugin.destroy()).resolves.toBeUndefined();
+    });
+  });
+
+  describe('silent strategy', () => {
+    beforeEach(() => {
+      plugin = new UsagePlugin({ strategy: 'silent', aggregateStats: false });
+    });
+
+    it('records and returns empty stats', async () => {
+      await plugin.recordUsage({
+        provider: 'openai',
+        model: 'gpt-4',
+        tokensUsed: { input: 100, output: 50, total: 150 },
+        requestCount: 1,
+        duration: 500,
+        success: true,
+      });
+      const stats = await plugin.getUsageStats();
+      expect(stats).toHaveLength(0);
+    });
+  });
+
+  describe('file strategy', () => {
+    it('creates plugin with file strategy and valid filePath', () => {
+      plugin = new UsagePlugin({
+        strategy: 'file',
+        filePath: './usage.json',
+        aggregateStats: false,
+      });
+      expect(plugin.name).toBe('UsagePlugin');
+    });
+
+    it('records usage with file strategy', async () => {
+      plugin = new UsagePlugin({
+        strategy: 'file',
+        filePath: './usage.json',
+        aggregateStats: false,
+      });
+      await expect(
+        plugin.recordUsage({
+          provider: 'openai',
+          model: 'gpt-4',
+          tokensUsed: { input: 100, output: 50, total: 150 },
+          requestCount: 1,
+          duration: 500,
+          success: true,
+        }),
+      ).resolves.toBeUndefined();
+    });
+  });
+
+  describe('remote strategy', () => {
+    it('creates plugin with remote strategy and valid endpoint', () => {
+      plugin = new UsagePlugin({
+        strategy: 'remote',
+        remoteEndpoint: 'https://api.example.com/usage',
+        aggregateStats: false,
+      });
+      expect(plugin.name).toBe('UsagePlugin');
+    });
+  });
+
+  describe('aggregateStats: true', () => {
+    it('creates plugin with aggregation enabled and runs timer callback', async () => {
+      plugin = new UsagePlugin({
+        strategy: 'memory',
+        aggregateStats: true,
+        aggregationInterval: 50,
+      });
+      expect(plugin).toBeDefined();
+      // allow timer to fire at least once
+      await new Promise((r) => setTimeout(r, 80));
+    });
+  });
+
+  describe('onModuleEvent', () => {
+    beforeEach(() => {
+      plugin = new UsagePlugin({ strategy: 'memory', aggregateStats: false });
+    });
+
+    it('records module success event', async () => {
+      await plugin.onModuleEvent('module.execution.complete', {
+        type: 'module.execution.complete',
+        timestamp: new Date(),
+        executionId: 'eid',
+        sessionId: 'sid',
+        data: { duration: 100, moduleName: 'testModule', moduleType: 'executor' },
+      });
+      const stats = await plugin.getUsageStats();
+      expect(stats).toHaveLength(1);
+      expect(stats[0].provider).toBe('module');
+      expect(stats[0].success).toBe(true);
+    });
+
+    it('records module error event', async () => {
+      await plugin.onModuleEvent('module.execution.error', {
+        type: 'module.execution.error',
+        timestamp: new Date(),
+        executionId: 'eid',
+        sessionId: 'sid',
+        error: new Error('test error'),
+        data: { duration: 50, moduleName: 'testModule', moduleType: 'executor' },
+      });
+      const stats = await plugin.getUsageStats();
+      expect(stats).toHaveLength(1);
+      expect(stats[0].success).toBe(false);
+    });
+
+    it('ignores non-module events', async () => {
+      await plugin.onModuleEvent('conversation.start', {
+        type: 'conversation.start',
+        timestamp: new Date(),
+        executionId: 'eid',
+        sessionId: 'sid',
+        data: {},
+      });
+      const stats = await plugin.getUsageStats();
+      expect(stats).toHaveLength(0);
+    });
+
+    it('ignores events with no duration', async () => {
+      await plugin.onModuleEvent('module.execution.complete', {
+        type: 'module.execution.complete',
+        timestamp: new Date(),
+        executionId: 'eid',
+        sessionId: 'sid',
+        data: { moduleName: 'testModule' },
+      });
+      const stats = await plugin.getUsageStats();
+      expect(stats).toHaveLength(0);
+    });
+  });
+});