legionio 1.4.14 → 1.4.29

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0927bca374a6df75ab9a1e75067219af7205291a694defff2fa356fe2b330bf3'
-  data.tar.gz: 1c3171e36c3447a104889d556df53596e611b4965d60abb08d4e91fe5c50a996
+  metadata.gz: b82509c414c56ab775cbaa5879a5312e9d3fd69226eadae308c52f5cba2bff25
+  data.tar.gz: c82590fb0283ee9db793c5b18751dbba8eb51c209351e2674a2ac542e875b718
 SHA512:
-  metadata.gz: 4bba3556ee1380f6b61aaa14263dbcccb4340428237f0203cbed9d7090d1cf95e811109b75ebf14e1a1bd3767640ad805e2dee4b4d5711352aa7becd528bf259
-  data.tar.gz: 243d79f20efa83d65b41a6e39f3953aee765369f37aa30caa6b85d16cb0baeab95e46628a443c45b082f233925c3ba413734c5e8aa45146c3827e9f367597ae7
+  metadata.gz: eff59d6453668b41bfa4047f77db11d02dc3fadacd59801d94fc1a7ec4af14598e30d817e0f075631b087a195e1715a68744a0e399fec728c0d426d8b3dc20e6
+  data.tar.gz: 10f935f6b10a6db5ef4df40e84a487b5fac01a10bc4789a3eca257aed77294a804309eccca224c70b5a3b082de5e0338408464a2dacb1fc353ef43fa54e128fd

data/.rubocop.yml

@@ -35,6 +35,7 @@ Metrics/BlockLength:
     - 'lib/legion/cli/swarm_command.rb'
     - 'lib/legion/cli/gaia_command.rb'
     - 'lib/legion/cli/schedule_command.rb'
+    - 'lib/legion/cli/update_command.rb'
 
 Metrics/AbcSize:
   Max: 60

data/CHANGELOG.md

@@ -1,9 +1,141 @@
 # Legion Changelog
 
+## [1.4.29] - 2026-03-16
+
+### Added
+- `legion init`: one-command workspace setup with environment detection
+- `InitHelpers::EnvironmentDetector`: checks for RabbitMQ, database, Vault, Redis, git, existing config
+- `InitHelpers::ConfigGenerator`: ERB template-based config generation, `.legion/` workspace scaffolding
+- `--local` flag for zero-dependency development mode
+- `--force` flag to overwrite existing config files
+
+## [1.4.28] - 2026-03-16
+
+### Added
+- `Legion::Telemetry` module: opt-in OpenTelemetry tracing with `with_span` wrapper
+- `setup_telemetry` in Service: initializes OTel SDK with OTLP exporter when `telemetry.enabled: true`
+- `sanitize_attributes` helper for safe OTel attribute conversion
+- `record_exception` helper for span error recording
+
+## [1.4.27] - 2026-03-16
+
+### Added
+- `legion update` CLI command: updates all Legion gems (`legionio`, `legion-*`, `lex-*`) using the current Ruby's gem binary
+- `--dry-run` flag to check available updates without installing
+- `--json` flag for machine-readable output
+- Updates install into the running Ruby's GEM_HOME (safe for Homebrew bundled installs)
+
+## [1.4.26] - 2026-03-16
+
+### Added
+- `Legion::Metrics` module: opt-in Prometheus metrics via `prometheus-client` gem
+- `GET /metrics` endpoint returning Prometheus text-format output
+- 9 metrics: uptime, active_workers, tasks_total, tasks_per_second, error_rate, consent_violations, llm_requests, llm_tokens
+- Event-driven counters + pull-based gauge refresh on scrape
+- `/metrics` added to Auth middleware SKIP_PATHS
+- Wired into Service startup and shutdown
+
+## [1.4.25] - 2026-03-16
+
+### Added
+- `Legion::Chat::NotificationQueue`: thread-safe priority queue for background notifications
+- `Legion::Chat::NotificationBridge`: event-driven bridge matching Legion events to chat notifications
+- Chat REPL displays pending notifications before each prompt (critical in red, info in yellow)
+- Configurable notification patterns via `chat.notifications.patterns` setting
+
+## [1.4.24] - 2026-03-16
+
+### Added
+- `Legion::Audit.recent_for` — query audit records by principal and time window
+- `Legion::Audit.count_for` — count audit records by principal and time window
+- `Legion::Audit.failure_count_for` / `success_count_for` — convenience wrappers
+- `Legion::Audit.resources_for` — distinct resources invoked by a principal
+- `Legion::Audit.recent` — most recent N records with optional filters
+- All query methods return safe defaults (`[]` or `0`) when legion-data is unavailable
+
+## [1.4.23] - 2026-03-16
+
+### Added
+- `Middleware::BodyLimit`: request body size limit (1MB max, returns 413)
+- `API::Validators` helper module: `validate_required!`, `validate_string_length!`, `validate_enum!`, `validate_uuid!`, `validate_integer!`
+- Ingress payload validation: 512KB size limit, runner_class/function format checks
+
+### Security
+- Ingress validates runner_class format before `Kernel.const_get` to prevent arbitrary constant resolution
+- Ingress validates function format before `.send` to prevent method injection
+
+## [1.4.22] - 2026-03-16
+
+### Added
+- `Legion::Alerts`: configurable alerting rules engine with event pattern matching
+- `Alerts::Engine`: count-based conditions, cooldown deduplication, multi-channel dispatch
+- 4 default rules: consent_violation, extinction_trigger, error_spike, budget_exceeded
+- Channel dispatch: events (via `Legion::Events`), log (via `Legion::Logging`), webhook
+- Settings: `alerts.enabled`, `alerts.rules`
+- Wired into `Service` startup (opt-in via `alerts.enabled: true`)
+
+## [1.4.21] - 2026-03-16
+
+### Added
+- `Middleware::ApiVersion`: rewrites `/api/v1/` paths to `/api/` for future versioned API support
+- Deprecation headers (`Deprecation`, `Sunset`, `Link`) on unversioned `/api/` paths
+- `X-API-Version` request header set for versioned paths
+- Skip paths: `/api/health`, `/api/ready`, `/api/openapi.json`, `/metrics`
+
+## [1.4.20] - 2026-03-16
+
+### Added
+- `Middleware::RateLimit`: sliding-window rate limiting with per-IP, per-agent, per-tenant tiers
+- In-memory store (default) with lazy reap; distributed store via `Legion::Cache` when available
+- Standard headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `Retry-After` (429 only)
+- Skip paths: `/api/health`, `/api/ready`, `/api/metrics`, `/api/openapi.json`
+
+## [1.4.19] - 2026-03-16
+
+### Added
+- Local development mode: `LEGION_LOCAL=true` env var or `local_mode: true` in settings
+- Auto-configures in-memory transport, mock Vault, and dev settings
+
+## [1.4.18] - 2026-03-16
+
+### Added
+- `legion config scaffold` auto-detects environment variables and enables providers
+- Detects: AWS_BEARER_TOKEN_BEDROCK, ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, VAULT_TOKEN, RABBITMQ_USER/PASSWORD
+- Detects running Ollama on localhost:11434
+- First detected LLM provider becomes the default; credentials use `env://` references
+- JSON output includes `detected` array for automation
+
+## [1.4.17] - 2026-03-16
+
+### Added
+- `Legion::Audit` publisher module for immutable audit logging via AMQP
+- Audit hook in `Runner.run` records every runner execution (event_type, duration, status)
+- Audit hook in `DigitalWorker::Lifecycle.transition!` records state transitions
+- `GET /api/audit` endpoint with filters (event_type, principal_id, source, status, since, until)
+- `GET /api/audit/verify` endpoint for hash chain integrity verification
+- `legion audit list` and `legion audit verify` CLI commands
+- Silent degradation: audit never interferes with normal operation (triple guard + rescue)
+
+## [1.4.16] - 2026-03-16
+
+### Added
+- `legion worker create NAME` CLI command: provisions digital worker in bootstrap state with DB record + optional Vault secret storage
+
+## [1.4.15] - 2026-03-16
+
+### Added
+- RAI invariant #2: Ingress.run calls Registry.validate_execution! when worker_id is present
+- Unregistered or inactive workers are blocked with structured error (no exception propagation)
+- Registration check fires before RBAC authorization (registration precedes permission)
+
 ## [1.4.14] - 2026-03-16
 
 ### Added
 - Optional RBAC integration via legion-rbac gem (`if defined?(Legion::Rbac)` guards)
+- `GET /api/workers/:id/health` endpoint returns worker health status with node metrics
+- `health_status` query filter on `GET /api/workers`
+- Thread-safe local worker tracking in `DigitalWorker::Registry` for heartbeat reporting
+- `Legion::DigitalWorker.active_local_ids` delegate method
 - `setup_rbac` lifecycle hook in Service (after setup_data)
 - `authorize_execution!` guard in Ingress for task execution
 - Rack middleware registration in API when legion-rbac loaded

data/CLAUDE.md

@@ -9,7 +9,7 @@ The primary gem for the LegionIO framework. An extensible async job engine for s
 
 **GitHub**: https://github.com/LegionIO/LegionIO
 **Gem**: `legionio`
-**Version**: 1.4.13
+**Version**: 1.4.29
 **License**: Apache-2.0
 **Docker**: `legionio/legion`
 **Ruby**: >= 3.4
@@ -274,6 +274,7 @@ legion
   worker
     list [-s status] [-t risk_tier]
     show <id>
+    create <name> --entra_app_id ID --owner_msid EMAIL --extension NAME [--team T] [--client_secret S]
     pause <id>
     activate <id>
     retire <id>
@@ -468,7 +469,17 @@ rack-test, rake, rspec, rubocop, rubocop-rspec, simplecov
 | `lib/legion/api/token.rb` | Token: JWT token issuance endpoint |
 | `lib/legion/api/openapi.rb` | OpenAPI: `Legion::API::OpenAPI.spec` / `.to_json`; also served at `GET /api/openapi.json` |
 | `lib/legion/api/oauth.rb` | OAuth: `GET /api/oauth/microsoft_teams/callback` — receives delegated OAuth redirect and stores tokens |
+| `lib/legion/audit.rb` | Audit logging: AMQP publish + query layer (recent_for, count_for, resources_for, recent) backed by AuditLog model |
+| `lib/legion/alerts.rb` | Configurable alerting rules engine: pattern matching, count conditions, cooldown dedup |
+| `lib/legion/telemetry.rb` | Opt-in OpenTelemetry tracing: `with_span` wrapper, `sanitize_attributes`, `record_exception` |
+| `lib/legion/metrics.rb` | Opt-in Prometheus metrics: event-driven counters, pull-based gauges, `prometheus-client` guarded |
+| `lib/legion/api/metrics.rb` | `GET /metrics` Prometheus text-format endpoint with gauge refresh |
+| `lib/legion/chat/notification_queue.rb` | Thread-safe priority queue for background notifications (critical/info/debug) |
+| `lib/legion/chat/notification_bridge.rb` | Event-driven bridge: matches Legion events to chat notifications via fnmatch patterns |
 | `lib/legion/api/middleware/auth.rb` | Auth: JWT Bearer auth middleware (real token validation, skip paths for health/ready) |
+| `lib/legion/api/middleware/api_version.rb` | ApiVersion: rewrites `/api/v1/` to `/api/`, adds Deprecation/Sunset headers on unversioned paths |
+| `lib/legion/api/middleware/body_limit.rb` | BodyLimit: request body size limit (1MB max, returns 413) |
+| `lib/legion/api/middleware/rate_limit.rb` | RateLimit: sliding-window rate limiting with per-IP/agent/tenant tiers |
 | **MCP** | |
 | `lib/legion/mcp.rb` | Entry point: `Legion::MCP.server` singleton factory |
 | `lib/legion/mcp/server.rb` | MCP::Server builder, TOOL_CLASSES array, instructions |
@@ -495,7 +506,7 @@ rack-test, rake, rspec, rubocop, rubocop-rspec, simplecov
 | `lib/legion/cli/config_scaffold.rb` | `legion config scaffold` — generates starter JSON config files per subsystem |
 | `lib/legion/cli/generate_command.rb` | `legion generate` subcommands (runner, actor, exchange, queue, message) |
 | `lib/legion/cli/mcp_command.rb` | `legion mcp` subcommand (stdio + HTTP transports) |
-| `lib/legion/cli/worker_command.rb` | `legion worker` subcommands (list, show, pause, retire, terminate, activate, costs) |
+| `lib/legion/cli/worker_command.rb` | `legion worker` subcommands (list, show, create, pause, retire, terminate, activate, costs) |
 | `lib/legion/cli/coldstart_command.rb` | `legion coldstart` subcommands (ingest, preview, status) |
 | `lib/legion/cli/chat_command.rb` | `legion chat` — interactive AI REPL + headless prompt mode |
 | `lib/legion/cli/chat/session.rb` | Chat session: multi-turn conversation, streaming, tool use |
@@ -566,7 +577,7 @@ rack-test, rake, rspec, rubocop, rubocop-rspec, simplecov
 
 ```bash
 bundle install
-bundle exec rspec       # 880 examples, 0 failures
+bundle exec rspec       # 997 examples, 0 failures
 bundle exec rubocop     # 0 offenses
 ```
 

data/README.md

@@ -176,6 +176,7 @@ AI-as-labor with governance, risk tiers, and cost tracking:
 ```bash
 legion worker list                  # list workers
 legion worker show <id>             # worker detail
+legion worker create <name>         # register new worker (bootstrap state)
 legion worker pause <id>            # pause / activate / retire
 legion worker costs --days 30       # cost report
 ```
@@ -205,9 +206,11 @@ legion schedule list
 ```bash
 legion config show              # resolved config (redacted)
 legion config validate          # verify settings + subsystem health
-legion config scaffold          # generate starter config files
+legion config scaffold          # generate starter config files (auto-detects env vars)
 ```
 
+`config scaffold` auto-detects environment variables (`ANTHROPIC_API_KEY`, `AWS_BEARER_TOKEN_BEDROCK`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `VAULT_TOKEN`, `RABBITMQ_USER`/`PASSWORD`) and a running Ollama instance, enabling providers and setting `env://` references automatically.
+
 Settings load from the first directory found: `/etc/legionio/` → `~/legionio/` → `./settings/`
 
 ### Diagnostics
@@ -220,6 +223,15 @@ legion doctor --json            # machine-readable output
 
 Checks Ruby version, bundle status, config files, RabbitMQ, database, cache, Vault, extensions, PID files, and permissions. Exits 1 if any check fails.
 
+### Updating
+
+```bash
+legion update                   # update all legion gems in-place
+legion update --dry-run         # check what's available without installing
+```
+
+Uses the same Ruby that `legion` is running from — safe for Homebrew installs (updates go into the bundled gem directory, not your system Ruby).
+
 All commands support `--json` for structured output and `--no-color` to strip ANSI codes.
 
 ## REST API

data/lib/legion/alerts.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Legion
+  module Alerts
+    AlertRule = Struct.new(:name, :event_pattern, :condition, :severity, :channels, :cooldown_seconds)
+
+    DEFAULT_RULES = [
+      { name: 'consent_violation', event_pattern: 'governance.consent_violation', severity: 'critical',
+        channels: %w[events log], cooldown_seconds: 300 },
+      { name: 'extinction_trigger', event_pattern: 'extinction.*', severity: 'critical',
+        channels: %w[events log], cooldown_seconds: 0 },
+      { name: 'error_spike', event_pattern: 'runner.failure',
+        condition: { count_threshold: 10, window_seconds: 60 }, severity: 'warning',
+        channels: %w[events log], cooldown_seconds: 300 },
+      { name: 'budget_exceeded', event_pattern: 'finops.budget_exceeded', severity: 'warning',
+        channels: %w[events log], cooldown_seconds: 3600 }
+    ].freeze
+
+    class Engine
+      attr_reader :rules
+
+      def initialize(rules: [])
+        @rules = rules.map { |r| r.is_a?(AlertRule) ? r : AlertRule.new(**r.transform_keys(&:to_sym)) }
+        @counters = {}
+        @last_fired = {}
+      end
+
+      def evaluate(event_name, payload = {})
+        fired = []
+        @rules.each do |rule|
+          next unless event_matches?(event_name, rule.event_pattern)
+          next unless condition_met?(rule, event_name)
+          next if in_cooldown?(rule)
+
+          fire_alert(rule, event_name, payload)
+          fired << rule.name
+        end
+        fired
+      end
+
+      private
+
+      def event_matches?(name, pattern)
+        File.fnmatch?(pattern, name)
+      end
+
+      def condition_met?(rule, event_name)
+        cond = rule.condition
+        return true unless cond.is_a?(Hash)
+
+        key = "#{rule.name}:#{event_name}"
+        @counters[key] ||= { count: 0, window_start: Time.now }
+
+        window = cond[:window_seconds] || 60
+        @counters[key] = { count: 0, window_start: Time.now } if Time.now - @counters[key][:window_start] > window
+
+        @counters[key][:count] += 1
+        @counters[key][:count] >= (cond[:count_threshold] || 1)
+      end
+
+      def in_cooldown?(rule)
+        last = @last_fired[rule.name]
+        return false unless last
+
+        Time.now - last < (rule.cooldown_seconds || 0)
+      end
+
+      def fire_alert(rule, event_name, payload)
+        @last_fired[rule.name] = Time.now
+        alert = { rule: rule.name, event: event_name, severity: rule.severity,
+                  payload: payload, fired_at: Time.now.utc }
+
+        (rule.channels || []).each do |channel|
+          case channel.to_sym
+          when :events
+            Legion::Events.emit('alert.fired', alert) if defined?(Legion::Events)
+          when :log
+            Legion::Logging.warn "[alert] #{rule.name}: #{event_name} (#{rule.severity})" if defined?(Legion::Logging)
+          when :webhook
+            Legion::Webhooks.dispatch('alert.fired', alert) if defined?(Legion::Webhooks)
+          end
+        end
+      end
+    end
+
+    class << self
+      def setup
+        rules = load_rules
+        @engine = Engine.new(rules: rules)
+        register_listener
+        Legion::Logging.debug "Alerts: #{rules.size} rules loaded" if defined?(Legion::Logging)
+      end
+
+      attr_reader :engine
+
+      def reset!
+        @engine = nil
+      end
+
+      private
+
+      def load_rules
+        custom = begin
+          Legion::Settings[:alerts][:rules]
+        rescue StandardError
+          nil
+        end
+        custom && !custom.empty? ? custom : DEFAULT_RULES
+      end
+
+      def register_listener
+        return unless defined?(Legion::Events)
+
+        Legion::Events.on('*') do |event_name, **payload|
+          @engine&.evaluate(event_name, payload)
+        end
+      end
+    end
+  end
+end

data/lib/legion/api/audit.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Legion
+  class API < Sinatra::Base
+    module Routes
+      module Audit
+        def self.registered(app)
+          app.get '/api/audit' do
+            require_data!
+            dataset = Legion::Data::Model::AuditLog.order(Sequel.desc(:id))
+            dataset = dataset.where(event_type: params[:event_type])     if params[:event_type]
+            dataset = dataset.where(principal_id: params[:principal_id]) if params[:principal_id]
+            dataset = dataset.where(source: params[:source])             if params[:source]
+            dataset = dataset.where(status: params[:status])             if params[:status]
+            dataset = dataset.where { created_at >= Time.parse(params[:since]) } if params[:since]
+            dataset = dataset.where { created_at <= Time.parse(params[:until]) } if params[:until]
+            json_collection(dataset)
+          end
+
+          app.get '/api/audit/verify' do
+            require_data!
+            halt 503, json_error('unavailable', 'lex-audit is not loaded', status_code: 503) unless defined?(Legion::Extensions::Audit::Runners::Audit)
+
+            runner = Object.new.extend(Legion::Extensions::Audit::Runners::Audit)
+            result = runner.verify
+            json_response(result)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/api/metrics.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Legion
+  class API < Sinatra::Base
+    module Routes
+      module Metrics
+        def self.registered(app)
+          app.get '/metrics' do
+            unless defined?(Legion::Metrics) && Legion::Metrics.available?
+              content_type 'text/plain'
+              halt 404, 'prometheus-client gem not available'
+            end
+
+            Legion::Metrics.refresh_gauges
+            content_type 'text/plain; version=0.0.4; charset=utf-8'
+            Legion::Metrics.render
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/api/middleware/api_version.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'sinatra/base'
+
+module Legion
+  class API < Sinatra::Base
+    module Middleware
+      class ApiVersion
+        SKIP_PATHS = %w[/api/health /api/ready /api/openapi.json /metrics].freeze
+
+        def initialize(app)
+          @app = app
+        end
+
+        def call(env)
+          path = env['PATH_INFO']
+
+          if path.start_with?('/api/v1/')
+            env['PATH_INFO'] = path.sub('/api/v1/', '/api/')
+            env['HTTP_X_API_VERSION'] = '1'
+            @app.call(env)
+          elsif path.start_with?('/api/') && !skip_path?(path)
+            status, headers, body = @app.call(env)
+            headers['Deprecation'] = 'true'
+            headers['Sunset'] = (Time.now + (180 * 86_400)).httpdate
+            successor = path.sub('/api/', '/api/v1/')
+            headers['Link'] = "<#{successor}>; rel=\"successor-version\""
+            [status, headers, body]
+          else
+            @app.call(env)
+          end
+        end
+
+        private
+
+        def skip_path?(path)
+          SKIP_PATHS.any? { |skip| path.start_with?(skip) }
+        end
+      end
+    end
+  end
+end

data/lib/legion/api/middleware/auth.rb

@@ -4,7 +4,7 @@ module Legion
   class API < Sinatra::Base
     module Middleware
       class Auth
-        SKIP_PATHS      = %w[/api/health /api/ready /api/openapi.json].freeze
+        SKIP_PATHS      = %w[/api/health /api/ready /api/openapi.json /metrics].freeze
         AUTH_HEADER     = 'HTTP_AUTHORIZATION'
         BEARER_PATTERN  = /\ABearer\s+(.+)\z/i
         API_KEY_HEADER  = 'HTTP_X_API_KEY'

data/lib/legion/api/middleware/body_limit.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'sinatra/base'
+
+module Legion
+  class API < Sinatra::Base
+    module Middleware
+      class BodyLimit
+        MAX_BODY_SIZE = 1_048_576 # 1MB
+
+        def initialize(app, max_size: MAX_BODY_SIZE)
+          @app = app
+          @max_size = max_size
+        end
+
+        def call(env)
+          content_length = env['CONTENT_LENGTH'].to_i
+          if content_length > @max_size
+            body = Legion::JSON.dump({
+                                       error: { code:    'payload_too_large',
+                                                message: "request body exceeds #{@max_size} bytes" },
+                                       meta:  { timestamp: Time.now.utc.iso8601 }
+                                     })
+            return [413, { 'content-type' => 'application/json' }, [body]]
+          end
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/legion/api/middleware/rate_limit.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'sinatra/base'
+require 'concurrent-ruby'
+
+module Legion
+  class API < Sinatra::Base
+    module Middleware
+      class RateLimit
+        SKIP_PATHS = %w[/api/health /api/ready /api/metrics /api/openapi.json].freeze
+        WINDOW_SIZE = 60
+
+        class MemoryStore
+          def initialize
+            @counters = Concurrent::Hash.new
+          end
+
+          def increment(key, window)
+            composite = "#{key}:#{window}"
+            @counters[composite] = (@counters[composite] || 0) + 1
+          end
+
+          def count(key, window)
+            @counters["#{key}:#{window}"] || 0
+          end
+
+          def reap!
+            cutoff = (Time.now.to_i / WINDOW_SIZE * WINDOW_SIZE) - (WINDOW_SIZE * 2)
+            @counters.each_key do |k|
+              window = k.split(':').last.to_i
+              @counters.delete(k) if window < cutoff
+            end
+          end
+        end
+
+        class CacheStore
+          def increment(key, window)
+            cache_key = "legion:ratelimit:#{key}:#{window}"
+            current = Legion::Cache.get(cache_key).to_i
+            Legion::Cache.set(cache_key, current + 1, ttl: 120)
+            current + 1
+          end
+
+          def count(key, window)
+            Legion::Cache.get("legion:ratelimit:#{key}:#{window}").to_i
+          end
+
+          def reap!; end
+        end
+
+        def initialize(app, **opts)
+          @app = app
+          @enabled = opts.fetch(:enabled, true)
+          @limits = {
+            per_ip:     opts.fetch(:per_ip, 60),
+            per_agent:  opts.fetch(:per_agent, 300),
+            per_tenant: opts.fetch(:per_tenant, 3000)
+          }
+          @store = select_store
+          @reap_counter = 0
+        end
+
+        def call(env)
+          return @app.call(env) unless @enabled
+          return @app.call(env) if skip_path?(env['PATH_INFO'])
+
+          result = check_limits(env)
+          if result[:limited]
+            rate_limit_response(result)
+          else
+            status, headers, body = @app.call(env)
+            [status, headers.merge(rate_limit_headers(result)), body]
+          end
+        rescue StandardError
+          @app.call(env)
+        end
+
+        private
+
+        def select_store
+          if defined?(Legion::Cache) && Legion::Cache.respond_to?(:connected?) && Legion::Cache.connected?
+            CacheStore.new
+          else
+            MemoryStore.new
+          end
+        end
+
+        def skip_path?(path)
+          SKIP_PATHS.any? { |p| path.start_with?(p) }
+        end
+
+        def current_window
+          Time.now.to_i / WINDOW_SIZE * WINDOW_SIZE
+        end
+
+        def check_limits(env)
+          window = current_window
+          reset_at = window + WINDOW_SIZE
+          most_restrictive = { limited: false, limit: 0, remaining: 0, reset: reset_at }
+
+          ip = env['REMOTE_ADDR'] || 'unknown'
+          ip_count = @store.increment("ip:#{ip}", window)
+          update_most_restrictive(most_restrictive, ip_count, @limits[:per_ip], reset_at)
+
+          worker_id = env['legion.worker_id']
+          if worker_id
+            agent_count = @store.increment("agent:#{worker_id}", window)
+            update_most_restrictive(most_restrictive, agent_count, @limits[:per_agent], reset_at)
+          end
+
+          owner_msid = env['legion.owner_msid']
+          if owner_msid
+            tenant_count = @store.increment("tenant:#{owner_msid}", window)
+            update_most_restrictive(most_restrictive, tenant_count, @limits[:per_tenant], reset_at)
+          end
+
+          lazy_reap!
+          most_restrictive
+        end
+
+        def update_most_restrictive(result, count, limit, reset_at)
+          remaining = [limit - count, 0].max
+          if count > limit
+            result[:limited] = true
+            result[:limit] = limit
+            result[:remaining] = 0
+            result[:reset] = reset_at
+          elsif result[:limit].zero? || remaining < result[:remaining]
+            result[:limit] = limit
+            result[:remaining] = remaining
+            result[:reset] = reset_at
+          end
+        end
+
+        def lazy_reap!
+          @reap_counter += 1
+          return unless @reap_counter >= 100
+
+          @reap_counter = 0
+          @store.reap!
+        end
+
+        def rate_limit_headers(result)
+          {
+            'X-RateLimit-Limit'     => result[:limit].to_s,
+            'X-RateLimit-Remaining' => result[:remaining].to_s,
+            'X-RateLimit-Reset'     => result[:reset].to_s
+          }
+        end
+
+        def rate_limit_response(result)
+          retry_after = [result[:reset] - Time.now.to_i, 1].max
+          body = Legion::JSON.dump({
+                                     error: { code:    'rate_limit_exceeded',
+                                              message: "Rate limit exceeded. Try again after #{retry_after} seconds." },
+                                     meta:  { timestamp: Time.now.utc.iso8601 }
+                                   })
+          headers = rate_limit_headers(result).merge(
+            'content-type' => 'application/json',
+            'Retry-After'  => retry_after.to_s
+          )
+          [429, headers, [body]]
+        end
+      end
+    end
+  end
+end