legionio 1.9.0 → 1.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69a0d25a5f8ac2e2327e09ca2185099bd87e7b8575d8c941abc807a0b6c03dfb
-  data.tar.gz: f9cb3bcdb322e670a235cc7761e43377d11ed8fed8e7e34b235b8ff77773ef8a
+  metadata.gz: 1dee00872a482d84ca7cffed624add4a568595383b31d93ffe1983d5bfb89d91
+  data.tar.gz: 0e8eaba327808c586a3cdf6d9e8da177831ac0ce9f5fb1919de115f48b63346f
 SHA512:
-  metadata.gz: 2d7fe093823d8a62b3bbf31f1cb9733b18d56a208990f314e7b9c9ec9ec1b51af2faf18716b48032fd57039b71aec7f32629d0d2218a9500f4746c0525da432f
-  data.tar.gz: 51b33926ea63e730ee6407e61da81808bb058030fcb1f1f2d3cd87bcafe25b4c82b21d8a914dabb02771795329e601cc1d14f2b147efccc274895da78c11cfc0
+  metadata.gz: 7b7124a1ed4fa62aaa5da4e55391961973435b324cc17142245c52af7b32d43d6f7c161341f12d27aca47310dc9e6289a3d1a4d781561b001baa724c03ddc8ba
+  data.tar.gz: 952d0045d985d1f14ac76e15e015fa8bd279ed92ae123cd43e7f5139ed7efbee9a3cba93856ce2f6c8603e74f9549495e415fcd8459a27d3b35cb169eebec617

data/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [1.9.2] - 2026-04-27
+
+### Fixed
+- `POST /api/knowledge/status` no longer silently defaults to the daemon's cwd. Uses `knowledge.default_corpus_path` setting or `LEGION_CORPUS_PATH` env var; returns 400 when unresolvable. Prevents `Errno::EPERM` crashes on macOS when the daemon is launched from `~` and `Find.find` walks into TCC-protected subdirs like `~/Library/Accounts`.
+
+## [1.9.1] - 2026-04-25
+
+### Added
+- Extension runtime handles now expose authoritative active/latest versions, reload state, pending-reload status, hot-reload eligibility, and owned runtime resources through `/api/extension_catalog`.
+- Extension dispatch quiescing now blocks API, ingress, and subscription runner dispatch while an extension is stopping or actively reloading.
+- `Legion::Tools::Registry.unregister_extension` removes callable tools owned by an extension during unload/reload cleanup.
+
+### Fixed
+- Runtime handle `loaded?` no longer reports `stopped` or `failed` extensions as loaded.
+- Extension registration publication now happens after extension autobuild and runtime side effects complete, avoiding durable registration of failed loads.
+- Extension runtime handles now transition to loaded only after `require` and extension side effects succeed, and multi-segment extension modules keep their hyphenated lex identity.
+
 ## [1.9.0] - 2026-04-24
 
 ### Added

data/lib/legion/api/extensions.rb

@@ -22,33 +22,21 @@ module Legion
 
         def self.register_extension_routes(app)
           app.get '/api/extension_catalog' do
-            entries = Legion::Extensions::Catalog.all.map do |name, entry|
-              { name: name, state: entry[:state].to_s,
-                registered_at: entry[:registered_at]&.iso8601,
-                started_at: entry[:started_at]&.iso8601 }
-            end
+            entries = Routes::Extensions.extension_entries
             entries = entries.select { |e| e[:state] == params[:state] } if params[:state]
             json_response(entries)
           end
 
           app.get '/api/extension_catalog/:name' do
             name = params[:name]
-            entry = Legion::Extensions::Catalog.entry(name)
+            entry = Routes::Extensions.extension_entry(name)
             halt_not_found("extension '#{name}' not found") unless entry
 
             ext_mod = find_extension_module(name)
-            version = ext_mod&.const_defined?(:VERSION) ? ext_mod::VERSION : nil
 
             runners = ext_mod ? runner_summaries(ext_mod) : []
 
-            json_response({
-              name:          name,
-              state:         entry[:state].to_s,
-              version:       version,
-              registered_at: entry[:registered_at]&.iso8601,
-              started_at:    entry[:started_at]&.iso8601,
-              runners:       runners
-            }.compact)
+            json_response(entry.merge(runners: runners).compact)
           end
         end
 
@@ -154,6 +142,52 @@ module Legion
         end
 
         class << self
+          def extension_entries
+            handles = if Legion::Extensions.respond_to?(:extension_handles)
+                        Legion::Extensions.extension_handles
+                      else
+                        []
+                      end
+            return handles.map { |handle| serialize_handle(handle) } unless handles.empty?
+
+            Legion::Extensions::Catalog.all.filter_map do |name, entry|
+              serialize_catalog_entry(name, entry)
+            end
+          end
+
+          def extension_entry(name)
+            handle = Legion::Extensions.extension_handle(name) if Legion::Extensions.respond_to?(:extension_handle)
+            return serialize_handle(handle) if handle
+
+            serialize_catalog_entry(name, Legion::Extensions::Catalog.entry(name))
+          end
+
+          def serialize_handle(handle)
+            {
+              name:                     handle.lex_name,
+              state:                    handle.state.to_s,
+              active_version:           handle.active_version&.to_s,
+              latest_installed_version: handle.latest_installed_version&.to_s,
+              reload_state:             handle.reload_state.to_s,
+              pending_reload:           handle.pending_reload?,
+              hot_reloadable:           handle.hot_reloadable,
+              loaded_at:                handle.loaded_at&.iso8601,
+              last_error:               handle.last_error,
+              routes:                   handle.routes,
+              tools:                    handle.tools,
+              absorbers:                handle.absorbers,
+              owned_runners:            handle.runners
+            }.compact
+          end
+
+          def serialize_catalog_entry(name, entry)
+            return nil unless entry
+
+            { name: name, state: entry[:state].to_s,
+              registered_at: entry[:registered_at]&.iso8601,
+              started_at: entry[:started_at]&.iso8601 }
+          end
+
           private :register_available_route, :register_extension_routes,
                   :register_runner_routes, :register_function_routes, :register_invoke_route
         end

data/lib/legion/api/knowledge.rb

@@ -67,7 +67,15 @@ module Legion
           app.post '/api/knowledge/status' do
             require_knowledge_ingest!
             body = parse_request_body
-            path = body[:path] || Dir.pwd
+            path = body[:path] ||
+                   Legion::Settings.dig(:knowledge, :default_corpus_path) ||
+                   ENV.fetch('LEGION_CORPUS_PATH', nil)
+
+            if path.nil? || path.to_s.empty?
+              halt 400, json_error('missing_param',
+                                   'path is required (no knowledge.default_corpus_path configured)')
+            end
+
             result = Legion::Extensions::Knowledge::Runners::Ingest.scan_corpus(path: path)
             json_response(result)
           end

data/lib/legion/api/stats.rb

@@ -20,21 +20,23 @@ module Legion
           end
         end
 
-        EXTENSION_IVARS = {
-          loaded:       :@loaded_extensions,
+        EXTENSION_TASK_IVARS = {
           discovered:   :@extensions,
           subscription: :@subscription_tasks,
           every:        :@timer_tasks,
           poll:         :@poll_tasks,
           once:         :@once_tasks,
           loop:         :@loop_tasks,
-          running:      :@running_instances
+          actors:       :@running_instances
         }.freeze
 
         class << self
           def collect_extensions
             ext = Legion::Extensions
-            EXTENSION_IVARS.transform_values { |ivar| ext.instance_variable_get(ivar)&.count || 0 }
+            {
+              loaded:  ext.extension_handle_registry.loaded.count,
+              running: ext.extension_handle_registry.running.count
+            }.merge(EXTENSION_TASK_IVARS.transform_values { |ivar| ext.instance_variable_get(ivar)&.count || 0 })
           rescue StandardError => e
             { error: e.message }
           end

data/lib/legion/extensions/actors/subscription.rb

@@ -214,6 +214,11 @@ module Legion
         end
 
         def dispatch_runner(message, runner_cls, function, check_subtask, generate_task)
+          unless extension_dispatch_allowed?
+            log.warn "[Subscription] rejecting #{lex_name}/#{function}: extension is not accepting new work" if defined?(log)
+            return { success: false, status: 'task.blocked', error: { code: 'extension_quiescing' } }
+          end
+
           run_block = lambda {
             ctx = message.merge(runner_class: runner_cls.to_s, function: function.to_s)
             Legion::Context.with_task_context(ctx) do
@@ -232,6 +237,12 @@ module Legion
           end
         end
 
+        def extension_dispatch_allowed?
+          return true unless defined?(Legion::Extensions) && Legion::Extensions.respond_to?(:dispatch_allowed?)
+
+          Legion::Extensions.dispatch_allowed?(lex_name)
+        end
+
         def reject_or_retry(delivery_info, metadata, payload)
           headers = metadata&.headers || {}
           retry_count = RetryPolicy.extract_retry_count(headers)

data/lib/legion/extensions/handle.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    class Handle
+      STATES = %i[registered loaded starting running stopping stopped failed].freeze
+      LOADED_STATES = %i[loaded starting running stopping].freeze
+      DISPATCHABLE_STATES = %i[loaded starting running].freeze
+      RELOAD_STATES = %i[idle pending updating rolling_back failed].freeze
+      DISPATCH_BLOCKING_RELOAD_STATES = %i[updating rolling_back].freeze
+
+      attr_reader :lex_name, :gem_name, :active_version, :state, :reload_state, :hot_reloadable,
+                  :latest_installed_version, :spec, :gem_dir, :loaded_features, :actors, :routes, :tools, :absorbers,
+                  :runners, :loaded_at, :last_error
+
+      def initialize(**attrs)
+        lex_name = attrs.fetch(:lex_name)
+        spec = attrs[:spec]
+        @lex_name = lex_name.to_s
+        @gem_name = (attrs[:gem_name] || lex_name).to_s
+        @spec = spec
+        @active_version = normalize_version(attrs[:active_version] || spec&.version)
+        @latest_installed_version = normalize_version(attrs[:latest_installed_version] || attrs[:installed_version] || @active_version)
+        @state = normalize_state(attrs.fetch(:state, :registered))
+        @reload_state = normalize_reload_state(attrs.fetch(:reload_state, :idle))
+        @hot_reloadable = attrs[:hot_reloadable] == true
+        @gem_dir = attrs[:gem_dir] || spec&.gem_dir
+        @loaded_features = Array(attrs.fetch(:loaded_features, [])).dup.freeze
+        @actors = Array(attrs.fetch(:actors, [])).dup.freeze
+        @routes = Array(attrs.fetch(:routes, [])).dup.freeze
+        @tools = Array(attrs.fetch(:tools, [])).dup.freeze
+        @absorbers = Array(attrs.fetch(:absorbers, [])).dup.freeze
+        @runners = Array(attrs.fetch(:runners, [])).dup.freeze
+        @loaded_at = attrs.fetch(:loaded_at, Time.now)
+        @last_error = attrs[:last_error]
+      end
+
+      def loaded?
+        LOADED_STATES.include?(state)
+      end
+
+      def running?
+        state == :running
+      end
+
+      def pending_reload?
+        return false if active_version.nil? || latest_installed_version.nil?
+
+        latest_installed_version > active_version
+      end
+
+      def dispatchable?
+        DISPATCHABLE_STATES.include?(state) && !DISPATCH_BLOCKING_RELOAD_STATES.include?(reload_state)
+      end
+
+      def with(**attrs)
+        self.class.new(**to_h, **attrs)
+      end
+
+      def to_h
+        {
+          lex_name:                 lex_name,
+          gem_name:                 gem_name,
+          active_version:           active_version,
+          latest_installed_version: latest_installed_version,
+          state:                    state,
+          reload_state:             reload_state,
+          hot_reloadable:           hot_reloadable,
+          spec:                     spec,
+          gem_dir:                  gem_dir,
+          loaded_features:          loaded_features,
+          actors:                   actors,
+          routes:                   routes,
+          tools:                    tools,
+          absorbers:                absorbers,
+          runners:                  runners,
+          loaded_at:                loaded_at,
+          last_error:               last_error
+        }
+      end
+
+      private
+
+      def normalize_version(value)
+        return nil if value.nil?
+        return value if value.is_a?(Gem::Version)
+
+        Gem::Version.new(value.to_s)
+      end
+
+      def normalize_state(value)
+        normalized = value.to_sym
+        return normalized if STATES.include?(normalized)
+
+        raise ArgumentError, "unknown extension state: #{value.inspect}"
+      end
+
+      def normalize_reload_state(value)
+        normalized = value.to_sym
+        return normalized if RELOAD_STATES.include?(normalized)
+
+        raise ArgumentError, "unknown extension reload state: #{value.inspect}"
+      end
+    end
+  end
+end

data/lib/legion/extensions/handle_registry.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/handle'
+
+module Legion
+  module Extensions
+    class HandleRegistry
+      def initialize
+        @handles = {}
+        @mutex = Mutex.new
+      end
+
+      def register(lex_name, **attrs)
+        key = normalize_name(lex_name)
+        @mutex.synchronize do
+          current = @handles[key]
+          @handles[key] = current ? current.with(**attrs) : Handle.new(lex_name: key, **attrs)
+        end
+      end
+
+      def transition(lex_name, state)
+        update(lex_name, state: state)
+      end
+
+      def update(lex_name, **attrs)
+        key = normalize_name(lex_name)
+        @mutex.synchronize do
+          current = @handles[key] || Handle.new(lex_name: key)
+          @handles[key] = current.with(**attrs)
+        end
+      end
+
+      def fetch(lex_name)
+        @mutex.synchronize { @handles[normalize_name(lex_name)] }
+      end
+
+      def all
+        @mutex.synchronize { @handles.values.dup }
+      end
+
+      def running
+        all.select(&:running?)
+      end
+
+      def loaded
+        all.select(&:loaded?)
+      end
+
+      def dispatch_allowed?(lex_name)
+        handle = fetch(lex_name)
+        return true unless handle
+
+        handle.dispatchable?
+      end
+
+      def delete(lex_name)
+        @mutex.synchronize { @handles.delete(normalize_name(lex_name)) }
+      end
+
+      def reset!
+        @mutex.synchronize { @handles.clear }
+      end
+
+      private
+
+      def normalize_name(lex_name)
+        lex_name.to_s
+      end
+    end
+  end
+end

data/lib/legion/extensions.rb

@@ -2,6 +2,7 @@
 
 require 'legion/extensions/core'
 require 'legion/extensions/catalog'
+require 'legion/extensions/handle_registry'
 require 'legion/extensions/permissions'
 require 'legion/runner'
 
@@ -22,6 +23,7 @@ module Legion
         @actors = []
         @running_instances = Concurrent::Array.new
         @loaded_extensions = []
+        reset_runtime_handles!
         @pending_registrations = Concurrent::Array.new
 
         find_extensions
@@ -33,7 +35,7 @@ module Legion
           hook_phase_actors(phase_num)
         end
 
-        @loaded_extensions&.each { |name| Catalog.transition(name, :running) }
+        transition_loaded_extensions(:running)
         Catalog.flush_persisted_transitions
 
         load_yaml_agents
@@ -47,7 +49,7 @@ module Legion
         deadline = Legion::Settings.dig(:extensions, :shutdown_timeout) || 15
         shutdown_start = Time.now
 
-        @loaded_extensions.each { |name| Catalog.transition(name, :stopping) }
+        transition_loaded_extensions(:stopping)
 
         if @subscription_pool
           @subscription_pool.shutdown
@@ -100,10 +102,7 @@ module Legion
 
         Legion::Dispatch.shutdown if defined?(Legion::Dispatch) && Legion::Dispatch.instance_variable_get(:@dispatcher)
 
-        @loaded_extensions.each do |name|
-          Catalog.transition(name, :stopped)
-          unregister_capabilities(name)
-        end
+        transition_loaded_extensions(:stopped) { |name| unregister_capabilities(name) }
         Legion::Logging.info "Successfully shut down all actors (#{(Time.now - shutdown_start).round(1)}s)"
       end
 
@@ -146,6 +145,8 @@ module Legion
           end
 
           Catalog.register(gem_name)
+          register_extension_handle(gem_name, state:                    :registered,
+                                              latest_installed_version: latest_installed_version(gem_name))
           entry
         end
 
@@ -211,9 +212,11 @@ module Legion
         results.each_with_index do |result, idx|
           if result
             Catalog.transition(result[:gem_name], :loaded)
+            transition_extension_handle(result[:gem_name], :loaded)
             register_in_registry(gem_name: result[:gem_name], version: result[:version])
             @loaded_extensions.push(result[:gem_name])
           else
+            transition_extension_handle(eligible[idx][:gem_name], :failed)
             Legion::Logging.warn("#{eligible[idx][:gem_name]} failed to load")
           end
         end
@@ -275,14 +278,6 @@ module Legion
         has_logger = extension.respond_to?(:log)
         extension.autobuild
 
-        require 'legion/transport/messages/lex_register'
-        registration = Legion::Transport::Messages::LexRegister.new(function: 'save', opts: extension.runners)
-        if @pending_registrations
-          @pending_registrations << registration
-        else
-          registration.publish
-        end
-
         register_capabilities(entry[:gem_name], extension.runners) if extension.respond_to?(:runners)
         write_lex_cli_manifest(entry, extension)
         register_absorber_capabilities(entry[:gem_name], extension.absorbers) if extension.respond_to?(:absorbers)
@@ -301,6 +296,14 @@ module Legion
         extension.log.info "Loaded v#{extension::VERSION}"
         Legion::Events.emit('extension.loaded', name: ext_name, version: entry[:gem_name])
 
+        require 'legion/transport/messages/lex_register'
+        registration = Legion::Transport::Messages::LexRegister.new(function: 'save', opts: extension.runners)
+        if @pending_registrations
+          @pending_registrations << registration
+        else
+          registration.publish
+        end
+
         begin
           if defined?(Legion::Data) && defined?(Legion::Data::Model::DigitalWorker)
             worker_id = "lex-#{ext_name}"
@@ -320,6 +323,8 @@ module Legion
           Legion::Logging.debug "Extensions#load_extension failed to register digital worker for #{ext_name}: #{e.message}" if defined?(Legion::Logging)
           nil
         end
+        register_extension_handle(entry[:gem_name], spec: entry[:spec], state: :loaded, loaded_at: Time.now,
+                                                    latest_installed_version: latest_installed_version(entry[:gem_name]))
         true
       rescue StandardError => e
         Legion::Logging.log_exception(e, lex: entry[:gem_name], component_type: :boot)
@@ -599,9 +604,12 @@ module Legion
       public
 
       def loaded_extension_modules
+        handles = extension_handles
+        active_names = handles.select(&:dispatchable?).map(&:lex_name)
         constants(false).filter_map do |const_name|
           mod = const_get(const_name, false)
           next nil unless mod.is_a?(Module) && mod.respond_to?(:runner_modules)
+          next nil if handles.any? && !active_names.include?(module_lex_name(mod))
 
           mod
         rescue StandardError => e
@@ -611,7 +619,11 @@ module Legion
       end
 
       # Legacy capability registration - now handled by Tools::Discovery
-      def unregister_capabilities(_gem_name); end
+      def unregister_capabilities(gem_name)
+        return unless defined?(Legion::Tools::Registry) && Legion::Tools::Registry.respond_to?(:unregister_extension)
+
+        Legion::Tools::Registry.unregister_extension(gem_name)
+      end
 
       def register_absorber_capabilities(_gem_name, _absorbers); end
 
@@ -620,7 +632,10 @@ module Legion
       def gem_load(entry)
         gem_name     = entry[:gem_name]
         require_path = entry[:require_path]
-        gem_dir      = Gem::Specification.find_by_name(gem_name).gem_dir
+        spec         = Gem::Specification.find_by_name(gem_name)
+        gem_dir      = spec.gem_dir
+        entry[:spec] = spec
+        entry[:version] = spec.version.to_s
         require "#{gem_dir}/lib/#{require_path}"
         true
       rescue Gem::MissingSpecError => e
@@ -762,6 +777,82 @@ module Legion
         @extensions
       end
 
+      def loaded_extensions
+        extension_handle_registry.loaded.map(&:lex_name)
+      end
+
+      def extension_handles
+        extension_handle_registry.all
+      end
+
+      def extension_handle(name)
+        extension_handle_registry.fetch(name)
+      end
+
+      def register_extension_handle(name, **attrs)
+        extension_handle_registry.register(name, **attrs)
+      end
+
+      def transition_extension_handle(name, state)
+        extension_handle_registry.transition(name, state)
+      end
+
+      def update_extension_handle(name, **attrs)
+        extension_handle_registry.update(name, **attrs)
+      end
+
+      def reset_runtime_handles!
+        extension_handle_registry.reset!
+      end
+
+      def dispatch_allowed?(lex_name)
+        extension_handle_registry.dispatch_allowed?(normalize_lex_name(lex_name))
+      end
+
+      def dispatch_allowed_for_runner?(runner_class)
+        lex_name = lex_name_for_runner_class(runner_class)
+        return true unless lex_name
+
+        dispatch_allowed?(lex_name)
+      end
+
+      def record_extension_resource(lex_name, resource_type, value)
+        handle = extension_handle(lex_name) || register_extension_handle(normalize_lex_name(lex_name))
+        values = Array(handle.public_send(resource_type))
+        return handle if values.include?(value)
+
+        update_extension_handle(handle.lex_name, resource_type => values + [value])
+      end
+
+      def reload_extension(name)
+        gem_name = normalize_lex_name(name)
+        update_extension_handle(gem_name, reload_state: :updating)
+        unregister_capabilities(gem_name)
+        reset_runner_cache
+
+        entry = @extensions&.find { |candidate| candidate[:gem_name] == gem_name }
+        raise "#{gem_name} failed to reload" if entry && !load_extension(entry)
+
+        update_extension_handle(gem_name, state: :running, reload_state: :idle, last_error: nil,
+                                          latest_installed_version: latest_installed_version(gem_name))
+        true
+      rescue StandardError => e
+        update_extension_handle(gem_name, reload_state: :failed, last_error: e.message)
+        raise
+      end
+
+      def extension_handle_registry
+        @extension_handle_registry ||= HandleRegistry.new
+      end
+
+      def transition_loaded_extensions(state)
+        @loaded_extensions&.each do |name|
+          Catalog.transition(name, state)
+          transition_extension_handle(name, state)
+          yield name if block_given?
+        end
+      end
+
       def load_yaml_agents
         @load_yaml_agents ||= begin
           require 'legion/settings/agent_loader'
@@ -777,6 +868,57 @@ module Legion
 
       private
 
+      def latest_installed_version(gem_name)
+        Gem::Specification.find_all_by_name(gem_name).map(&:version).max
+      rescue StandardError
+        nil
+      end
+
+      def reset_runner_cache
+        return unless defined?(Legion::Ingress) && Legion::Ingress.respond_to?(:reset_runner_cache!)
+
+        Legion::Ingress.reset_runner_cache!
+      end
+
+      def normalize_lex_name(name)
+        str = name.to_s
+        str.start_with?('lex-') ? str : "lex-#{str.tr('.', '-').tr('_', '-')}"
+      end
+
+      def module_lex_name(mod)
+        parts = mod.name.to_s.split('::')
+        idx = parts.index('Extensions')
+        return nil unless idx
+
+        extension_parts = extension_parts_from_const(parts, idx)
+        return nil if extension_parts.empty?
+
+        "lex-#{extension_parts.join('-')}"
+      end
+
+      def lex_name_for_runner_class(runner_class)
+        parts = runner_class.to_s.split('::')
+        idx = parts.index('Extensions')
+        return nil unless idx
+
+        extension_parts = extension_parts_from_const(parts, idx)
+        return nil if extension_parts.empty?
+
+        "lex-#{extension_parts.join('-')}"
+      end
+
+      def extension_parts_from_const(parts, idx)
+        parts[(idx + 1)..].to_a.each_with_object([]) do |part, extension_parts|
+          break extension_parts if %w[Actor Actors Runners Helpers Transport Data Hooks Skills].include?(part)
+
+          extension_parts << camel_to_snake(part).tr('_', '-')
+        end
+      end
+
+      def camel_to_snake(value)
+        value.to_s.gsub(/(?<!^)[A-Z]/) { "_#{Regexp.last_match(0)}" }.downcase
+      end
+
       def default_agents_directory
         custom = Legion::Settings.dig(:agents, :directory)
         return custom if custom && Dir.exist?(custom)

data/lib/legion/ingress.rb

@@ -64,6 +64,14 @@ module Legion
         fn_str = fn.to_s
         raise InvalidFunction, "invalid function format: #{fn_str}" unless fn_str.match?(FUNCTION_PATTERN)
 
+        unless extension_dispatch_allowed?(rc)
+          return {
+            success: false,
+            status:  'task.blocked',
+            error:   { code: 'extension_quiescing', message: "extension for #{rc} is not accepting new work" }
+          }
+        end
+
         # RAI invariant #2: registration precedes permission
         if defined?(Legion::DigitalWorker::Registry) && message[:worker_id]
           Legion::DigitalWorker::Registry.validate_execution!(
@@ -138,8 +146,18 @@ module Legion
         false
       end
 
+      def reset_runner_cache!
+        @registered_runner_modules = nil
+      end
+
       private
 
+      def extension_dispatch_allowed?(runner_class)
+        return true unless defined?(Legion::Extensions) && Legion::Extensions.respond_to?(:dispatch_allowed_for_runner?)
+
+        Legion::Extensions.dispatch_allowed_for_runner?(runner_class)
+      end
+
       def resolve_runner_class(runner_class)
         return runner_class unless runner_class.is_a?(String)
 
@@ -169,10 +187,6 @@ module Legion
         @registered_runner_modules = modules
       end
 
-      def reset_runner_cache!
-        @registered_runner_modules = nil
-      end
-
       def parse_payload(payload)
         case payload
         when Hash

data/lib/legion/tools/discovery.rb

@@ -123,7 +123,9 @@ module Legion
             ext: ext, runner_mod: runner_mod, func_name: func_name,
             meta: meta, defn: defn, deferred: is_deferred
           )
-          Legion::Tools::Registry.register(tool_class)
+          return unless Legion::Tools::Registry.register(tool_class)
+
+          record_tool_owner(ext, tool_class)
         end
 
         def resolve_mcp_tools_enabled(ext, runner_mod)
@@ -214,6 +216,15 @@ module Legion
           end
         end
 
+        def record_tool_owner(ext, tool_class)
+          return unless defined?(Legion::Extensions) && Legion::Extensions.respond_to?(:record_extension_resource)
+
+          ext_name = derive_extension_name(ext)
+          Legion::Extensions.record_extension_resource("lex-#{ext_name.tr('_', '-')}", :tools, tool_class.tool_name)
+        rescue StandardError => e
+          handle_exception(e, level: :warn, handled: true, operation: :record_tool_owner)
+        end
+
         def merge_trigger_words(ext, runner_mod)
           ext_words = ext.respond_to?(:trigger_words) ? Array(ext.trigger_words) : []
 

data/lib/legion/tools/registry.rb

@@ -56,7 +56,8 @@ module Legion
         end
 
         def for_extension(ext_name)
-          all_tools.select { |t| t.respond_to?(:extension) && t.extension == ext_name }
+          normalized = normalize_extension(ext_name)
+          all_tools.select { |t| t.respond_to?(:extension) && normalize_extension(t.extension) == normalized }
         end
 
         def for_runner(runner_name)
@@ -73,6 +74,22 @@ module Legion
             @deferred.clear
           end
         end
+
+        def unregister_extension(ext_name)
+          normalized = normalize_extension(ext_name)
+          @mutex.synchronize do
+            before = @always.size + @deferred.size
+            @always.reject! { |t| t.respond_to?(:extension) && normalize_extension(t.extension) == normalized }
+            @deferred.reject! { |t| t.respond_to?(:extension) && normalize_extension(t.extension) == normalized }
+            before - (@always.size + @deferred.size)
+          end
+        end
+
+        private
+
+        def normalize_extension(ext_name)
+          ext_name.to_s.delete_prefix('lex-').tr('-', '_')
+        end
       end
     end
   end

data/lib/legion/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Legion
-  VERSION = '1.9.0'
+  VERSION = '1.9.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legionio
 version: !ruby/object:Gem::Version
-  version: 1.9.0
+  version: 1.9.2
 platform: ruby
 authors:
 - Esity
@@ -830,6 +830,8 @@ files:
 - lib/legion/extensions/data/model.rb
 - lib/legion/extensions/definitions.rb
 - lib/legion/extensions/gem_source.rb
+- lib/legion/extensions/handle.rb
+- lib/legion/extensions/handle_registry.rb
 - lib/legion/extensions/helpers/base.rb
 - lib/legion/extensions/helpers/cache.rb
 - lib/legion/extensions/helpers/core.rb