rateLimiting static method

ToolLifecycle rateLimiting({
  1. int maxToolCallsPerMinute = 120,
  2. void onLimitApproached(
    1. String warning
    )?,
  3. void onLimitExceeded(
    1. String error
    )?,
})

Rate limiting lifecycle hooks.

Tracks tool execution frequency and can throttle or warn when limits are approached.

Implementation

static ToolLifecycle rateLimiting({
  int maxToolCallsPerMinute = 120,
  void Function(String warning)? onLimitApproached,
  void Function(String error)? onLimitExceeded,
}) {
  final callTimestamps = <DateTime>[];

  return ToolLifecycle(
    onToolBeforeExecution: (event) async {
      final now = DateTime.now();
      final windowStart = now.subtract(const Duration(minutes: 1));
      callTimestamps.removeWhere((t) => t.isBefore(windowStart));

      final count = callTimestamps.length;

      if (count >= maxToolCallsPerMinute) {
        onLimitExceeded?.call(
          'Tool call rate limit exceeded: '
          '$count/$maxToolCallsPerMinute per minute. '
          'Tool "${event.toolName}" may be throttled.',
        );
      } else if (count >= (maxToolCallsPerMinute * 0.8).round()) {
        onLimitApproached?.call(
          'Approaching tool call rate limit: '
          '$count/$maxToolCallsPerMinute per minute.',
        );
      }

      callTimestamps.add(now);
      return null; // Do not modify input.
    },
  );
}