legionio 1.4.119 → 1.4.122

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac22c22ec64e117b1568d5569a2983e46fdc9aadb566642c05c35973fb29428a
-  data.tar.gz: e6b5a99eebc5b0de37a59ad9cebc4fd5e96b8fb125b1974faa64e2454e268907
+  metadata.gz: 102a045825ff17747b2724547e3704b958c55b51e77ce846d4dd8146460e8dbb
+  data.tar.gz: eccf79a4549c7f5bc949c2dc7141dd9b5ff794c85483d6cc414c790b7c867c06
 SHA512:
-  metadata.gz: 789c1485afd78d006d6d9aad725e483c5b6fd467a952476a11e1db29ac8c710f9d80c7e8dce4ac0045627abc45defae5ae45ebe995d167b95ffa866897ae4979
-  data.tar.gz: 852f58359d4cb4beb1a1708f6d01f9423dc2d18e0d9f028493f2f018eaa5f999b87c564b8015d39004f08ff70e43e41ff92bfcb075fc28b8608281c702704fd8
+  metadata.gz: fb2d2613bfd4e539755cf225e5917ff8aec939840f1435c1308c71ecc862617e31e516876ca6dd513dfe5496106296af1421ae9e3b9431871a99594cdbab5d19
+  data.tar.gz: 383b632d9dbb961d01895b273b19ead0a1742d56dae85a6090a371aec4a995b065b226c5db1768454cbab95db947fd5eea3443fe89979a529fcdb06bf4d6af56

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Legion Changelog
 
+## [1.4.122] - 2026-03-22
+
+### Added
+- GraphQL API via `graphql-ruby` gem: `POST /api/graphql` endpoint alongside existing REST API
+- Schema types: QueryType, WorkerType, TaskType, ExtensionType, TeamType with field-level resolvers
+- Resolver modules for workers, tasks, extensions, and teams (safe stubs with `defined?` guards)
+- 45 new specs for GraphQL schema, queries, and error handling
+
+## [1.4.121] - 2026-03-22
+
+### Added
+- Route `/api/llm/chat` through full Legion pipeline (Ingress -> RBAC -> Events -> Task -> Gateway metering -> LLM) when `lex-llm-gateway` is loaded
+- `gateway_available?` helper to detect gateway runner presence
+- Proper result extraction from `ingress_result[:result]` with support for RubyLLM response objects, error hashes, and plain strings
+- Error logging in async LLM rescue block (previously silent)
+
+## [1.4.120] - 2026-03-22
+
+### Added
+- Comprehensive logging throughout the framework: 55 files, 443 lines of `.info`, `.warn`, `.error`, `.debug` calls
+- API routes: every non-2xx response logs at warn (4xx) or error (5xx), every mutation logs at info, debug for request entry
+- Core framework: ingress, runner, extensions, actors, service lifecycle, readiness, events all log state transitions
+- Extension system: autobuild, actor hooking, transport setup, builder phases all log at debug/info
+- Digital worker lifecycle, capacity model, catalog, guardrails, webhooks, alerts, audit, telemetry all instrumented
+- CLI error handler logs matched patterns (warn) and unhandled errors (error)
+
 ## [1.4.119] - 2026-03-22
 
 ### Added

data/legionio.gemspec

@@ -42,6 +42,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'concurrent-ruby', '>= 1.2'
   spec.add_dependency 'concurrent-ruby-ext', '>= 1.2'
   spec.add_dependency 'daemons', '>= 1.4'
+  spec.add_dependency 'graphql', '>= 2.0'
   spec.add_dependency 'oj', '>= 3.16'
   spec.add_dependency 'puma', '>= 6.0'
   spec.add_dependency 'rackup', '>= 2.0'

data/lib/legion/alerts.rb

@@ -40,6 +40,8 @@ module Legion
         fired = []
         @rules.each do |rule|
           next unless event_matches?(event_name, rule.event_pattern)
+
+          Legion::Logging.debug "[Alerts] evaluating rule=#{rule.name} for event=#{event_name}" if defined?(Legion::Logging)
           next unless condition_met?(rule, event_name)
           next if in_cooldown?(rule)
 
@@ -81,12 +83,14 @@ module Legion
         alert = { rule: rule.name, event: event_name, severity: rule.severity,
                   payload: payload, fired_at: Time.now.utc }
 
+        Legion::Logging.info "[Alerts] alert fired: rule=#{rule.name} event=#{event_name} severity=#{rule.severity}" if defined?(Legion::Logging)
+
         (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)
+            Legion::Logging.warn "[Alerts] #{rule.name}: #{event_name} (#{rule.severity})" if defined?(Legion::Logging)
           when :webhook
             Legion::Webhooks.dispatch('alert.fired', alert) if defined?(Legion::Webhooks)
           end

data/lib/legion/api/audit.rb

@@ -4,7 +4,7 @@ module Legion
   class API < Sinatra::Base
     module Routes
       module Audit
-        def self.registered(app)
+        def self.registered(app) # rubocop:disable Metrics/AbcSize
           app.get '/api/audit' do
             require_data!
             dataset = Legion::Data::Model::AuditLog.order(Sequel.desc(:id))
@@ -15,15 +15,24 @@ module Legion
             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)
+          rescue StandardError => e
+            Legion::Logging.error "API GET /api/audit: #{e.class} — #{e.message}"
+            json_error('audit_error', e.message, status_code: 500)
           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)
+            unless defined?(Legion::Extensions::Audit::Runners::Audit)
+              Legion::Logging.warn 'API GET /api/audit/verify returned 503: lex-audit is not loaded'
+              halt 503, json_error('unavailable', 'lex-audit is not loaded', status_code: 503)
+            end
 
             runner = Object.new.extend(Legion::Extensions::Audit::Runners::Audit)
             result = runner.verify
             json_response(result)
+          rescue StandardError => e
+            Legion::Logging.error "API GET /api/audit/verify: #{e.class} — #{e.message}"
+            json_error('audit_error', e.message, status_code: 500)
           end
         end
       end

data/lib/legion/api/auth.rb

@@ -10,16 +10,21 @@ module Legion
 
         def self.register_token_exchange(app) # rubocop:disable Metrics/MethodLength
           app.post '/api/auth/token' do
+            Legion::Logging.debug "API: POST /api/auth/token params=#{params.keys}"
             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'
+              Legion::Logging.warn "API POST /api/auth/token returned 400: unsupported grant_type=#{grant_type}"
               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 subject_token
+              Legion::Logging.warn 'API POST /api/auth/token returned 400: subject_token is required'
+              halt 400, json_error('missing_subject_token', 'subject_token is required', status_code: 400)
+            end
 
             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',
@@ -28,7 +33,10 @@ module Legion
 
             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
+            unless tenant_id
+              Legion::Logging.error 'API POST /api/auth/token returned 500: rbac.entra.tenant_id not set'
+              halt 500, json_error('entra_tenant_not_configured', 'rbac.entra.tenant_id not set', 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"
@@ -38,10 +46,13 @@ module Legion
                 subject_token, jwks_url: jwks_url, issuers: [issuer]
               )
             rescue Legion::Crypt::JWT::ExpiredTokenError
+              Legion::Logging.warn 'API POST /api/auth/token returned 401: Entra token has expired'
               halt 401, json_error('token_expired', 'Entra token has expired', status_code: 401)
             rescue Legion::Crypt::JWT::InvalidTokenError => e
+              Legion::Logging.warn "API POST /api/auth/token returned 401: #{e.message}"
               halt 401, json_error('invalid_token', e.message, status_code: 401)
             rescue Legion::Crypt::JWT::Error => e
+              Legion::Logging.error "API POST /api/auth/token returned 502: #{e.message}"
               halt 502, json_error('identity_provider_unavailable', e.message, status_code: 502)
             end
 
@@ -63,6 +74,7 @@ module Legion
               roles: mapped[:roles], ttl: ttl
             )
 
+            Legion::Logging.info "API: issued human token for sub=#{mapped[:sub]} roles=#{mapped[:roles]&.join(',')}"
             json_response({
                             access_token: token,
                             token_type:   'Bearer',

data/lib/legion/api/auth_human.rb

@@ -44,7 +44,10 @@ module Legion
         def self.register_authorize(app)
           app.get '/api/auth/authorize' do
             entra = Routes::AuthHuman.resolve_entra_settings
-            halt 500, json_error('entra_not_configured', 'Entra OAuth settings are missing', status_code: 500) unless entra[:tenant_id] && entra[:client_id]
+            unless entra[:tenant_id] && entra[:client_id]
+              Legion::Logging.error 'API GET /api/auth/authorize returned 500: Entra OAuth settings are missing'
+              halt 500, json_error('entra_not_configured', 'Entra OAuth settings are missing', status_code: 500)
+            end
 
             state = Legion::Crypt::JWT.issue(
               { nonce: SecureRandom.hex(16), purpose: 'oauth_state' },
@@ -63,27 +66,43 @@ module Legion
           end
         end
 
-        def self.register_callback(app) # rubocop:disable Metrics/AbcSize
+        def self.register_callback(app) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
           app.get '/api/auth/callback' do
             entra = Routes::AuthHuman.resolve_entra_settings
-            halt 500, json_error('entra_not_configured', 'Entra OAuth settings are missing', status_code: 500) unless entra[:tenant_id] && entra[:client_id]
+            unless entra[:tenant_id] && entra[:client_id]
+              Legion::Logging.error 'API GET /api/auth/callback returned 500: Entra OAuth settings are missing'
+              halt 500, json_error('entra_not_configured', 'Entra OAuth settings are missing', status_code: 500)
+            end
 
-            halt 400, json_error('oauth_error', params[:error_description] || params[:error], status_code: 400) if params[:error]
-            halt 400, json_error('missing_code', 'authorization code is required', status_code: 400) unless params[:code]
+            if params[:error]
+              Legion::Logging.warn "API GET /api/auth/callback returned 400: #{params[:error_description] || params[:error]}"
+              halt 400, json_error('oauth_error', params[:error_description] || params[:error], status_code: 400)
+            end
+            unless params[:code]
+              Legion::Logging.warn 'API GET /api/auth/callback returned 400: authorization code is required'
+              halt 400, json_error('missing_code', 'authorization code is required', status_code: 400)
+            end
 
             if params[:state]
               begin
                 Legion::Crypt::JWT.verify(params[:state])
               rescue Legion::Crypt::JWT::Error
+                Legion::Logging.warn 'API GET /api/auth/callback returned 400: CSRF state token is invalid or expired'
                 halt 400, json_error('invalid_state', 'CSRF state token is invalid or expired', status_code: 400)
               end
             end
 
             token_response = Routes::AuthHuman.exchange_code(entra, params[:code])
-            halt 502, json_error('token_exchange_failed', 'Failed to exchange code for tokens', status_code: 502) unless token_response
+            unless token_response
+              Legion::Logging.error 'API GET /api/auth/callback returned 502: Failed to exchange code for tokens'
+              halt 502, json_error('token_exchange_failed', 'Failed to exchange code for tokens', status_code: 502)
+            end
 
             id_token = token_response[:id_token] || token_response['id_token']
-            halt 502, json_error('no_id_token', 'Entra did not return an id_token', status_code: 502) unless id_token
+            unless id_token
+              Legion::Logging.error 'API GET /api/auth/callback returned 502: Entra did not return an id_token'
+              halt 502, json_error('no_id_token', 'Entra did not return an id_token', status_code: 502)
+            end
 
             jwks_url = "https://login.microsoftonline.com/#{entra[:tenant_id]}/discovery/v2.0/keys"
             issuer = "https://login.microsoftonline.com/#{entra[:tenant_id]}/v2.0"
@@ -91,6 +110,7 @@ module Legion
             begin
               claims = Legion::Crypt::JWT.verify_with_jwks(id_token, jwks_url: jwks_url, issuers: [issuer])
             rescue Legion::Crypt::JWT::Error => e
+              Legion::Logging.warn "API GET /api/auth/callback returned 401: #{e.message}"
               halt 401, json_error('invalid_id_token', e.message, status_code: 401)
             end
 
@@ -110,6 +130,7 @@ module Legion
               msid: mapped[:sub], name: mapped[:name], roles: mapped[:roles], ttl: ttl
             )
 
+            Legion::Logging.info "API: human OAuth callback issued token for sub=#{mapped[:sub]}"
             if request.env['HTTP_ACCEPT']&.include?('application/json')
               json_response({
                               access_token: token,

data/lib/legion/api/auth_worker.rb

@@ -8,18 +8,23 @@ module Legion
           register_worker_token_exchange(app)
         end
 
-        def self.register_worker_token_exchange(app) # rubocop:disable Metrics/MethodLength
+        def self.register_worker_token_exchange(app) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
           app.post '/api/auth/worker-token' do
+            Legion::Logging.debug "API: POST /api/auth/worker-token params=#{params.keys}"
             body = parse_request_body
             grant_type = body[:grant_type]
             entra_token = body[:entra_token]
 
             unless grant_type == 'client_credentials'
+              Legion::Logging.warn "API POST /api/auth/worker-token returned 400: unsupported grant_type=#{grant_type}"
               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 entra_token
+              Legion::Logging.warn 'API POST /api/auth/worker-token returned 400: entra_token is required'
+              halt 400, json_error('missing_entra_token', 'entra_token is required', status_code: 400)
+            end
 
             unless defined?(Legion::Crypt::JWT) && Legion::Crypt::JWT.respond_to?(:verify_with_jwks)
               halt 501, json_error('jwks_validation_not_available',
@@ -29,6 +34,7 @@ module Legion
             entra_settings = Routes::AuthWorker.resolve_entra_settings
             tenant_id = entra_settings[:tenant_id]
             unless tenant_id
+              Legion::Logging.error 'API POST /api/auth/worker-token returned 500: Entra tenant_id is not configured'
               halt 500, json_error('entra_tenant_not_configured',
                                    'Entra tenant_id is not configured', status_code: 500)
             end
@@ -41,25 +47,33 @@ module Legion
                 entra_token, jwks_url: jwks_url, issuers: [issuer]
               )
             rescue Legion::Crypt::JWT::ExpiredTokenError
+              Legion::Logging.warn 'API POST /api/auth/worker-token returned 401: Entra token has expired'
               halt 401, json_error('token_expired', 'Entra token has expired', status_code: 401)
             rescue Legion::Crypt::JWT::InvalidTokenError => e
+              Legion::Logging.warn "API POST /api/auth/worker-token returned 401: #{e.message}"
               halt 401, json_error('invalid_token', e.message, status_code: 401)
             rescue Legion::Crypt::JWT::Error => e
+              Legion::Logging.error "API POST /api/auth/worker-token returned 502: #{e.message}"
               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
+            unless app_id
+              Legion::Logging.warn 'API POST /api/auth/worker-token returned 401: missing appid claim'
+              halt 401, json_error('invalid_token', 'missing appid claim', status_code: 401)
+            end
 
             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
+              Legion::Logging.warn "API POST /api/auth/worker-token returned 404: no worker for entra_app_id=#{app_id}"
               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'
+              Legion::Logging.warn "API POST /api/auth/worker-token returned 403: worker #{worker.worker_id} is in #{worker.lifecycle_state} state"
               halt 403, json_error('worker_not_active',
                                    "worker is in #{worker.lifecycle_state} state", status_code: 403)
             end
@@ -69,6 +83,7 @@ module Legion
               worker_id: worker.worker_id, owner_msid: worker.owner_msid, ttl: ttl
             )
 
+            Legion::Logging.info "API: issued worker token for worker_id=#{worker.worker_id}"
             json_response({
                             access_token: token,
                             token_type:   'Bearer',

data/lib/legion/api/capacity.rb

@@ -11,6 +11,9 @@ module Legion
             workers = Routes::Capacity.fetch_worker_list
             model = Legion::Capacity::Model.new(workers: workers)
             json_response(model.aggregate)
+          rescue StandardError => e
+            Legion::Logging.error "API GET /api/capacity: #{e.class} — #{e.message}"
+            json_error('capacity_error', e.message, status_code: 500)
           end
 
           app.get '/api/capacity/forecast' do
@@ -21,12 +24,18 @@ module Legion
               growth_rate: (params[:growth_rate] || 0).to_f
             )
             json_response(forecast)
+          rescue StandardError => e
+            Legion::Logging.error "API GET /api/capacity/forecast: #{e.class} — #{e.message}"
+            json_error('capacity_error', e.message, status_code: 500)
           end
 
           app.get '/api/capacity/workers' do
             workers = Routes::Capacity.fetch_worker_list
             model = Legion::Capacity::Model.new(workers: workers)
             json_response(model.per_worker_stats)
+          rescue StandardError => e
+            Legion::Logging.error "API GET /api/capacity/workers: #{e.class} — #{e.message}"
+            json_error('capacity_error', e.message, status_code: 500)
           end
         end
 

data/lib/legion/api/chains.rb

@@ -4,7 +4,7 @@ module Legion
   class API < Sinatra::Base
     module Routes
       module Chains
-        def self.registered(app)
+        def self.registered(app) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
           app.get '/api/chains' do
             require_data!
             halt 501, json_error('not_implemented', 'chain data model is not yet available', status_code: 501) unless Legion::Data::Model.const_defined?(:Chain)
@@ -13,42 +13,62 @@ module Legion
           end
 
           app.post '/api/chains' do
+            Legion::Logging.debug "API: POST /api/chains params=#{params.keys}"
             require_data!
-            halt 501, json_error('not_implemented', 'chain data model is not yet available', status_code: 501) unless Legion::Data::Model.const_defined?(:Chain)
+            unless Legion::Data::Model.const_defined?(:Chain)
+              Legion::Logging.warn 'API POST /api/chains returned 501: chain data model is not yet available'
+              halt 501, json_error('not_implemented', 'chain data model is not yet available', status_code: 501)
+            end
 
             body = parse_request_body
-            halt 422, json_error('missing_field', 'name is required', status_code: 422) unless body[:name]
+            unless body[:name]
+              Legion::Logging.warn 'API POST /api/chains returned 422: name is required'
+              halt 422, json_error('missing_field', 'name is required', status_code: 422)
+            end
 
             id = Legion::Data::Model::Chain.insert(body)
             record = Legion::Data::Model::Chain[id]
+            Legion::Logging.info "API: created chain #{id} (#{body[:name]})"
             json_response(record.values, status_code: 201)
           end
 
           app.get '/api/chains/:id' do
             require_data!
-            halt 501, json_error('not_implemented', 'chain data model is not yet available', status_code: 501) unless Legion::Data::Model.const_defined?(:Chain)
+            unless Legion::Data::Model.const_defined?(:Chain)
+              Legion::Logging.warn "API GET /api/chains/#{params[:id]} returned 501: chain data model is not yet available"
+              halt 501, json_error('not_implemented', 'chain data model is not yet available', status_code: 501)
+            end
 
             record = find_or_halt(Legion::Data::Model::Chain, params[:id])
             json_response(record.values)
           end
 
           app.put '/api/chains/:id' do
+            Legion::Logging.debug "API: PUT /api/chains/#{params[:id]} params=#{params.keys}"
             require_data!
-            halt 501, json_error('not_implemented', 'chain data model is not yet available', status_code: 501) unless Legion::Data::Model.const_defined?(:Chain)
+            unless Legion::Data::Model.const_defined?(:Chain)
+              Legion::Logging.warn "API PUT /api/chains/#{params[:id]} returned 501: chain data model is not yet available"
+              halt 501, json_error('not_implemented', 'chain data model is not yet available', status_code: 501)
+            end
 
             record = find_or_halt(Legion::Data::Model::Chain, params[:id])
             body = parse_request_body
             record.update(body)
             record.refresh
+            Legion::Logging.info "API: updated chain #{params[:id]}"
             json_response(record.values)
           end
 
           app.delete '/api/chains/:id' do
             require_data!
-            halt 501, json_error('not_implemented', 'chain data model is not yet available', status_code: 501) unless Legion::Data::Model.const_defined?(:Chain)
+            unless Legion::Data::Model.const_defined?(:Chain)
+              Legion::Logging.warn "API DELETE /api/chains/#{params[:id]} returned 501: chain data model is not yet available"
+              halt 501, json_error('not_implemented', 'chain data model is not yet available', status_code: 501)
+            end
 
             record = find_or_halt(Legion::Data::Model::Chain, params[:id])
             record.delete
+            Legion::Logging.info "API: deleted chain #{params[:id]}"
             json_response({ deleted: true })
           end
         end

data/lib/legion/api/coldstart.rb

@@ -6,13 +6,23 @@ module Legion
       module Coldstart
         def self.registered(app)
           app.post '/api/coldstart/ingest' do
+            Legion::Logging.debug "API: POST /api/coldstart/ingest params=#{params.keys}"
             body = parse_request_body
             path = body[:path]
-            halt 422, json_error('missing_field', 'path is required', status_code: 422) if path.nil? || path.empty?
+            if path.nil? || path.empty?
+              Legion::Logging.warn 'API POST /api/coldstart/ingest returned 422: path is required'
+              halt 422, json_error('missing_field', 'path is required', status_code: 422)
+            end
 
-            halt 503, json_error('coldstart_unavailable', 'lex-coldstart is not loaded', status_code: 503) unless defined?(Legion::Extensions::Coldstart)
+            unless defined?(Legion::Extensions::Coldstart)
+              Legion::Logging.warn 'API POST /api/coldstart/ingest returned 503: lex-coldstart is not loaded'
+              halt 503, json_error('coldstart_unavailable', 'lex-coldstart is not loaded', status_code: 503)
+            end
 
-            halt 503, json_error('memory_unavailable', 'lex-memory is not loaded', status_code: 503) unless defined?(Legion::Extensions::Memory)
+            unless defined?(Legion::Extensions::Memory)
+              Legion::Logging.warn 'API POST /api/coldstart/ingest returned 503: lex-memory is not loaded'
+              halt 503, json_error('memory_unavailable', 'lex-memory is not loaded', status_code: 503)
+            end
 
             runner = Object.new.extend(Legion::Extensions::Coldstart::Runners::Ingest)
 
@@ -24,12 +34,14 @@ module Legion
                          pattern:  body[:pattern] || '**/{CLAUDE,MEMORY}.md'
                        )
                      else
+                       Legion::Logging.warn "API POST /api/coldstart/ingest returned 404: path not found: #{path}"
                        halt 404, json_error('path_not_found', "path not found: #{path}", status_code: 404)
                      end
 
+            Legion::Logging.info "API: coldstart ingest completed for path=#{path}"
             json_response(result, status_code: 201)
           rescue StandardError => e
-            Legion::Logging.error "API coldstart ingest error: #{e.message}"
+            Legion::Logging.error "API POST /api/coldstart/ingest: #{e.class} — #{e.message}"
             json_error('execution_error', e.message, status_code: 500)
           end
         end

data/lib/legion/api/extensions.rb

@@ -41,7 +41,7 @@ module Legion
           end
         end
 
-        def self.register_function_routes(app)
+        def self.register_function_routes(app) # rubocop:disable Metrics/AbcSize
           app.get '/api/extensions/:id/runners/:runner_id/functions' do
             require_data!
             find_or_halt(Legion::Data::Model::Extension, params[:id])
@@ -60,6 +60,8 @@ module Legion
 
           app.post '/api/extensions/:id/runners/:runner_id/functions/:function_id/invoke' do
             require_data!
+            path = "/api/extensions/#{params[:id]}/runners/#{params[:runner_id]}/functions/#{params[:function_id]}/invoke"
+            Legion::Logging.debug "API: POST #{path} params=#{params.keys}"
             find_or_halt(Legion::Data::Model::Extension, params[:id])
             runner = find_or_halt(Legion::Data::Model::Runner, params[:runner_id])
             func = find_or_halt(Legion::Data::Model::Function, params[:function_id])
@@ -71,11 +73,13 @@ module Legion
               check_subtask: body.fetch(:check_subtask, true),
               generate_task: body.fetch(:generate_task, true)
             )
+            Legion::Logging.info "API: invoked function #{func.values[:name]} via runner #{runner.values[:namespace]}, task #{result[:task_id]}"
             json_response(result, status_code: 201)
           rescue NameError => e
+            Legion::Logging.warn "API POST /api/extensions invoke returned 422: #{e.message}"
             json_error('invalid_runner', e.message, status_code: 422)
           rescue StandardError => e
-            Legion::Logging.error "API invoke error: #{e.message}"
+            Legion::Logging.error "API POST /api/extensions invoke: #{e.class} — #{e.message}"
             json_error('execution_error', e.message, status_code: 500)
           end
         end

data/lib/legion/api/gaia.rb

@@ -14,15 +14,19 @@ module Legion
           end
 
           app.post '/api/channels/teams/webhook' do
+            Legion::Logging.debug "API: POST /api/channels/teams/webhook params=#{params.keys}"
             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
+            unless adapter
+              Legion::Logging.warn 'API POST /api/channels/teams/webhook returned 503: teams adapter not available'
+              halt 503, json_response({ error: 'teams adapter not available' }, status_code: 503)
+            end
 
             input_frame = adapter.translate_inbound(activity)
             Legion::Gaia.sensory_buffer&.push(input_frame) if defined?(Legion::Gaia)
-
+            Legion::Logging.info "API: accepted Teams webhook frame_id=#{input_frame&.id}"
             json_response({ status: 'accepted', frame_id: input_frame&.id })
           end
         end

data/lib/legion/api/graphql.rb

@@ -11,6 +11,7 @@ module Legion
         def self.registered(app)
           app.post '/api/graphql' do
             content_type :json
+            Legion::Logging.debug "API: POST /api/graphql params=#{params.keys}" if defined?(Legion::Logging)
 
             body_str = request.body.read
             payload  = body_str.empty? ? {} : Legion::JSON.load(body_str)
@@ -21,6 +22,7 @@ module Legion
             operation_name = payload[:operationName]
 
             if query.nil? || query.strip.empty?
+              Legion::Logging.warn 'API POST /api/graphql returned 400: query is required' if defined?(Legion::Logging)
               status 400
               next Legion::JSON.dump({
                                        errors: [{ message: 'query is required' }]
@@ -37,7 +39,7 @@ module Legion
             status 200
             Legion::JSON.dump(result.to_h)
           rescue StandardError => e
-            Legion::Logging.error "GraphQL execution error: #{e.message}" if defined?(Legion::Logging)
+            Legion::Logging.error "API POST /api/graphql: #{e.class} — #{e.message}" if defined?(Legion::Logging)
             status 500
             Legion::JSON.dump({ errors: [{ message: e.message }] })
           end

data/lib/legion/api/hooks.rb

@@ -37,23 +37,36 @@ module Legion
 
         def self.handle_hook_request(context, request)
           splat_path = request.path_info.sub(%r{^/api/hooks/lex/}, '')
+          Legion::Logging.debug "API: #{request.request_method} /api/hooks/lex/#{splat_path}"
           hook_entry = Legion::API.find_hook_by_path(splat_path)
-          context.halt 404, context.json_error('not_found', "no hook registered for '#{splat_path}'", status_code: 404) if hook_entry.nil?
+          if hook_entry.nil?
+            Legion::Logging.warn "API #{request.request_method} #{request.path_info} returned 404: no hook registered for '#{splat_path}'"
+            context.halt 404, context.json_error('not_found', "no hook registered for '#{splat_path}'", status_code: 404)
+          end
 
           body = request.request_method == 'POST' ? request.body.read : nil
           hook = hook_entry[:hook_class].new
-          context.halt 401, context.json_error('unauthorized', 'hook verification failed', status_code: 401) unless hook.verify(request.env, body || '')
+          unless hook.verify(request.env, body || '')
+            Legion::Logging.warn "API #{request.request_method} #{request.path_info} returned 401: hook verification failed"
+            context.halt 401, context.json_error('unauthorized', 'hook verification failed', status_code: 401)
+          end
 
           payload = build_payload(request, body)
           function = hook.route(request.env, payload)
-          context.halt 422, context.json_error('unhandled_event', 'hook could not route this event', status_code: 422) if function.nil?
+          if function.nil?
+            Legion::Logging.warn "API #{request.request_method} #{request.path_info} returned 422: hook could not route this event"
+            context.halt 422, context.json_error('unhandled_event', 'hook could not route this event', status_code: 422)
+          end
 
           runner = hook.runner_class || hook_entry[:default_runner]
-          context.halt 500, context.json_error('no_runner', 'no runner class configured for this hook', status_code: 500) if runner.nil?
+          if runner.nil?
+            Legion::Logging.error "API #{request.request_method} #{request.path_info} returned 500: no runner class configured for hook '#{splat_path}'"
+            context.halt 500, context.json_error('no_runner', 'no runner class configured for this hook', status_code: 500)
+          end
 
           dispatch_hook(context, payload: payload, runner: runner, function: function)
         rescue StandardError => e
-          Legion::Logging.error "Hook error: #{e.message}"
+          Legion::Logging.error "API #{request.request_method} #{request.path_info}: #{e.class} — #{e.message}"
           Legion::Logging.error e.backtrace&.first(5)
           context.json_error('internal_error', e.message, status_code: 500)
         end
@@ -74,6 +87,7 @@ module Legion
             payload: payload, runner_class: runner, function: function,
             source: 'hook', check_subtask: true, generate_task: true
           )
+          Legion::Logging.info "API: dispatched hook to #{runner}##{function}, task #{result[:task_id]}"
           return render_custom_response(context, result[:response]) if result.is_a?(Hash) && result[:response]
 
           context.json_response({ task_id: result[:task_id], status: result[:status] })

data/lib/legion/api/lex.rb

@@ -33,8 +33,10 @@ module Legion
 
         def self.handle_lex_request(context, request)
           splat_path = request.path_info.sub(%r{^/api/lex/}, '')
+          Legion::Logging.debug "API: POST /api/lex/#{splat_path}"
           route_entry = Legion::API.find_route_by_path(splat_path)
           if route_entry.nil?
+            Legion::Logging.warn "API POST /api/lex/#{splat_path} returned 404: no route registered"
             context.halt 404, context.json_error('route_not_found',
                                                  "no route registered for '#{splat_path}'", status_code: 404)
           end
@@ -47,10 +49,11 @@ module Legion
             source:        'lex_route',
             generate_task: true
           )
+          Legion::Logging.info "API: LEX route #{splat_path} dispatched to #{route_entry[:runner_class]}, task #{result[:task_id]}"
           context.json_response({ task_id: result[:task_id], status: result[:status],
                                    result: result[:result] }.compact)
         rescue StandardError => e
-          Legion::Logging.error "LEX route error: #{e.message}"
+          Legion::Logging.error "API POST /api/lex/#{request.path_info.sub(%r{^/api/lex/}, '')}: #{e.class} — #{e.message}"
           Legion::Logging.error e.backtrace&.first(5)
           context.json_error('internal_error', e.message, status_code: 500)
         end