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

package/src/limits/index.ts

@@ -0,0 +1,9 @@
+export { LimitsPlugin } from './limits-plugin';
+export type {
+  TLimitsStrategy,
+  ILimitsPluginOptions,
+  TPluginLimitsStatusData,
+  ILimitWindow,
+  ITokenBucket,
+} from './types';
+export type { ILimitsPluginExecutionContext, ILimitsPluginExecutionResult } from './limits-plugin';

package/src/limits/limits-helpers.ts

@@ -0,0 +1,185 @@
+/**
+ * Limits Plugin - Rate limit check, cost calculation, and utility helpers.
+ *
+ * Extracted from limits-plugin.ts to keep each file under 300 lines.
+ * @internal
+ */
+
+import { PluginError } from '@robota-sdk/agent-core';
+import type { TUniversalMessage } from '@robota-sdk/agent-core';
+import type { ILimitWindow, ITokenBucket } from './types';
+
+const COST_DECIMAL_PLACES = 4;
+const CHARS_PER_TOKEN = 4;
+const TOKEN_ESTIMATE_BUFFER = 100;
+const TOKENS_PER_COST_UNIT = 1000;
+const MS_PER_SECOND = 1000;
+
+/** Model-specific cost table (per 1000 tokens). @internal */
+const MODEL_COSTS: Record<string, number> = {
+  'gpt-4': 0.03,
+  'gpt-4-turbo': 0.01,
+  'gpt-3.5-turbo': 0.002,
+  'claude-3-opus': 0.015,
+  'claude-3-sonnet': 0.003,
+  'claude-3-haiku': 0.00025,
+};
+
+/** Default cost calculator: uses model-specific rates or falls back to tokenCostPer1000. @internal */
+export function defaultCostCalculator(
+  tokens: number,
+  model: string,
+  tokenCostPer1000: number,
+): number {
+  return (tokens / TOKENS_PER_COST_UNIT) * (MODEL_COSTS[model] ?? tokenCostPer1000);
+}
+
+/** Estimate token count from message content lengths. @internal */
+export function estimateTokensFromMessages(messages: TUniversalMessage[]): number {
+  return (
+    Math.ceil(messages.reduce((t, m) => t + (m.content?.length || 0), 0) / CHARS_PER_TOKEN) +
+    TOKEN_ESTIMATE_BUFFER
+  );
+}
+
+/** Check and update token-bucket state. Throws PluginError if any limit is exceeded. @internal */
+export function checkTokenBucket(
+  bucket: ITokenBucket,
+  now: number,
+  estimatedTokens: number,
+  estimatedCost: number,
+  options: {
+    bucketSize: number;
+    refillRate: number;
+    timeWindow: number;
+    maxRequests: number;
+    maxCost: number;
+  },
+  pluginName: string,
+): void {
+  const timePassed = (now - bucket.lastRefill) / MS_PER_SECOND;
+  bucket.tokens = Math.min(options.bucketSize, bucket.tokens + timePassed * options.refillRate);
+  bucket.lastRefill = now;
+
+  if (bucket.tokens < estimatedTokens) {
+    throw new PluginError(
+      `Token bucket depleted. Available: ${Math.floor(bucket.tokens)}, Required: ${estimatedTokens}`,
+      pluginName,
+      { availableTokens: bucket.tokens, requiredTokens: estimatedTokens },
+    );
+  }
+
+  if (now - bucket.windowStart >= options.timeWindow) {
+    bucket.requests = 0;
+    bucket.cost = 0;
+    bucket.windowStart = now;
+  }
+
+  if (bucket.requests >= options.maxRequests) {
+    throw new PluginError(`Request limit exceeded. Max: ${options.maxRequests}`, pluginName, {
+      currentRequests: bucket.requests,
+      maxRequests: options.maxRequests,
+    });
+  }
+
+  if (bucket.cost + estimatedCost > options.maxCost) {
+    throw new PluginError(
+      `Cost limit exceeded. Current: $${bucket.cost.toFixed(COST_DECIMAL_PLACES)}, Estimated: $${estimatedCost.toFixed(COST_DECIMAL_PLACES)}, Max: $${options.maxCost}`,
+      pluginName,
+      { currentCost: bucket.cost, estimatedCost, maxCost: options.maxCost },
+    );
+  }
+
+  bucket.tokens -= estimatedTokens;
+  bucket.requests++;
+}
+
+/** Check and update sliding-window state. Throws PluginError if any limit is exceeded. @internal */
+export function checkSlidingWindow(
+  window: ILimitWindow,
+  now: number,
+  estimatedTokens: number,
+  estimatedCost: number,
+  options: {
+    timeWindow: number;
+    maxTokens: number;
+    maxRequests: number;
+    maxCost: number;
+  },
+  pluginName: string,
+): void {
+  if (now - window.windowStart < options.timeWindow) {
+    if (window.tokens + estimatedTokens > options.maxTokens) {
+      throw new PluginError(
+        `Token limit exceeded in sliding window. Current: ${window.tokens}, Estimated: ${estimatedTokens}, Max: ${options.maxTokens}`,
+        pluginName,
+        { currentTokens: window.tokens, estimatedTokens, maxTokens: options.maxTokens },
+      );
+    }
+    if (window.count >= options.maxRequests) {
+      throw new PluginError(
+        `Request limit exceeded in sliding window. Current: ${window.count}, Max: ${options.maxRequests}`,
+        pluginName,
+        { currentRequests: window.count, maxRequests: options.maxRequests },
+      );
+    }
+    if (window.cost + estimatedCost > options.maxCost) {
+      throw new PluginError(
+        `Cost limit exceeded in sliding window. Current: $${window.cost.toFixed(COST_DECIMAL_PLACES)}, Estimated: $${estimatedCost.toFixed(COST_DECIMAL_PLACES)}, Max: $${options.maxCost}`,
+        pluginName,
+        { currentCost: window.cost, estimatedCost, maxCost: options.maxCost },
+      );
+    }
+  } else {
+    window.count = 0;
+    window.tokens = 0;
+    window.cost = 0;
+    window.windowStart = now;
+  }
+  window.count++;
+}
+
+/** Check and update fixed-window state. Throws PluginError if any limit is exceeded. @internal */
+export function checkFixedWindow(
+  window: ILimitWindow,
+  now: number,
+  estimatedTokens: number,
+  estimatedCost: number,
+  options: {
+    timeWindow: number;
+    maxTokens: number;
+    maxRequests: number;
+    maxCost: number;
+  },
+  pluginName: string,
+): void {
+  if (now - window.windowStart >= options.timeWindow) {
+    window.count = 0;
+    window.tokens = 0;
+    window.cost = 0;
+    window.windowStart = now;
+  }
+
+  if (window.tokens + estimatedTokens > options.maxTokens) {
+    throw new PluginError(
+      `Token limit exceeded in fixed window. Current: ${window.tokens}, Estimated: ${estimatedTokens}, Max: ${options.maxTokens}`,
+      pluginName,
+      { currentTokens: window.tokens, estimatedTokens, maxTokens: options.maxTokens },
+    );
+  }
+  if (window.count >= options.maxRequests) {
+    throw new PluginError(
+      `Request limit exceeded in fixed window. Current: ${window.count}, Max: ${options.maxRequests}`,
+      pluginName,
+      { currentRequests: window.count, maxRequests: options.maxRequests },
+    );
+  }
+  if (window.cost + estimatedCost > options.maxCost) {
+    throw new PluginError(
+      `Cost limit exceeded in fixed window. Current: $${window.cost.toFixed(COST_DECIMAL_PLACES)}, Estimated: $${estimatedCost.toFixed(COST_DECIMAL_PLACES)}, Max: $${options.maxCost}`,
+      pluginName,
+      { currentCost: window.cost, estimatedCost, maxCost: options.maxCost },
+    );
+  }
+  window.count++;
+}

package/src/limits/limits-plugin.ts

@@ -0,0 +1,196 @@
+import {
+  AbstractPlugin,
+  type IPluginExecutionContext,
+  type IPluginExecutionResult,
+  PluginCategory,
+  PluginPriority,
+  createLogger,
+  type ILogger,
+  type TUniversalMessage,
+} from '@robota-sdk/agent-core';
+import type {
+  TLimitsStrategy,
+  ILimitsPluginOptions,
+  TPluginLimitsStatusData,
+  ILimitWindow,
+  ITokenBucket,
+} from './types';
+import { validateLimitsOptions } from './validation';
+import {
+  defaultCostCalculator,
+  estimateTokensFromMessages,
+  checkTokenBucket,
+  checkSlidingWindow,
+  checkFixedWindow,
+} from './limits-helpers';
+
+const DEFAULT_MAX_TOKENS = 100000;
+const DEFAULT_MAX_REQUESTS = 1000;
+const DEFAULT_TIME_WINDOW_MS = 3600000;
+const DEFAULT_MAX_COST = 10.0;
+const DEFAULT_TOKEN_COST_PER_1000 = 0.002;
+const DEFAULT_REFILL_RATE = 100;
+const DEFAULT_BUCKET_SIZE = 10000;
+
+export type { TLimitsStrategy, ILimitsPluginOptions, TPluginLimitsStatusData };
+
+export interface ILimitsPluginExecutionContext extends IPluginExecutionContext {
+  config?: { model?: string; maxTokens?: number; temperature?: number };
+  conversationId?: string;
+}
+
+export interface ILimitsPluginExecutionResult {
+  tokensUsed?: number;
+  cost?: number;
+  success?: boolean;
+  [key: string]: string | number | boolean | undefined;
+}
+
+/**
+ * Enforces rate limiting on token usage, request frequency, and cost.
+ * @extends AbstractPlugin
+ */
+export class LimitsPlugin extends AbstractPlugin<ILimitsPluginOptions> {
+  name = 'LimitsPlugin';
+  version = '1.0.0';
+  private pluginOptions: Required<ILimitsPluginOptions>;
+  private logger: ILogger;
+  private windows = new Map<string, ILimitWindow>();
+  private buckets = new Map<string, ITokenBucket>();
+
+  constructor(options: ILimitsPluginOptions) {
+    super();
+    this.logger = createLogger('LimitsPlugin');
+    validateLimitsOptions(options, this.name, this.logger);
+    this.pluginOptions = {
+      enabled: options.enabled ?? true,
+      strategy: options.strategy,
+      maxTokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
+      maxRequests: options.maxRequests ?? DEFAULT_MAX_REQUESTS,
+      timeWindow: options.timeWindow ?? DEFAULT_TIME_WINDOW_MS,
+      maxCost: options.maxCost ?? DEFAULT_MAX_COST,
+      tokenCostPer1000: options.tokenCostPer1000 ?? DEFAULT_TOKEN_COST_PER_1000,
+      refillRate: options.refillRate ?? DEFAULT_REFILL_RATE,
+      bucketSize: options.bucketSize ?? DEFAULT_BUCKET_SIZE,
+      costCalculator:
+        options.costCalculator ??
+        ((tokens: number, model: string) =>
+          defaultCostCalculator(tokens, model, this.pluginOptions.tokenCostPer1000)),
+      category: options.category ?? PluginCategory.LIMITS,
+      priority: options.priority ?? PluginPriority.NORMAL,
+      moduleEvents: options.moduleEvents ?? [],
+      subscribeToAllModuleEvents: options.subscribeToAllModuleEvents ?? false,
+    };
+  }
+
+  override async beforeExecution(context: IPluginExecutionContext): Promise<void> {
+    if (this.pluginOptions.strategy === 'none') return;
+    const key = this.getKey(context);
+    const now = Date.now();
+    const est = estimateTokensFromMessages(context.messages ?? []);
+    const estCost = this.pluginOptions.costCalculator(est, this.resolveModelName(context));
+
+    switch (this.pluginOptions.strategy) {
+      case 'token-bucket':
+        checkTokenBucket(this.getBucket(key), now, est, estCost, this.pluginOptions, this.name);
+        break;
+      case 'sliding-window':
+        checkSlidingWindow(this.getWindow(key), now, est, estCost, this.pluginOptions, this.name);
+        break;
+      case 'fixed-window':
+        checkFixedWindow(this.getWindow(key), now, est, estCost, this.pluginOptions, this.name);
+        break;
+    }
+  }
+
+  override async afterExecution(
+    context: IPluginExecutionContext,
+    result: IPluginExecutionResult,
+  ): Promise<void> {
+    if (this.pluginOptions.strategy === 'none') return;
+    const key = this.getKey(context);
+    const tokensUsed = result?.tokensUsed || 0;
+    const cost = this.pluginOptions.costCalculator(tokensUsed, this.resolveModelName(context));
+    switch (this.pluginOptions.strategy) {
+      case 'token-bucket':
+        this.getBucket(key).cost += cost;
+        break;
+      case 'sliding-window':
+      case 'fixed-window': {
+        const w = this.getWindow(key);
+        w.tokens += tokensUsed;
+        w.cost += cost;
+        break;
+      }
+    }
+  }
+
+  private getBucket(key: string): ITokenBucket {
+    if (!this.buckets.has(key))
+      this.buckets.set(key, {
+        tokens: this.pluginOptions.bucketSize,
+        lastRefill: Date.now(),
+        requests: 0,
+        cost: 0,
+        windowStart: Date.now(),
+      });
+    return this.buckets.get(key)!;
+  }
+
+  private getWindow(key: string): ILimitWindow {
+    if (!this.windows.has(key))
+      this.windows.set(key, { count: 0, tokens: 0, cost: 0, windowStart: Date.now() });
+    return this.windows.get(key)!;
+  }
+
+  private getKey(context: ILimitsPluginExecutionContext): string {
+    return context.userId || context.sessionId || context.executionId || 'default';
+  }
+
+  private resolveModelName(context: IPluginExecutionContext): string {
+    const m = context.config?.model;
+    return typeof m === 'string' && m.length > 0 ? m : 'unknown';
+  }
+
+  getLimitsStatus(key?: string): TPluginLimitsStatusData {
+    if (key) {
+      const bucket = this.buckets.get(key);
+      const window = this.windows.get(key);
+      return {
+        strategy: this.pluginOptions.strategy,
+        key,
+        bucket: bucket
+          ? {
+              availableTokens: Math.floor(bucket.tokens),
+              requests: bucket.requests,
+              cost: bucket.cost,
+            }
+          : null,
+        window: window
+          ? {
+              count: window.count,
+              tokens: window.tokens,
+              cost: window.cost,
+              windowStart: window.windowStart,
+            }
+          : null,
+      };
+    }
+    return {
+      strategy: this.pluginOptions.strategy,
+      totalKeys: this.buckets.size + this.windows.size,
+      bucketKeys: Array.from(this.buckets.keys()),
+      windowKeys: Array.from(this.windows.keys()),
+    };
+  }
+
+  resetLimits(key?: string): void {
+    if (key) {
+      this.buckets.delete(key);
+      this.windows.delete(key);
+    } else {
+      this.buckets.clear();
+      this.windows.clear();
+    }
+  }
+}

package/src/limits/types.ts

@@ -0,0 +1,73 @@
+import type { IPluginOptions } from '@robota-sdk/agent-core';
+
+/**
+ * Rate limiting strategies
+ */
+export type TLimitsStrategy = 'token-bucket' | 'sliding-window' | 'fixed-window' | 'none';
+
+/**
+ * Limits plugin configuration
+ */
+export interface ILimitsPluginOptions extends IPluginOptions {
+  /** Rate limiting strategy */
+  strategy: TLimitsStrategy;
+  /** Maximum tokens per time window */
+  maxTokens?: number;
+  /** Maximum requests per time window */
+  maxRequests?: number;
+  /** Time window in milliseconds */
+  timeWindow?: number;
+  /** Maximum cost per time window (in USD) */
+  maxCost?: number;
+  /** Token cost per 1000 tokens (in USD) */
+  tokenCostPer1000?: number;
+  /** Bucket refill rate for token bucket strategy */
+  refillRate?: number;
+  /** Initial bucket size for token bucket strategy */
+  bucketSize?: number;
+  /** Custom cost calculator */
+  costCalculator?: (tokens: number, model: string) => number;
+}
+
+/**
+ * Plugin limits status data type - supports nested objects and null values for comprehensive status reporting
+ *
+ * REASON: Status data needs to include nested objects for bucket/window details and null values for missing data
+ * ALTERNATIVES_CONSIDERED:
+ * 1. Strict primitive types (loses nested status information)
+ * 2. Union types without null (breaks null handling)
+ * 3. Interface definitions (too rigid for dynamic status)
+ * 4. Generic constraints (too complex for status data)
+ * 5. Type assertions (decreases type safety)
+ * TODO: Consider specific status interfaces if patterns emerge
+ */
+export type TPluginLimitsStatusData = Record<
+  string,
+  | string
+  | number
+  | boolean
+  | Array<string | number | boolean>
+  | Record<string, string | number | boolean>
+  | null
+>;
+
+/**
+ * Rate limiting window data
+ */
+export interface ILimitWindow {
+  count: number;
+  tokens: number;
+  cost: number;
+  windowStart: number;
+}
+
+/**
+ * Token bucket state
+ */
+export interface ITokenBucket {
+  tokens: number;
+  lastRefill: number;
+  requests: number;
+  cost: number;
+  windowStart: number;
+}

package/src/limits/validation.ts

@@ -0,0 +1,81 @@
+/**
+ * Validation logic for LimitsPlugin options.
+ *
+ * Extracted from limits-plugin.ts to keep each file under 300 lines.
+ * @internal
+ */
+import { PluginError, type ILogger } from '@robota-sdk/agent-core';
+import type { ILimitsPluginOptions } from './types';
+
+/** Validate LimitsPlugin options. @internal */
+export function validateLimitsOptions(
+  options: ILimitsPluginOptions,
+  pluginName: string,
+  logger: ILogger,
+): void {
+  if (options.strategy === 'none') {
+    logger.info('LimitsPlugin configured with "none" strategy - no rate limiting will be applied');
+    return;
+  }
+
+  if (!options.strategy) {
+    throw new PluginError(
+      'Strategy must be specified for limits plugin. Use "none" to disable rate limiting, or choose from: token-bucket, sliding-window, fixed-window',
+      pluginName,
+      { availableStrategies: ['none', 'token-bucket', 'sliding-window', 'fixed-window'] },
+    );
+  }
+
+  const validStrategies = ['none', 'token-bucket', 'sliding-window', 'fixed-window'];
+  if (!validStrategies.includes(options.strategy)) {
+    throw new PluginError(
+      `Invalid strategy "${options.strategy}". Must be one of: ${validStrategies.join(', ')}`,
+      pluginName,
+      { provided: options.strategy, validStrategies },
+    );
+  }
+
+  if (options.strategy === 'token-bucket') {
+    if (options.bucketSize !== undefined && options.bucketSize <= 0)
+      throw new PluginError('Bucket size must be positive for token-bucket strategy', pluginName, {
+        strategy: options.strategy,
+        bucketSize: options.bucketSize,
+      });
+    if (options.refillRate !== undefined && options.refillRate < 0)
+      throw new PluginError(
+        'Refill rate must be non-negative for token-bucket strategy',
+        pluginName,
+        { strategy: options.strategy, refillRate: options.refillRate },
+      );
+  }
+
+  if (['sliding-window', 'fixed-window'].includes(options.strategy)) {
+    if (options.timeWindow !== undefined && options.timeWindow <= 0)
+      throw new PluginError(
+        `Time window must be positive for ${options.strategy} strategy`,
+        pluginName,
+        { strategy: options.strategy, timeWindow: options.timeWindow },
+      );
+  }
+
+  if (options.maxRequests !== undefined && options.maxRequests < 0)
+    throw new PluginError('Max requests must be non-negative', pluginName, {
+      strategy: options.strategy,
+      maxRequests: options.maxRequests,
+    });
+  if (options.maxTokens !== undefined && options.maxTokens < 0)
+    throw new PluginError('Max tokens must be non-negative', pluginName, {
+      strategy: options.strategy,
+      maxTokens: options.maxTokens,
+    });
+  if (options.maxCost !== undefined && options.maxCost < 0)
+    throw new PluginError('Max cost must be non-negative', pluginName, {
+      strategy: options.strategy,
+      maxCost: options.maxCost,
+    });
+  if (options.tokenCostPer1000 !== undefined && options.tokenCostPer1000 < 0)
+    throw new PluginError('Token cost per 1000 must be non-negative', pluginName, {
+      strategy: options.strategy,
+      tokenCostPer1000: options.tokenCostPer1000,
+    });
+}

package/src/logging/__tests__/formatters.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import { ConsoleLogFormatter, JsonLogFormatter } from '../formatters';
+import type { ILogEntry } from '../types';
+
+const entry: ILogEntry = {
+  timestamp: new Date('2025-01-01T12:00:00Z'),
+  level: 'info',
+  message: 'Test message',
+  context: { module: 'test' },
+  metadata: { operation: 'value' },
+};
+
+describe('ConsoleLogFormatter', () => {
+  const formatter = new ConsoleLogFormatter();
+
+  it('formats entry with all fields', () => {
+    const result = formatter.format(entry);
+    expect(result).toContain('2025-01-01T12:00:00.000Z');
+    expect(result).toContain('INFO');
+    expect(result).toContain('Test message');
+    expect(result).toContain('"module":"test"');
+  });
+
+  it('formats entry without context', () => {
+    const noCtx: ILogEntry = { ...entry, context: undefined };
+    const result = formatter.format(noCtx);
+    expect(result).toContain('Test message');
+    expect(result).not.toContain('module');
+  });
+
+  it('formats entry without metadata', () => {
+    const noMeta: ILogEntry = { ...entry, metadata: undefined };
+    const result = formatter.format(noMeta);
+    expect(result).not.toContain('"operation"');
+  });
+});
+
+describe('JsonLogFormatter', () => {
+  const formatter = new JsonLogFormatter();
+
+  it('formats entry as JSON string', () => {
+    const result = formatter.format(entry);
+    const parsed = JSON.parse(result);
+    expect(parsed.message).toBe('Test message');
+    expect(parsed.level).toBe('info');
+    expect(parsed.timestamp).toBe('2025-01-01T12:00:00.000Z');
+  });
+});