legionio 1.4.29 → 1.4.44

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b82509c414c56ab775cbaa5879a5312e9d3fd69226eadae308c52f5cba2bff25
-  data.tar.gz: c82590fb0283ee9db793c5b18751dbba8eb51c209351e2674a2ac542e875b718
+  metadata.gz: 16599e1c095434bfb65c5a5aa763cb821324e192f8e367cad1aff64fadec7e10
+  data.tar.gz: 2747877e468f15212ed3bbd19eaa287323d159a676a01e80e6b1ca11e0abed9b
 SHA512:
-  metadata.gz: eff59d6453668b41bfa4047f77db11d02dc3fadacd59801d94fc1a7ec4af14598e30d817e0f075631b087a195e1715a68744a0e399fec728c0d426d8b3dc20e6
-  data.tar.gz: 10f935f6b10a6db5ef4df40e84a487b5fac01a10bc4789a3eca257aed77294a804309eccca224c70b5a3b082de5e0338408464a2dacb1fc353ef43fa54e128fd
+  metadata.gz: e522c7f831673baa38cf887b1493e78e7133d930f3e857b82fefddbeeffbcc88877e4d741330a222e744170bd0e5876ec08deca5c8a00d8dc6cc520fbd0f54dc
+  data.tar.gz: 802b45c5a8d13d79f0c52ac872080a6fde0e5b64bc7ee0f46a21fbdb5be56c23ddad2f6b242b535b9a862e13b446735cb57c44ac50a9a0b021a728c620defe20

data/.rubocop.yml

@@ -36,6 +36,8 @@ Metrics/BlockLength:
     - 'lib/legion/cli/gaia_command.rb'
     - 'lib/legion/cli/schedule_command.rb'
     - 'lib/legion/cli/update_command.rb'
+    - 'lib/legion/api/auth.rb'
+    - 'lib/legion/api/auth_worker.rb'
 
 Metrics/AbcSize:
   Max: 60

data/CHANGELOG.md

@@ -1,5 +1,109 @@
 # Legion Changelog
 
+## [1.4.44] - 2026-03-17
+
+### Added
+- `POST /api/auth/worker-token`: Entra client credentials token exchange endpoint (validates client_credentials grant via JWKS, looks up worker by appid, issues scoped Legion worker JWT)
+- Auth middleware SKIP_PATHS now includes `/api/auth/token` and `/api/auth/worker-token`
+
+## [1.4.43] - 2026-03-17
+
+### Fixed
+- Auth token exchange route used `Legion::Settings.dig` which doesn't exist — replaced with bracket access
+- Auth spec required `legion/rbac` gem directly — replaced with inline stub for standalone test execution
+
+## [1.4.42] - 2026-03-17
+
+### Added
+- `POST /api/auth/token`: Entra ID token exchange endpoint (validates external JWT via JWKS, maps claims via EntraClaimsMapper, issues Legion token)
+
+## [1.4.41] - 2026-03-17
+
+### Added
+- `Legion::CLI::LexTemplates`: extension template registry (basic, llm-agent, service-integration, scheduled-task, webhook-handler)
+- `Legion::Docs::SiteGenerator`: documentation site generation from existing markdown files
+
+## [1.4.40] - 2026-03-17
+
+### Added
+- `Legion::Guardrails`: embedding similarity and RAG relevancy safety checks
+- `Legion::Context`: session/user tracking with thread-local `SessionContext`
+- `Legion::Catalog`: AI catalog registration for MCP tools and workers
+
+## [1.4.39] - 2026-03-17
+
+### Added
+- `Legion::Webhooks`: outbound webhook dispatcher with HMAC-SHA256 signing
+- Webhook registration, delivery tracking, and dead letter queue
+- API routes: `GET/POST/DELETE /api/webhooks`
+
+## [1.4.38] - 2026-03-17
+
+### Added
+- `Legion::Isolation`: per-agent data and tool access enforcement with thread-local context
+- `Isolation::Context`: tool allowlist, data filter, and risk tier per agent
+
+## [1.4.37] - 2026-03-17
+
+### Added
+- `POST /api/channels/teams/webhook`: Bot Framework activity delivery to GAIA sensory buffer
+
+## [1.4.36] - 2026-03-17
+
+### Added
+- `Audit::HashChain`: SHA-256 hash chain for tamper-evident audit records
+- `Audit::SiemExport`: SIEM-compatible JSON and NDJSON export with integrity metadata
+- `Audit::HashChain.verify_chain` validates hash chain between records
+
+## [1.4.35] - 2026-03-17
+
+### Added
+- `Chat::Team`: multi-user context tracking with thread-local user, env detection
+- `Chat::ProgressBar`: progress indicator for long-running operations with ETA
+- `legion notebook read/export`: Jupyter notebook reading and export (markdown/script)
+
+## [1.4.34] - 2026-03-17
+
+### Added
+- `Legion::Registry`: central extension metadata store with search, risk tier filtering, AIRB status
+- `Legion::Sandbox`: capability-based extension sandboxing with enforcement toggle
+- `Legion::Registry::SecurityScanner`: naming convention, checksum, and gemspec metadata validation
+- `legion marketplace`: CLI for search, info, list, scan operations
+
+## [1.4.33] - 2026-03-17
+
+### Added
+- `legion cost summary`: overall cost summary (today/week/month)
+- `legion cost worker <id>`: per-worker cost breakdown
+- `legion cost top`: top cost consumers ranked by spend
+- `legion cost export`: export cost data as JSON or CSV
+- `Legion::CLI::CostData::Client`: API client for cost data retrieval
+
+### Fixed
+- `Connection.resolve_config_dir` spec now correctly stubs `~/.legionio/settings` path
+
+## [1.4.32] - 2026-03-17
+
+### Fixed
+- `NotificationBridge` missing `require_relative 'notification_queue'` causing `NameError` on `legion chat`
+
+## [1.4.31] - 2026-03-16
+
+### Added
+- Skills system: `.legion/skills/` and `~/.legionio/skills/` YAML frontmatter markdown files
+- `Legion::Chat::Skills`: discovery, parsing, and find for skill files
+- `/skill-name` invocation in chat resolves user-defined skills
+- `legion skill list`, `legion skill show`, `legion skill create`, `legion skill run` CLI subcommands
+
+## [1.4.30] - 2026-03-16
+
+### Added
+- `MCP::Auth`: token-based MCP authentication (JWT + API key)
+- `MCP::ToolGovernance`: risk-tier-aware tool filtering and invocation audit
+- `MCP.server_for(token:)` builds identity-scoped MCP server instances
+- HTTP transport auth: Bearer token validation with 401 response on failure
+- MCP settings: `mcp.auth.enabled`, `mcp.auth.allowed_api_keys`, `mcp.governance.enabled`, `mcp.governance.tool_risk_tiers`
+
 ## [1.4.29] - 2026-03-16
 
 ### Added

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.29
+**Version**: 1.4.36
 **License**: Apache-2.0
 **Docker**: `legionio/legion`
 **Ruby**: >= 3.4
@@ -481,8 +481,10 @@ rack-test, rake, rspec, rubocop, rubocop-rspec, simplecov
 | `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 |
+| `lib/legion/mcp.rb` | Entry point: `Legion::MCP.server` singleton factory, `server_for(token:)` |
+| `lib/legion/mcp/auth.rb` | MCP authentication: JWT + API key verification |
+| `lib/legion/mcp/tool_governance.rb` | Risk-tier tool filtering and invocation audit |
+| `lib/legion/mcp/server.rb` | MCP::Server builder, TOOL_CLASSES array, governance-aware build |
 | `lib/legion/digital_worker.rb` | DigitalWorker module entry point |
 | `lib/legion/digital_worker/lifecycle.rb` | Worker state machine |
 | `lib/legion/digital_worker/registry.rb` | In-process worker registry |
@@ -564,6 +566,8 @@ rack-test, rake, rspec, rubocop, rubocop-rspec, simplecov
 | `API::Routes::Relationships` | Fully implemented (backed by legion-data migration 013) |
 | `API::Routes::Chains` | 501 stub - no data model |
 | `API::Middleware::Auth` | JWT Bearer auth middleware — real token validation and API key (`X-API-Key` header) auth both implemented |
+| `MCP::Auth` | JWT + API key authentication for MCP server (HTTP transport) |
+| `MCP::ToolGovernance` | Risk-tier tool filtering + audit — disabled by default, opt-in via settings |
 | `legion-data` chains/relationships models | Not yet implemented |
 
 ## Rubocop Notes
@@ -577,7 +581,7 @@ rack-test, rake, rspec, rubocop, rubocop-rspec, simplecov
 
 ```bash
 bundle install
-bundle exec rspec       # 997 examples, 0 failures
+bundle exec rspec       # 1088 examples, 0 failures
 bundle exec rubocop     # 0 offenses
 ```
 

data/lib/legion/api/auth.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Legion
+  class API < Sinatra::Base
+    module Routes
+      module Auth
+        def self.registered(app)
+          register_token_exchange(app)
+        end
+
+        def self.register_token_exchange(app) # rubocop:disable Metrics/MethodLength
+          app.post '/api/auth/token' do
+            body = parse_request_body
+            grant_type = body[:grant_type]
+            subject_token = body[:subject_token]
+
+            unless grant_type == 'urn:ietf:params:oauth:grant-type:token-exchange'
+              halt 400, json_error('unsupported_grant_type', 'expected urn:ietf:params:oauth:grant-type:token-exchange',
+                                   status_code: 400)
+            end
+
+            halt 400, json_error('missing_subject_token', 'subject_token is required', status_code: 400) unless subject_token
+
+            unless defined?(Legion::Crypt::JWT) && Legion::Crypt::JWT.respond_to?(:verify_with_jwks)
+              halt 501, json_error('jwks_validation_not_available', 'legion-crypt JWKS support not loaded',
+                                   status_code: 501)
+            end
+
+            rbac_settings = (Legion::Settings[:rbac].is_a?(Hash) && Legion::Settings[:rbac][:entra]) || {}
+            tenant_id = rbac_settings[:tenant_id]
+            halt 500, json_error('entra_tenant_not_configured', 'rbac.entra.tenant_id not set', status_code: 500) unless tenant_id
+
+            jwks_url = "https://login.microsoftonline.com/#{tenant_id}/discovery/v2.0/keys"
+            issuer = "https://login.microsoftonline.com/#{tenant_id}/v2.0"
+
+            begin
+              entra_claims = Legion::Crypt::JWT.verify_with_jwks(
+                subject_token, jwks_url: jwks_url, issuers: [issuer]
+              )
+            rescue Legion::Crypt::JWT::ExpiredTokenError
+              halt 401, json_error('token_expired', 'Entra token has expired', status_code: 401)
+            rescue Legion::Crypt::JWT::InvalidTokenError => e
+              halt 401, json_error('invalid_token', e.message, status_code: 401)
+            rescue Legion::Crypt::JWT::Error => e
+              halt 502, json_error('identity_provider_unavailable', e.message, status_code: 502)
+            end
+
+            unless defined?(Legion::Rbac::EntraClaimsMapper)
+              halt 501, json_error('claims_mapper_not_available', 'legion-rbac EntraClaimsMapper not loaded',
+                                   status_code: 501)
+            end
+
+            mapped = Legion::Rbac::EntraClaimsMapper.map_claims(
+              entra_claims,
+              role_map:     rbac_settings[:role_map] || Legion::Rbac::EntraClaimsMapper::DEFAULT_ROLE_MAP,
+              group_map:    rbac_settings[:group_map] || {},
+              default_role: rbac_settings[:default_role] || 'worker'
+            )
+
+            ttl = 28_800
+            token = Legion::API::Token.issue_human_token(
+              msid: mapped[:sub], name: mapped[:name],
+              roles: mapped[:roles], ttl: ttl
+            )
+
+            json_response({
+                            access_token: token,
+                            token_type:   'Bearer',
+                            expires_in:   ttl,
+                            roles:        mapped[:roles],
+                            team:         mapped[:team]
+                          })
+          end
+        end
+
+        class << self
+          private :register_token_exchange
+        end
+      end
+    end
+  end
+end

data/lib/legion/api/auth_worker.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Legion
+  class API < Sinatra::Base
+    module Routes
+      module AuthWorker
+        def self.registered(app)
+          register_worker_token_exchange(app)
+        end
+
+        def self.register_worker_token_exchange(app) # rubocop:disable Metrics/MethodLength
+          app.post '/api/auth/worker-token' do
+            body = parse_request_body
+            grant_type = body[:grant_type]
+            entra_token = body[:entra_token]
+
+            unless grant_type == 'client_credentials'
+              halt 400, json_error('unsupported_grant_type', 'grant_type must be client_credentials',
+                                   status_code: 400)
+            end
+
+            halt 400, json_error('missing_entra_token', 'entra_token is required', status_code: 400) unless entra_token
+
+            unless defined?(Legion::Crypt::JWT) && Legion::Crypt::JWT.respond_to?(:verify_with_jwks)
+              halt 501, json_error('jwks_validation_not_available',
+                                   'JWKS validation is not available', status_code: 501)
+            end
+
+            entra_settings = Routes::AuthWorker.resolve_entra_settings
+            tenant_id = entra_settings[:tenant_id]
+            unless tenant_id
+              halt 500, json_error('entra_tenant_not_configured',
+                                   'Entra tenant_id is not configured', status_code: 500)
+            end
+
+            jwks_url = "https://login.microsoftonline.com/#{tenant_id}/discovery/v2.0/keys"
+            issuer = "https://login.microsoftonline.com/#{tenant_id}/v2.0"
+
+            begin
+              claims = Legion::Crypt::JWT.verify_with_jwks(
+                entra_token, jwks_url: jwks_url, issuers: [issuer]
+              )
+            rescue Legion::Crypt::JWT::ExpiredTokenError
+              halt 401, json_error('token_expired', 'Entra token has expired', status_code: 401)
+            rescue Legion::Crypt::JWT::InvalidTokenError => e
+              halt 401, json_error('invalid_token', e.message, status_code: 401)
+            rescue Legion::Crypt::JWT::Error => e
+              halt 502, json_error('identity_provider_unavailable', e.message, status_code: 502)
+            end
+
+            app_id = claims[:appid] || claims[:azp] || claims['appid'] || claims['azp']
+            halt 401, json_error('invalid_token', 'missing appid claim', status_code: 401) unless app_id
+
+            halt 503, json_error('data_unavailable', 'legion-data not connected', status_code: 503) unless defined?(Legion::Data::Model::DigitalWorker)
+
+            worker = Legion::Data::Model::DigitalWorker.first(entra_app_id: app_id)
+            unless worker
+              halt 404, json_error('worker_not_found',
+                                   "no worker registered for entra_app_id #{app_id}", status_code: 404)
+            end
+
+            unless worker.lifecycle_state == 'active'
+              halt 403, json_error('worker_not_active',
+                                   "worker is in #{worker.lifecycle_state} state", status_code: 403)
+            end
+
+            ttl = 3600
+            token = Legion::API::Token.issue_worker_token(
+              worker_id: worker.worker_id, owner_msid: worker.owner_msid, ttl: ttl
+            )
+
+            json_response({
+                            access_token: token,
+                            token_type:   'Bearer',
+                            expires_in:   ttl,
+                            worker_id:    worker.worker_id,
+                            scope:        'worker'
+                          })
+          end
+        end
+
+        def self.resolve_entra_settings
+          return {} unless defined?(Legion::Settings)
+
+          identity = Legion::Settings[:identity]
+          entra = identity.is_a?(Hash) ? identity[:entra] : nil
+          return entra if entra.is_a?(Hash)
+
+          rbac = Legion::Settings[:rbac]
+          entra = rbac.is_a?(Hash) ? rbac[:entra] : nil
+          return entra if entra.is_a?(Hash)
+
+          {}
+        rescue StandardError
+          {}
+        end
+
+        class << self
+          private :register_worker_token_exchange
+        end
+      end
+    end
+  end
+end

data/lib/legion/api/gaia.rb

@@ -12,6 +12,28 @@ module Legion
               json_response({ started: false }, status_code: 503)
             end
           end
+
+          app.post '/api/channels/teams/webhook' do
+            body = request.body.read
+            activity = Legion::JSON.load(body)
+
+            adapter = Routes::Gaia.teams_adapter
+            halt 503, json_response({ error: 'teams adapter not available' }, status_code: 503) unless adapter
+
+            input_frame = adapter.translate_inbound(activity)
+            Legion::Gaia.sensory_buffer&.push(input_frame) if defined?(Legion::Gaia)
+
+            json_response({ status: 'accepted', frame_id: input_frame&.id })
+          end
+        end
+
+        def self.teams_adapter
+          return nil unless defined?(Legion::Gaia) && Legion::Gaia.respond_to?(:channel_registry)
+          return nil unless Legion::Gaia.channel_registry
+
+          Legion::Gaia.channel_registry.adapter_for(:teams)
+        rescue StandardError
+          nil
         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 /metrics].freeze
+        SKIP_PATHS      = %w[/api/health /api/ready /api/openapi.json /metrics /api/auth/token /api/auth/worker-token].freeze
         AUTH_HEADER     = 'HTTP_AUTHORIZATION'
         BEARER_PATTERN  = /\ABearer\s+(.+)\z/i
         API_KEY_HEADER  = 'HTTP_X_API_KEY'

data/lib/legion/api/webhooks.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Legion
+  class API < Sinatra::Base
+    module Routes
+      module Webhooks
+        def self.registered(app)
+          app.get '/api/webhooks' do
+            json_response(Legion::Webhooks.list)
+          end
+
+          app.post '/api/webhooks' do
+            body = parse_request_body
+            result = Legion::Webhooks.register(
+              url: body[:url], secret: body[:secret],
+              event_types: body[:event_types] || ['*'],
+              max_retries: body[:max_retries] || 5
+            )
+            json_response(result, status_code: 201)
+          end
+
+          app.delete '/api/webhooks/:id' do
+            json_response(Legion::Webhooks.unregister(id: params[:id].to_i))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/api.rb

@@ -26,6 +26,8 @@ require_relative 'api/gaia'
 require_relative 'api/oauth'
 require_relative 'api/openapi'
 require_relative 'api/rbac'
+require_relative 'api/auth'
+require_relative 'api/auth_worker'
 require_relative 'api/audit'
 require_relative 'api/metrics'
 
@@ -96,6 +98,8 @@ module Legion
     register Routes::Gaia
     register Routes::OAuth
     register Routes::Rbac
+    register Routes::Auth
+    register Routes::AuthWorker
     register Routes::Audit
     register Routes::Metrics
 

data/lib/legion/audit/hash_chain.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module Legion
+  module Audit
+    module HashChain
+      ALGORITHM = 'SHA256'
+      GENESIS_HASH = ('0' * 64).freeze
+      CANONICAL_FIELDS = %i[principal_id action resource source status detail created_at previous_hash].freeze
+
+      module_function
+
+      def compute_hash(record)
+        payload = canonical_payload(record)
+        OpenSSL::Digest.new(ALGORITHM).hexdigest(payload)
+      end
+
+      def canonical_payload(record)
+        CANONICAL_FIELDS.map { |f| "#{f}:#{record[f]}" }.join('|')
+      end
+
+      def verify_chain(records)
+        broken = []
+        records.each_cons(2) do |prev, curr|
+          broken << { id: curr[:id], expected: prev[:record_hash], got: curr[:previous_hash] } unless curr[:previous_hash] == prev[:record_hash]
+        end
+        { valid: broken.empty?, broken_links: broken, records_checked: records.size }
+      end
+    end
+  end
+end

data/lib/legion/audit/siem_export.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Legion
+  module Audit
+    module SiemExport
+      module_function
+
+      def export_batch(records)
+        records.map do |r|
+          {
+            timestamp:  r[:created_at],
+            source:     'legion',
+            event_type: r[:event_type] || 'audit',
+            principal:  r[:principal_id],
+            action:     r[:action],
+            resource:   r[:resource],
+            status:     r[:status],
+            detail:     r[:detail],
+            integrity:  {
+              record_hash:   r[:record_hash],
+              previous_hash: r[:previous_hash],
+              algorithm:     'SHA256'
+            }
+          }
+        end
+      end
+
+      def to_ndjson(records)
+        export_batch(records).map { |r| Legion::JSON.dump(r) }.join("\n")
+      end
+    end
+  end
+end

data/lib/legion/catalog.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+
+module Legion
+  module Catalog
+    class << self
+      def register_tools(catalog_url:, api_key:)
+        tools = collect_mcp_tools
+        post_json("#{catalog_url}/api/tools", { tools: tools }, api_key)
+      end
+
+      def register_workers(catalog_url:, api_key:, workers:)
+        entries = workers.map do |w|
+          { id: w[:worker_id], status: w[:status], capabilities: w[:capabilities] || [] }
+        end
+        post_json("#{catalog_url}/api/workers", { workers: entries }, api_key)
+      end
+
+      def collect_mcp_tools
+        return [] unless defined?(Legion::MCP) && Legion::MCP.respond_to?(:tools)
+
+        Legion::MCP.tools.map { |t| { name: t[:name], description: t[:description] } }
+      rescue StandardError
+        []
+      end
+
+      private
+
+      def post_json(url, body, api_key)
+        uri = URI(url)
+        req = Net::HTTP::Post.new(uri)
+        req['Authorization'] = "Bearer #{api_key}"
+        req['Content-Type'] = 'application/json'
+        req.body = Legion::JSON.dump(body)
+
+        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
+          http.request(req)
+        end
+        { status: response.code.to_i, body: response.body }
+      rescue StandardError => e
+        { error: e.message }
+      end
+    end
+  end
+end

data/lib/legion/chat/notification_bridge.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'notification_queue'
+
 module Legion
   module Chat
     class NotificationBridge

data/lib/legion/chat/skills.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Legion
+  module Chat
+    module Skills
+      SKILL_DIRS = ['.legion/skills', '~/.legionio/skills'].freeze
+
+      class << self
+        def discover
+          SKILL_DIRS.flat_map do |dir|
+            expanded = File.expand_path(dir)
+            next [] unless Dir.exist?(expanded)
+
+            Dir.glob(File.join(expanded, '*.md')).filter_map { |f| parse(f) }
+          end
+        end
+
+        def find(name)
+          discover.find { |s| s[:name] == name.to_s }
+        end
+
+        def parse(path)
+          content = File.read(path)
+          return nil unless content.start_with?('---')
+
+          parts = content.split(/^---\s*$/, 3)
+          return nil if parts.size < 3
+
+          frontmatter = YAML.safe_load(parts[1], permitted_classes: [Symbol])
+          body = parts[2]&.strip
+
+          {
+            name:        frontmatter['name'] || File.basename(path, '.md'),
+            description: frontmatter['description'] || '',
+            model:       frontmatter['model'],
+            tools:       Array(frontmatter['tools']),
+            prompt:      body,
+            path:        path
+          }
+        rescue StandardError => e
+          Legion::Logging.warn "Skill parse error #{path}: #{e.message}" if defined?(Legion::Logging)
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/legion/cli/chat/progress_bar.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Legion
+  module CLI
+    class Chat
+      class ProgressBar
+        attr_reader :total, :current
+
+        def initialize(total:, label: '', width: 40, output: $stdout)
+          @total = [total, 1].max
+          @current = 0
+          @label = label
+          @width = width
+          @output = output
+          @start_time = Time.now
+        end
+
+        def advance(amount = 1)
+          @current = [@current + amount, @total].min
+          render
+          self
+        end
+
+        def finish
+          @current = @total
+          render
+          @output.puts
+          self
+        end
+
+        def percentage
+          (@current.to_f / @total * 100).round(1)
+        end
+
+        def elapsed
+          Time.now - @start_time
+        end
+
+        def eta
+          return 0 if @current.zero? || @current >= @total
+
+          (elapsed / @current * (@total - @current)).round
+        end
+
+        private
+
+        def render
+          filled = (@width * @current.to_f / @total).round
+          bar = ('#' * filled) + ('-' * [(@width - filled), 0].max)
+          @output.print "\r#{@label} [#{bar}] #{percentage}% (#{@current}/#{@total}) ETA: #{eta}s  "
+        end
+      end
+    end
+  end
+end