legionio 1.6.22 → 1.6.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68888d98222b99e6e88670e8df81245d312dbed7c5f04d59a0cb79e592d65e47
-  data.tar.gz: be305f5229f73ad9c28e76a87c5353afac7edfbe8764284db03e34d727af1ef8
+  metadata.gz: 02c65a88cb7cdf1a90b60cc3fe150983d9f3aa7b465344ab63a2e9128327b943
+  data.tar.gz: ff0aa83e8b72dc3452b0d11f08006ddd3cee4d831f99213da2bb65f153f17963
 SHA512:
-  metadata.gz: 180fc2adda6a37c44accfddd5c25099bab8568462ec58c99f51ccf58203d62d65813831ff569cfcd729524566be12b2c037c6df184efcf1514d9a9bd75964698
-  data.tar.gz: d5f1b84b9c562df8766b20923ebec48215b78b28e600744e9b210578a311138df4ffef221f8bb42520272fc71bff8b3041420765d7d876c8a634146927e55b15
+  metadata.gz: 7b6b41d1f383380ef4c7d6a01b6ca4bc6eb595afc7a3674544d25afb6d88a6fae37f1fefd94542a1bc801e40d18c966b3de8832fea5b6c08c410125a7e08f45f
+  data.tar.gz: 6dc2552ec0839432ab21c3664973c78b9ae9c392749758fb8422a35637c5cf9c7c3bf3219594d7b5c82e474e0e6cbe2e286f059de4429aabee660bbe94d058bb

data/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [1.6.24] - 2026-03-28
+
+### Added
+- `Legion::API.register_library_routes(gem_name, routes_module)` class method: library gems self-register their Sinatra route modules at boot via `router.register_library` + Sinatra `register`. Implemented in `lib/legion/api/library_routes.rb`.
+- `Legion::API::SyncDispatch.dispatch(exchange_name, routing_key, payload, envelope, timeout:)`: synchronous AMQP dispatch using a temporary exclusive reply_to queue with configurable timeout (default 30s). Implemented in `lib/legion/api/sync_dispatch.rb`.
+- Remote dispatch in `LexDispatch`: when a registered extension route's runner class is not loaded in the current process, the request is forwarded via AMQP — async (202) by default or sync (blocks on reply queue) when `X-Legion-Sync: true` header is present. Returns 403 when `definition[:remote_invocable] == false`.
+- `Routes::Llm` and `Routes::Apollo` registration now guarded: skipped in `api.rb` when `Legion::LLM::Routes` / `Legion::Apollo::Routes` are already defined (i.e. self-registered by the library gem).
+
+### Changed
+- `api.rb`: requires `api/library_routes` and `api/sync_dispatch`; LLM and Apollo route registration conditional on gem self-registration not already having run.
+
+## [1.6.23] - 2026-03-28
+
+### Added
+- `Legion::Extensions::Definitions` mixin: class-level `definition` DSL for method contracts (`desc`, `inputs`, `outputs`, `remote_invocable`, `mcp_exposed`, `idempotent`, `risk_tier`, `tags`, `requires`). Auto-extended onto every runner module at boot by the builder.
+- `Legion::Extensions::Actors::Dsl` mixin: `define_dsl_accessor` generates class-level getter/setter DSL with inheritance and instance delegation. Wired into all actor base classes (`Every`, `Poll`, `Subscription`, `Once`, `Base`).
+- `Absorbers::Base#absorb`: canonical entry point replacing `handle`. `alias handle absorb` preserves backward compatibility.
+
+### Changed
+- `Builders::Runners#build_runner_list`: auto-extends `Legion::Extensions::Definitions` onto every discovered runner module unless it already responds to `:definition`.
+- `Hooks::Base`: extended with `Definitions` mixin; `mount` DSL removed (paths fully derived from naming).
+- `Absorbers::Base`: extended with `Definitions` mixin.
+- `AbsorberDispatch`: calls `absorber.absorb` instead of `absorber.handle`.
+- `Helpers::Lex`: all `function_*` helpers and `expose_as_mcp_tool`/`mcp_tool_prefix` marked `@deprecated` — use `definition` DSL instead.
+
 ## [1.6.22] - 2026-03-27
 
 ### Added

data/lib/legion/api/lex_dispatch.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  class API < Sinatra::Base
+    module Routes
+      module LexDispatch
+        def self.registered(app)
+          register_discovery(app)
+          register_dispatch(app)
+        end
+
+        # Discovery endpoints (GET)
+        def self.register_discovery(app)
+          # GET /api/extensions/index — list all extensions
+          app.get '/api/extensions/index' do
+            content_type :json
+            names = Legion::API.router.extension_names
+            Legion::JSON.dump({ extensions: names })
+          end
+
+          # GET /api/extensions/:lex_name/:component_type/:component_name/:method_name — full contract
+          app.get '/api/extensions/:lex_name/:component_type/:component_name/:method_name' do
+            content_type :json
+            entry = Legion::API.router.find_extension_route(
+              params[:lex_name], params[:component_type],
+              params[:component_name], params[:method_name]
+            )
+            unless entry
+              halt 404, Legion::JSON.dump({
+                                            task_id:         nil,
+                                            conversation_id: nil,
+                                            status:          'failed',
+                                            error:           { code: 404, message: 'route not found' }
+                                          })
+            end
+
+            amqp_pfx = entry[:amqp_prefix].to_s.then { |p| p.empty? ? "lex.#{params[:lex_name]}" : p }
+            response = {
+              extension:      params[:lex_name],
+              component_type: params[:component_type],
+              component:      params[:component_name],
+              method:         params[:method_name],
+              definition:     entry[:definition],
+              amqp:           {
+                exchange:    amqp_pfx,
+                routing_key: "#{amqp_pfx}.#{params[:component_type]}.#{params[:component_name]}.#{params[:method_name]}"
+              }
+            }
+            if params[:component_type] == 'hooks'
+              response[:hook_endpoint] =
+                "/api/extensions/#{params[:lex_name]}/hooks/#{params[:component_name]}/#{params[:method_name]}"
+            end
+            Legion::JSON.dump(response)
+          end
+        end
+
+        # Dispatch endpoint (POST)
+        def self.register_dispatch(app)
+          dispatcher = method(:dispatch_request)
+          app.post '/api/extensions/:lex_name/:component_type/:component_name/:method_name' do
+            dispatcher.call(self, request, params)
+          end
+        end
+
+        def self.dispatch_request(context, request, params) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+          content_type = 'application/json'
+          context.content_type content_type
+
+          entry = Legion::API.router.find_extension_route(
+            params[:lex_name], params[:component_type],
+            params[:component_name], params[:method_name]
+          )
+
+          unless entry
+            route_key = "#{params[:lex_name]}/#{params[:component_type]}/#{params[:component_name]}/#{params[:method_name]}"
+            context.halt 404, Legion::JSON.dump({
+                                                  task_id:         nil,
+                                                  conversation_id: nil,
+                                                  status:          'failed',
+                                                  error:           { code: 404, message: "no route registered for '#{route_key}'" }
+                                                })
+          end
+
+          envelope = build_envelope(request)
+
+          payload = begin
+            body = request.body.read
+            body.nil? || body.empty? ? {} : Legion::JSON.load(body)
+          rescue StandardError => e
+            Legion::Logging.warn "[LexDispatch] invalid JSON body: #{e.message}" if defined?(Legion::Logging)
+            context.halt 400, Legion::JSON.dump({
+                                                  task_id:         nil,
+                                                  conversation_id: nil,
+                                                  status:          'failed',
+                                                  error:           { code: 400, message: 'request body is not valid JSON' }
+                                                })
+          end
+
+          # Remote dispatch: when the runner class is not loaded locally, forward via AMQP
+          unless extension_loaded_locally?(entry)
+            if definition_blocks_remote?(entry)
+              context.halt 403, Legion::JSON.dump({
+                                                    task_id:         nil,
+                                                    conversation_id: nil,
+                                                    status:          'failed',
+                                                    error:           { code: 403, message: 'Method not remotely invocable' }
+                                                  })
+            end
+
+            exchange_name = entry[:amqp_prefix].to_s.then { |p| p.empty? ? "lex.#{entry[:lex_name]}" : p }
+            routing_key   = "#{exchange_name}.#{entry[:component_type]}.#{entry[:component_name]}.#{entry[:method_name]}"
+
+            if request.env['HTTP_X_LEGION_SYNC'] == 'true'
+              result = Legion::API::SyncDispatch.dispatch(exchange_name, routing_key, payload, envelope)
+              return Legion::JSON.dump(result)
+            else
+              unless defined?(Legion::Transport) &&
+                     Legion::Transport.respond_to?(:connected?) &&
+                     Legion::Transport.connected?
+                context.halt 503, Legion::JSON.dump({
+                                                      task_id:         nil,
+                                                      conversation_id: nil,
+                                                      status:          'failed',
+                                                      error:           { code: 503, message: 'Transport not available' }
+                                                    })
+              end
+
+              dispatch_async_amqp(exchange_name, routing_key, payload, envelope)
+              context.status 202
+              return Legion::JSON.dump(envelope.merge(status: 'queued'))
+            end
+          end
+
+          result = Legion::Ingress.run(
+            payload:       payload.merge(envelope.slice(:task_id, :conversation_id, :parent_id, :master_id, :chain_id)),
+            runner_class:  entry[:runner_class],
+            function:      entry[:method_name].to_sym,
+            source:        'lex_dispatch',
+            generate_task: true
+          )
+
+          response_body = envelope.merge(
+            status: result[:status],
+            result: result[:result]
+          ).compact
+
+          Legion::JSON.dump(response_body)
+        rescue StandardError => e
+          route_key = "#{params[:lex_name]}/#{params[:component_type]}/#{params[:component_name]}/#{params[:method_name]}"
+          Legion::Logging.log_exception(e, payload_summary: "LexDispatch POST #{route_key}", component_type: :api)
+          context.status 500
+          Legion::JSON.dump({
+                              task_id:         nil,
+                              conversation_id: nil,
+                              status:          'failed',
+                              error:           { code: 500, message: e.message }
+                            })
+        end
+
+        def self.parse_header_integer(value)
+          return nil if value.nil?
+
+          Integer(value)
+        rescue ArgumentError, TypeError
+          nil
+        end
+
+        def self.build_envelope(request)
+          task_id         = parse_header_integer(request.env['HTTP_X_LEGION_TASK_ID'])
+          conversation_id = request.env['HTTP_X_LEGION_CONVERSATION_ID'] || ::SecureRandom.uuid
+          parent_id       = parse_header_integer(request.env['HTTP_X_LEGION_PARENT_ID'])
+          master_id       = parse_header_integer(request.env['HTTP_X_LEGION_MASTER_ID'])
+          chain_id        = parse_header_integer(request.env['HTTP_X_LEGION_CHAIN_ID'])
+          debug           = request.env['HTTP_X_LEGION_DEBUG'] == 'true'
+
+          {
+            task_id:         task_id,
+            conversation_id: conversation_id,
+            parent_id:       parent_id,
+            master_id:       master_id || task_id,
+            chain_id:        chain_id,
+            debug:           debug
+          }.compact
+        end
+
+        # Returns true when the runner class referenced by the route entry is
+        # available in the current process (i.e. the extension is loaded locally).
+        def self.extension_loaded_locally?(entry)
+          runner_class = entry[:runner_class]
+          return false if runner_class.nil? || runner_class.to_s.empty?
+
+          # Try constant lookup — safe because runner_class is from the route registry,
+          # not from user input.
+          parts = runner_class.to_s.split('::').reject(&:empty?)
+          parts.reduce(Object) { |mod, name| mod.const_get(name, false) }
+          true
+        rescue NameError, TypeError
+          false
+        end
+
+        # Returns true when the definition-level flag explicitly disables remote dispatch.
+        # Extension-level gate (entry[:lex_name] module) takes precedence over definition flag.
+        def self.definition_blocks_remote?(entry)
+          defn = entry[:definition]
+          return false if defn.nil?
+
+          defn[:remote_invocable] == false
+        end
+
+        # Publish an async AMQP message for remote dispatch (fire-and-forget).
+        def self.dispatch_async_amqp(exchange_name, routing_key, payload, envelope)
+          return unless defined?(Legion::Transport) &&
+                        Legion::Transport.respond_to?(:connected?) &&
+                        Legion::Transport.connected?
+
+          channel = Legion::Transport.channel
+          exchange = channel.exchange(exchange_name, type: :topic, durable: true, passive: true)
+          message = Legion::JSON.dump(payload.merge(envelope))
+          exchange.publish(message, routing_key: routing_key, content_type: 'application/json', persistent: true)
+        rescue StandardError => e
+          Legion::Logging.warn "[LexDispatch] async AMQP publish failed: #{e.message}" if defined?(Legion::Logging)
+          raise
+        end
+
+        class << self
+          private :register_discovery, :register_dispatch, :dispatch_request, :parse_header_integer,
+                  :build_envelope, :extension_loaded_locally?, :definition_blocks_remote?, :dispatch_async_amqp
+        end
+      end
+    end
+  end
+end

data/lib/legion/api/library_routes.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Legion
+  class API < Sinatra::Base
+    # Register a library gem's route module with the tier-aware router and mount it
+    # on this Sinatra app.
+    #
+    # Call from the library gem's boot/start method:
+    #   Legion::API.register_library_routes('llm', Legion::LLM::Routes) if defined?(Legion::API)
+    #
+    # @param gem_name [String] short name for the library (e.g. 'llm', 'apollo')
+    # @param routes_module [Module] a Sinatra::Extension module to register
+    def self.register_library_routes(gem_name, routes_module)
+      router.register_library(gem_name, routes_module)
+      register routes_module
+    end
+  end
+end

data/lib/legion/api/router.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Legion
+  class API < Sinatra::Base
+    class Router
+      def initialize
+        @infrastructure_routes = []
+        @library_routes = {}
+        @extension_routes = {}
+      end
+
+      # --- Infrastructure tier ---
+
+      def register_infrastructure(path, method: :get, summary: nil)
+        @infrastructure_routes << { path: path, method: method, summary: summary }
+      end
+
+      def infrastructure_routes
+        @infrastructure_routes.dup
+      end
+
+      # --- Library gem tier ---
+
+      def register_library(gem_name, routes_module)
+        @library_routes[gem_name.to_s] = routes_module
+      end
+
+      def library_routes
+        @library_routes.dup
+      end
+
+      def library_names
+        @library_routes.keys
+      end
+
+      # --- Extension tier ---
+
+      def register_extension_route(**opts)
+        lex_name = opts[:lex_name]
+        component_type = opts[:component_type]
+        component_name = opts[:component_name]
+        method_name = opts[:method_name]
+        key = "#{lex_name}/#{component_type}/#{component_name}/#{method_name}"
+        @extension_routes[key] = {
+          lex_name:       lex_name.to_s,
+          amqp_prefix:    opts[:amqp_prefix].to_s,
+          component_type: component_type.to_s,
+          component_name: component_name.to_s,
+          method_name:    method_name.to_s,
+          runner_class:   opts[:runner_class],
+          definition:     opts[:definition]
+        }
+      end
+
+      def find_extension_route(lex_name, component_type, component_name, method_name)
+        key = "#{lex_name}/#{component_type}/#{component_name}/#{method_name}"
+        @extension_routes[key]
+      end
+
+      def extension_routes
+        @extension_routes.dup
+      end
+
+      def extension_names
+        @extension_routes.values.map { |r| r[:lex_name] }.uniq
+      end
+
+      def components_for(lex_name)
+        @extension_routes.values
+                         .select { |r| r[:lex_name] == lex_name.to_s }
+                         .group_by { |r| r[:component_type] }
+      end
+
+      def methods_for(lex_name, component_type, component_name)
+        @extension_routes.values.select do |r|
+          r[:lex_name] == lex_name.to_s &&
+            r[:component_type] == component_type.to_s &&
+            r[:component_name] == component_name.to_s
+        end
+      end
+
+      def discovery_extension(lex_name)
+        comps = components_for(lex_name)
+        return nil if comps.empty?
+
+        comps.transform_values do |routes|
+          routes.map { |r| { name: r[:component_name], method: r[:method_name], definition: r[:definition] } }
+        end
+      end
+
+      def clear!
+        @infrastructure_routes.clear
+        @library_routes.clear
+        @extension_routes.clear
+      end
+    end
+  end
+end

data/lib/legion/api/sync_dispatch.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  class API < Sinatra::Base
+    module SyncDispatch
+      # Dispatch a message synchronously via AMQP using a temporary reply_to queue.
+      # Blocks until a response arrives or the timeout expires.
+      #
+      # @param exchange_name [String]   target exchange (e.g. "lex.github")
+      # @param routing_key   [String]   routing key (e.g. "lex.github.runners.pull_request.create")
+      # @param payload       [Hash]     message payload
+      # @param envelope      [Hash]     task envelope (task_id, conversation_id, etc.)
+      # @param timeout       [Integer]  seconds to wait (default 30)
+      # @return [Hash]
+      def self.dispatch(exchange_name, routing_key, payload, envelope, timeout: 30)
+        unless defined?(Legion::Transport) &&
+               Legion::Transport.respond_to?(:connected?) &&
+               Legion::Transport.connected?
+          return envelope.merge(
+            status: 'failed',
+            error:  { code: 503, message: 'Transport not available for sync dispatch' }
+          )
+        end
+
+        perform_dispatch(exchange_name, routing_key, payload, envelope, timeout)
+      rescue StandardError => e
+        Legion::Logging.error "[SyncDispatch] #{e.class}: #{e.message}" if defined?(Legion::Logging)
+        envelope.merge(
+          status: 'failed',
+          error:  { code: 500, message: e.message }
+        )
+      end
+
+      # @api private
+      def self.perform_dispatch(exchange_name, routing_key, payload, envelope, timeout)
+        response  = nil
+        mutex     = Mutex.new
+        condition = ConditionVariable.new
+        reply_queue_name = "sync.reply.#{::SecureRandom.uuid}"
+
+        begin
+          channel = Legion::Transport.channel
+          reply_queue = channel.queue(reply_queue_name, exclusive: true, auto_delete: true)
+          subscribe_reply(reply_queue, mutex, condition) { |r| response = r }
+          publish_sync(channel, exchange_name, routing_key, payload, envelope, reply_queue_name)
+          wait_for_response(mutex, condition, timeout) { response }
+          response || envelope.merge(
+            status: 'timeout',
+            error:  { code: 504, message: "Sync dispatch timed out after #{timeout}s" }
+          )
+        ensure
+          reply_queue&.delete rescue nil # rubocop:disable Style/RescueModifier
+        end
+      end
+
+      # @api private
+      def self.subscribe_reply(reply_queue, mutex, condition)
+        reply_queue.subscribe(block: false) do |_delivery_info, _metadata, body|
+          parsed = begin
+            Legion::JSON.load(body)
+          rescue StandardError
+            { raw: body }
+          end
+          mutex.synchronize do
+            yield parsed
+            condition.signal
+          end
+        end
+      end
+
+      # @api private
+      def self.wait_for_response(mutex, condition, timeout)
+        mutex.synchronize do
+          deadline = Time.now + timeout
+          loop do
+            remaining = deadline - Time.now
+            break if yield || remaining <= 0
+
+            condition.wait(mutex, remaining)
+          end
+        end
+      end
+
+      # @api private
+      def self.publish_sync(channel, exchange_name, routing_key, payload, envelope, reply_queue_name) # rubocop:disable Metrics/ParameterLists
+        exchange = channel.exchange(exchange_name, type: :topic, durable: true, passive: true)
+        message = Legion::JSON.dump(payload.merge(envelope))
+        exchange.publish(
+          message,
+          routing_key:  routing_key,
+          reply_to:     reply_queue_name,
+          content_type: 'application/json',
+          persistent:   false
+        )
+      end
+
+      private_class_method :perform_dispatch, :subscribe_reply, :wait_for_response, :publish_sync
+    end
+  end
+end

data/lib/legion/api.rb

@@ -47,6 +47,10 @@ require_relative 'api/costs'
 require_relative 'api/traces'
 require_relative 'api/stats'
 require_relative 'api/codegen'
+require_relative 'api/router'
+require_relative 'api/library_routes'
+require_relative 'api/sync_dispatch'
+require_relative 'api/lex_dispatch'
 require_relative 'api/graphql' if defined?(GraphQL)
 
 module Legion
@@ -72,6 +76,21 @@ module Legion
       Legion::API::OpenAPI.to_json
     end
 
+    # Root discovery — lists all tiers
+    get '/api/discovery' do
+      content_type :json
+      Legion::JSON.dump({
+                          infrastructure: [
+                            { path: '/api/health', method: 'GET' },
+                            { path: '/api/ready', method: 'GET' },
+                            { path: '/api/openapi.json', method: 'GET' },
+                            { path: '/api/discovery', method: 'GET' }
+                          ],
+                          libraries:      Legion::API.router.library_names,
+                          extensions:     Legion::API.router.extension_names
+                        })
+    end
+
     # Health and readiness
     get '/api/health' do
       json_response({ status: 'ok', version: Legion::VERSION })
@@ -87,8 +106,14 @@ module Legion
       content_type :json
       Legion::Logging.warn "API #{request.request_method} #{request.path_info} returned 404: no route matches"
       Legion::JSON.dump({
-                          error: { code: 'not_found', message: "no route matches #{request.request_method} #{request.path_info}" },
-                          meta:  { timestamp: Time.now.utc.iso8601, node: Legion::Settings[:client][:name] }
+                          task_id:         nil,
+                          conversation_id: nil,
+                          status:          'failed',
+                          error:           {
+                            code:    404,
+                            message: "no route matches #{request.request_method} #{request.path_info}"
+                          },
+                          meta:            { timestamp: Time.now.utc.iso8601, node: Legion::Settings[:client][:name] }
                         })
     end
 
@@ -97,12 +122,16 @@ module Legion
       err = env['sinatra.error']
       Legion::Logging.log_exception(err, payload_summary: "API #{request.request_method} #{request.path_info} returned 500", component_type: :api)
       Legion::JSON.dump({
-                          error: { code: 'internal_error', message: err.message },
-                          meta:  { timestamp: Time.now.utc.iso8601, node: Legion::Settings[:client][:name] }
+                          task_id:         nil,
+                          conversation_id: nil,
+                          status:          'failed',
+                          error:           { code: 500, message: err.message },
+                          meta:            { timestamp: Time.now.utc.iso8601, node: Legion::Settings[:client][:name] }
                         })
     end
 
     # Mount route modules
+    register Routes::LexDispatch
     register Routes::Tasks
     register Routes::Extensions
     register Routes::Nodes
@@ -126,14 +155,14 @@ module Legion
     register Routes::Capacity
     register Routes::Audit
     register Routes::Metrics
-    register Routes::Llm
+    register Routes::Llm unless defined?(Legion::LLM::Routes)
     register Routes::ExtensionCatalog
     register Routes::OrgChart
     register Routes::Governance
     register Routes::Acp
     register Routes::Prompts
     register Routes::Marketplace
-    register Routes::Apollo
+    register Routes::Apollo unless defined?(Legion::Apollo::Routes)
     register Routes::Costs
     register Routes::Traces
     register Routes::Stats
@@ -143,6 +172,13 @@ module Legion
     use Legion::API::Middleware::RequestLogger
     use Legion::Rbac::Middleware if defined?(Legion::Rbac::Middleware)
 
+    # Tier-aware router (three-tier namespace)
+    class << self
+      def router
+        @router ||= Legion::API::Router.new
+      end
+    end
+
     # Hook registry (preserved from original implementation)
     class << self
       def hook_registry