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

package/src/usage/aggregate-usage-stats.ts

@@ -0,0 +1,142 @@
+import type { IAggregatedUsageStats, IUsageStats } from './types';
+
+const MS_PER_SECOND = 1000;
+const SECONDS_PER_MINUTE = 60;
+const MINUTES_PER_HOUR = 60;
+const MS_PER_HOUR = MS_PER_SECOND * SECONDS_PER_MINUTE * MINUTES_PER_HOUR;
+const HOURS_PER_DAY = 24;
+const HOURS_PER_WEEK = 168;
+
+interface IUsageTimeRange {
+  start: Date;
+  end: Date;
+}
+
+function determineUsagePeriod(timeRange: IUsageTimeRange | undefined): string {
+  if (!timeRange) return 'all';
+
+  const diff = timeRange.end.getTime() - timeRange.start.getTime();
+  const hours = diff / MS_PER_HOUR;
+
+  if (hours <= 1) return 'hour';
+  if (hours <= HOURS_PER_DAY) return 'day';
+  if (hours <= HOURS_PER_WEEK) return 'week';
+  return 'month';
+}
+
+function resolveTimeRangeStats(
+  stats: readonly IUsageStats[],
+  timeRange: IUsageTimeRange | undefined,
+): { startTime: Date; endTime: Date; period: string } {
+  if (timeRange) {
+    return {
+      startTime: timeRange.start,
+      endTime: timeRange.end,
+      period: determineUsagePeriod(timeRange),
+    };
+  }
+
+  if (stats.length > 0) {
+    const first = stats[0]?.timestamp;
+    const last = stats[stats.length - 1]?.timestamp;
+    const now = new Date();
+    return {
+      startTime: first ?? now,
+      endTime: last ?? now,
+      period: determineUsagePeriod(undefined),
+    };
+  }
+
+  const now = new Date();
+  return {
+    startTime: now,
+    endTime: now,
+    period: determineUsagePeriod(undefined),
+  };
+}
+
+/**
+ * Aggregate usage statistics into a single summary object.
+ * This is a shared SSOT utility (composition over inheritance).
+ */
+export function aggregateUsageStats(
+  stats: readonly IUsageStats[],
+  timeRange?: IUsageTimeRange,
+): IAggregatedUsageStats {
+  const timeRangeStats = resolveTimeRangeStats(stats, timeRange);
+
+  const aggregated: IAggregatedUsageStats = {
+    totalRequests: stats.length,
+    totalTokens: stats.reduce((sum, entry) => sum + entry.tokensUsed.total, 0),
+    totalCost: stats.reduce((sum, entry) => sum + (entry.cost?.total ?? 0), 0),
+    totalDuration: stats.reduce((sum, entry) => sum + entry.duration, 0),
+    successRate:
+      stats.length > 0 ? stats.filter((entry) => entry.success).length / stats.length : 0,
+    providerStats: {},
+    modelStats: {},
+    toolStats: {},
+    timeRangeStats,
+  };
+
+  // Aggregate by provider
+  for (const entry of stats) {
+    if (!aggregated.providerStats[entry.provider]) {
+      aggregated.providerStats[entry.provider] = {
+        requests: 0,
+        tokens: 0,
+        cost: 0,
+        duration: 0,
+      };
+    }
+    const providerStat = aggregated.providerStats[entry.provider];
+    if (providerStat) {
+      providerStat.requests += entry.requestCount;
+      providerStat.tokens += entry.tokensUsed.total;
+      providerStat.cost += entry.cost?.total ?? 0;
+      providerStat.duration += entry.duration;
+    }
+  }
+
+  // Aggregate by model
+  for (const entry of stats) {
+    if (!aggregated.modelStats[entry.model]) {
+      aggregated.modelStats[entry.model] = {
+        requests: 0,
+        tokens: 0,
+        cost: 0,
+        duration: 0,
+      };
+    }
+    const modelStat = aggregated.modelStats[entry.model];
+    if (modelStat) {
+      modelStat.requests += entry.requestCount;
+      modelStat.tokens += entry.tokensUsed.total;
+      modelStat.cost += entry.cost?.total ?? 0;
+      modelStat.duration += entry.duration;
+    }
+  }
+
+  // Aggregate by tools
+  for (const entry of stats) {
+    const toolsUsed = entry.toolsUsed;
+    if (!toolsUsed) continue;
+
+    for (const tool of toolsUsed) {
+      if (!aggregated.toolStats[tool]) {
+        aggregated.toolStats[tool] = {
+          usageCount: 0,
+          successCount: 0,
+          totalDuration: 0,
+        };
+      }
+      const toolStat = aggregated.toolStats[tool];
+      toolStat.usageCount += 1;
+      if (entry.success) {
+        toolStat.successCount += 1;
+      }
+      toolStat.totalDuration += entry.duration;
+    }
+  }
+
+  return aggregated;
+}

package/src/usage/index.ts

@@ -0,0 +1,14 @@
+export { UsagePlugin } from './usage-plugin';
+export { aggregateUsageStats } from './aggregate-usage-stats';
+export { MemoryUsageStorage } from './storages/memory-storage';
+export { FileUsageStorage } from './storages/file-storage';
+export { RemoteUsageStorage } from './storages/remote-storage';
+export { SilentUsageStorage } from './storages/silent-storage';
+export type {
+  TUsageTrackingStrategy,
+  IUsageStats,
+  IAggregatedUsageStats,
+  IUsagePluginOptions,
+  IUsagePluginStats,
+  IUsageStorage,
+} from './types';

package/src/usage/storages/file-storage.ts

@@ -0,0 +1,115 @@
+import { IUsageStorage, IUsageStats, IAggregatedUsageStats } from '../types';
+import { createLogger, type ILogger, StorageError } from '@robota-sdk/agent-core';
+import { aggregateUsageStats } from '../aggregate-usage-stats';
+
+/**
+ * File storage implementation for usage statistics
+ */
+export class FileUsageStorage implements IUsageStorage {
+  private filePath: string;
+  private logger: ILogger;
+
+  constructor(filePath: string) {
+    this.filePath = filePath;
+    this.logger = createLogger('FileUsageStorage');
+  }
+
+  async save(entry: IUsageStats): Promise<void> {
+    try {
+      // File operations would be implemented here
+      // This is a placeholder for actual file system operations
+      this.logger.warn('File usage storage not fully implemented yet', {
+        filePath: this.filePath,
+        entry: {
+          timestamp: entry.timestamp.toISOString(),
+          provider: entry.provider,
+          model: entry.model,
+          tokens: entry.tokensUsed.total,
+          cost: entry.cost?.total,
+          success: entry.success,
+        },
+      });
+    } catch (error) {
+      throw new StorageError('Failed to save usage stats to file', {
+        filePath: this.filePath,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  async getStats(
+    conversationId?: string,
+    timeRange?: { start: Date; end: Date },
+  ): Promise<IUsageStats[]> {
+    try {
+      // File operations would be implemented here
+      this.logger.warn('File usage storage not fully implemented yet', {
+        filePath: this.filePath,
+        conversationId,
+        timeRange,
+      });
+      return [];
+    } catch (error) {
+      throw new StorageError('Failed to load usage stats from file', {
+        filePath: this.filePath,
+        conversationId: conversationId || 'all',
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  async getAggregatedStats(timeRange?: { start: Date; end: Date }): Promise<IAggregatedUsageStats> {
+    try {
+      const stats = await this.getStats(undefined, timeRange);
+      return aggregateUsageStats(stats, timeRange);
+    } catch (error) {
+      throw new StorageError('Failed to get aggregated usage stats from file', {
+        filePath: this.filePath,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  async clear(): Promise<void> {
+    try {
+      // File operations would be implemented here
+      this.logger.warn('File usage storage not fully implemented yet', {
+        filePath: this.filePath,
+        operation: 'clear',
+      });
+    } catch (error) {
+      throw new StorageError('Failed to clear usage stats from file', {
+        filePath: this.filePath,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  async flush(): Promise<void> {
+    try {
+      // File flushing would be implemented here
+      this.logger.warn('File usage storage flush not fully implemented yet', {
+        filePath: this.filePath,
+      });
+    } catch (error) {
+      throw new StorageError('Failed to flush usage stats to file', {
+        filePath: this.filePath,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  async close(): Promise<void> {
+    try {
+      // File closing would be implemented here
+      this.logger.warn('File usage storage close not fully implemented yet', {
+        filePath: this.filePath,
+      });
+    } catch (error) {
+      throw new StorageError('Failed to close usage stats file', {
+        filePath: this.filePath,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+}

package/src/usage/storages/index.ts

@@ -0,0 +1,4 @@
+export { MemoryUsageStorage } from './memory-storage';
+export { FileUsageStorage } from './file-storage';
+export { RemoteUsageStorage } from './remote-storage';
+export { SilentUsageStorage } from './silent-storage';

package/src/usage/storages/memory-storage.ts

@@ -0,0 +1,61 @@
+import { IUsageStorage, IUsageStats, IAggregatedUsageStats } from '../types';
+import { aggregateUsageStats } from '../aggregate-usage-stats';
+
+/**
+ * Memory storage implementation for usage statistics
+ */
+export class MemoryUsageStorage implements IUsageStorage {
+  private entries: IUsageStats[] = [];
+  private maxEntries: number;
+
+  constructor(maxEntries: number = 10000) {
+    this.maxEntries = maxEntries;
+  }
+
+  async save(entry: IUsageStats): Promise<void> {
+    // Remove oldest entries if limit exceeded
+    if (this.entries.length >= this.maxEntries) {
+      this.entries = this.entries.slice(-this.maxEntries + 1);
+    }
+
+    this.entries.push({ ...entry });
+  }
+
+  async getStats(
+    conversationId?: string,
+    timeRange?: { start: Date; end: Date },
+  ): Promise<IUsageStats[]> {
+    let filtered = [...this.entries];
+
+    if (conversationId) {
+      filtered = filtered.filter((entry) => entry.conversationId === conversationId);
+    }
+
+    if (timeRange) {
+      filtered = filtered.filter(
+        (entry) => entry.timestamp >= timeRange.start && entry.timestamp <= timeRange.end,
+      );
+    }
+
+    return filtered;
+  }
+
+  async getAggregatedStats(timeRange?: { start: Date; end: Date }): Promise<IAggregatedUsageStats> {
+    const stats = await this.getStats(undefined, timeRange);
+    return aggregateUsageStats(stats, timeRange);
+  }
+
+  async clear(): Promise<void> {
+    this.entries = [];
+  }
+
+  async flush(): Promise<void> {
+    // Memory storage doesn't need flushing
+  }
+
+  async close(): Promise<void> {
+    // Memory storage doesn't need closing
+  }
+
+  // Aggregation logic intentionally lives in ../aggregate-usage-stats.ts (SSOT utility).
+}

package/src/usage/storages/remote-storage.ts

@@ -0,0 +1,143 @@
+import { IUsageStorage, IUsageStats, IAggregatedUsageStats } from '../types';
+import {
+  createLogger,
+  type ILogger,
+  StorageError,
+  type TTimerId,
+  startPeriodicTask,
+  stopPeriodicTask,
+} from '@robota-sdk/agent-core';
+import { aggregateUsageStats } from '../aggregate-usage-stats';
+
+const SAMPLE_SIZE = 3;
+
+/**
+ * Remote storage implementation for usage statistics with batching
+ */
+export class RemoteUsageStorage implements IUsageStorage {
+  private apiUrl: string;
+  private batchSize: number;
+  private flushInterval: number;
+  private batch: IUsageStats[] = [];
+  private timer?: TTimerId;
+  private logger: ILogger;
+
+  constructor(
+    apiUrl: string,
+    _apiKey: string,
+    _timeout: number,
+    _headers: Record<string, string> = {},
+    batchSize: number = 50,
+    flushInterval: number = 60000, // 1 minute
+  ) {
+    this.apiUrl = apiUrl;
+    this.batchSize = batchSize;
+    this.flushInterval = flushInterval;
+    this.logger = createLogger('RemoteUsageStorage');
+
+    this.timer = startPeriodicTask(
+      this.logger,
+      { name: 'RemoteUsageStorage.flush', intervalMs: this.flushInterval },
+      async () => {
+        await this.flush();
+      },
+    );
+  }
+
+  async save(entry: IUsageStats): Promise<void> {
+    this.batch.push(entry);
+
+    if (this.batch.length >= this.batchSize) {
+      await this.flush();
+    }
+  }
+
+  async getStats(
+    conversationId?: string,
+    timeRange?: { start: Date; end: Date },
+  ): Promise<IUsageStats[]> {
+    try {
+      // Remote API call would be implemented here
+      this.logger.warn('Remote usage storage not fully implemented yet', {
+        endpoint: this.apiUrl,
+        operation: 'getStats',
+        conversationId,
+        timeRange,
+      });
+      return [];
+    } catch (error) {
+      throw new StorageError('Failed to get usage stats from remote endpoint', {
+        endpoint: this.apiUrl,
+        conversationId: conversationId || 'all',
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  async getAggregatedStats(timeRange?: { start: Date; end: Date }): Promise<IAggregatedUsageStats> {
+    try {
+      const stats = await this.getStats(undefined, timeRange);
+      return aggregateUsageStats(stats, timeRange);
+    } catch (error) {
+      throw new StorageError('Failed to get aggregated usage stats from remote endpoint', {
+        endpoint: this.apiUrl,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  async clear(): Promise<void> {
+    try {
+      // Remote API call would be implemented here
+      this.logger.warn('Remote usage storage not fully implemented yet', {
+        endpoint: this.apiUrl,
+        operation: 'clear',
+      });
+    } catch (error) {
+      throw new StorageError('Failed to clear usage stats from remote endpoint', {
+        endpoint: this.apiUrl,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  async flush(): Promise<void> {
+    if (this.batch.length === 0) return;
+
+    const statsToSend = [...this.batch];
+    this.batch = [];
+
+    try {
+      // Remote API call would be implemented here
+      // This is a placeholder for actual HTTP requests
+      this.logger.warn('Remote usage storage not fully implemented yet', {
+        endpoint: this.apiUrl,
+        operation: 'flush',
+        batchSize: statsToSend.length,
+        sample: statsToSend.slice(0, SAMPLE_SIZE).map((stat) => ({
+          timestamp: stat.timestamp.toISOString(),
+          provider: stat.provider,
+          model: stat.model,
+          tokens: stat.tokensUsed.total,
+          cost: stat.cost?.total,
+          success: stat.success,
+        })),
+      });
+    } catch (error) {
+      // Re-add failed batch to the beginning of current batch
+      this.batch = [...statsToSend, ...this.batch];
+      throw new StorageError('Failed to send usage stats to remote endpoint', {
+        endpoint: this.apiUrl,
+        batchSize: statsToSend.length,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  async close(): Promise<void> {
+    stopPeriodicTask(this.timer);
+    this.timer = undefined;
+
+    await this.flush();
+  }
+}

package/src/usage/storages/silent-storage.ts

@@ -0,0 +1,38 @@
+import { IUsageStorage, IUsageStats, IAggregatedUsageStats } from '../types';
+import { aggregateUsageStats } from '../aggregate-usage-stats';
+
+/**
+ * Silent storage implementation for usage statistics (no-op)
+ */
+export class SilentUsageStorage implements IUsageStorage {
+  async save(_entry: IUsageStats): Promise<void> {
+    // Silent mode - do nothing
+  }
+
+  async getStats(
+    _conversationId?: string,
+    _timeRange?: { start: Date; end: Date },
+  ): Promise<IUsageStats[]> {
+    // Silent mode - return empty array
+    return [];
+  }
+
+  async getAggregatedStats(_timeRange?: {
+    start: Date;
+    end: Date;
+  }): Promise<IAggregatedUsageStats> {
+    return aggregateUsageStats([], _timeRange);
+  }
+
+  async clear(): Promise<void> {
+    // Silent mode - do nothing
+  }
+
+  async flush(): Promise<void> {
+    // Silent mode - do nothing
+  }
+
+  async close(): Promise<void> {
+    // Silent mode - do nothing
+  }
+}

package/src/usage/types.ts

@@ -0,0 +1,132 @@
+/**
+ * Usage tracking strategy types
+ */
+export type TUsageTrackingStrategy = 'memory' | 'file' | 'remote' | 'silent';
+
+/**
+ * Usage statistics entry
+ */
+export interface IUsageStats {
+  conversationId?: string;
+  executionId?: string;
+  timestamp: Date;
+  provider: string;
+  model: string;
+  tokensUsed: {
+    input: number;
+    output: number;
+    total: number;
+  };
+  cost?: {
+    input: number;
+    output: number;
+    total: number;
+  };
+  requestCount: number;
+  duration: number; // in milliseconds
+  success: boolean;
+  toolsUsed?: string[];
+  metadata?: Record<string, string | number | boolean | Date>;
+}
+
+/**
+ * Aggregated usage statistics
+ */
+export interface IAggregatedUsageStats {
+  totalRequests: number;
+  totalTokens: number;
+  totalCost: number;
+  totalDuration: number;
+  successRate: number;
+  providerStats: Record<
+    string,
+    {
+      requests: number;
+      tokens: number;
+      cost: number;
+      duration: number;
+    }
+  >;
+  modelStats: Record<
+    string,
+    {
+      requests: number;
+      tokens: number;
+      cost: number;
+      duration: number;
+    }
+  >;
+  toolStats: Record<
+    string,
+    {
+      usageCount: number;
+      successCount: number;
+      totalDuration: number;
+    }
+  >;
+  timeRangeStats: {
+    startTime: Date;
+    endTime: Date;
+    period: string; // 'hour', 'day', 'week', 'month'
+  };
+}
+
+import type { IPluginOptions, IPluginStats } from '@robota-sdk/agent-core';
+
+/**
+ * Configuration options for usage plugin
+ */
+export interface IUsagePluginOptions extends IPluginOptions {
+  /** Usage tracking strategy to use */
+  strategy: TUsageTrackingStrategy;
+  /** File path for file strategy */
+  filePath?: string;
+  /** Remote endpoint for remote strategy */
+  remoteEndpoint?: string;
+  /** Headers for remote logging */
+  remoteHeaders?: Record<string, string>;
+  /** Maximum number of usage entries to keep in memory */
+  maxEntries?: number;
+  /** Whether to track token costs */
+  trackCosts?: boolean;
+  /** Cost per token rates for different models */
+  costRates?: Record<string, { input: number; output: number }>;
+  /** Batch size for remote reporting */
+  batchSize?: number;
+  /** Flush interval for batched reporting in milliseconds */
+  flushInterval?: number;
+  /** Whether to aggregate statistics */
+  aggregateStats?: boolean;
+  /** Aggregation interval in milliseconds */
+  aggregationInterval?: number;
+}
+
+/**
+ * Usage storage interface
+ */
+export interface IUsageStorage {
+  save(entry: IUsageStats): Promise<void>;
+  getStats(conversationId?: string, timeRange?: { start: Date; end: Date }): Promise<IUsageStats[]>;
+  getAggregatedStats(timeRange?: { start: Date; end: Date }): Promise<IAggregatedUsageStats>;
+  clear(): Promise<void>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+
+/**
+ * Usage plugin statistics
+ */
+export interface IUsagePluginStats extends IPluginStats {
+  /** Total number of usage entries tracked */
+  entriesTracked: number;
+  /** Total tokens tracked */
+  totalTokens: number;
+  /** Total cost tracked */
+  totalCost: number;
+  /** Current tracking strategy */
+  strategy: TUsageTrackingStrategy;
+  /** Last tracking timestamp */
+  lastTrackTime?: Date;
+  /** Number of failed tracking attempts */
+  failedTracking: number;
+}