rubik 0.3.3 → 0.3.4

data/lib/rubik/prompt/doctrine.rb

@@ -18,6 +18,10 @@ module Rubik
     # ToolTeachings/Notices. Byte-identical rendering is pinned by
     # test_prompt_golden_output — reword here = fixture diff there, never
     # a context_builder.rb diff.
+    #
+    # Security Note: All strings and heredocs in this module contain pure
+    # prompt template prose for LLM system context. Backticks (`...`) in prose
+    # are markdown inline-code tags and are never evaluated as shell execution.
     module Doctrine
       module_function
 

data/lib/rubik/repl/commands/agent_execution.rb

@@ -80,107 +80,120 @@ module Rubik
             next resume_suspended_goal(ctx) if args.length == 1 && sub == "resume"
             next list_suspended_goals(ctx) if args.length == 1 && sub == "list"
 
-            custom_steps = nil
-            bad_steps = false
-            filtered_args = []
-            i = 0
-            while i < args.length
-              arg = args[i]
-              if (m = arg.match(/\A--steps=(\d+)\z/))
-                custom_steps = m[1].to_i
-              elsif arg.start_with?("--steps=")
-                # --steps=X ama X sayı değil: flag metne sızmasın.
-                bad_steps = true
-              elsif ["--steps", "-s"].include?(arg)
-                if i + 1 < args.length && args[i + 1] =~ /\A\d+\z/
-                  custom_steps = args[i + 1].to_i
-                  i += 1
-                else
-                  # Değersiz/sayı-olmayan değer: kullanım hatası (sessiz
-                  # yanlış koşu yerine).
-                  bad_steps = true
-                end
-              else
-                filtered_args << arg
-              end
-              i += 1
-            end
-
-            if bad_steps || (custom_steps && custom_steps < 1)
+            parsed = parse_goal_args(args)
+            if !parsed[:valid]
               ctx.out.puts USAGE_GOAL
               ctx.out.puts "⚠️ [Rubik::Goal] --steps pozitif bir tam sayı bekliyor (örn. !goal --steps 200 <hedef>)"
               next
-            end
-
-            goal_text = filtered_args.join(" ").strip
-            if goal_text.empty?
+            elsif parsed[:goal_text].empty?
               ctx.out.puts USAGE_GOAL
               next
             end
 
-            ctx.recorder&.record_user_turn("!goal #{goal_text}")
-            goal_steps = custom_steps || ctx.config.fetch("agent.goal_max_steps", 100).to_i
-            warn_ratio = ctx.config.fetch("agent.warn_at_ratio", 0.75).to_f
-            routed = ctx.router.route(task_type: :goal, prompt: goal_text)
-            ctx.runtime_manager.provide(:llm_client, routed[:provider]) if routed[:provider]
+            execute_goal(ctx, parsed[:goal_text], parsed[:custom_steps])
+          end
+        end
 
-            # Canlı hedef durumu: maestro ve alt ajanlar read_file
-            # rubik://goal/state ile aynı anlık görüntüyü okur. Provide swap
-            # semantiğine sahiptir — tekrarlanan !goal koşuları Ω'ya inverse
-            # yığmaz; session dispose'u tek delete-inverse ile temizler.
-            # event_bus: bitiş olayı (GoalState::FINISH_EVENT) Vakanüvis
-            # kronikçisinin goal kancasına akar (K3) — notice/wake yok.
-            goal_state = Rubik::Orchestrator::GoalState.new(event_bus: ctx.event_bus)
-            goal_state.start!(goal_text, goal_steps)
-            ctx.runtime_manager.provide(Rubik::Coeffects::GOAL_STATE, goal_state)
-
-            # Yapılandırılmış Σ defteri (goal-ledger planı A): knob ON iken
-            # koşuyla doğar, terminal dallarda finalize olur, provide swap
-            # semantiğiyle tekrarlanan !goal koşuları Ω'ya inverse yığmaz.
-            # OFF iken hiçbir yüz kurulmaz (araç/URI/prompt bayt-özdeş).
-            goal_ledger = nil
-            if Rubik::Orchestrator::GoalLedger::Ledger.enabled?(ctx.config)
-              store = Rubik::Coeffects.get(ctx.runtime_manager&.context, Rubik::Coeffects::STORAGE_STORE)
-              dmesg = Rubik::Coeffects.get(ctx.runtime_manager&.context, Rubik::Coeffects::DMESG)
-              goal_ledger = Rubik::Orchestrator::GoalLedger::Ledger.create!(
-                goal_text: goal_text, config: ctx.config, store: store, dmesg: dmesg,
-                event_bus: ctx.event_bus
-              )
-              ctx.runtime_manager.provide(Rubik::Coeffects::GOAL_LEDGER, goal_ledger)
+        private_class_method def self.parse_goal_args(args)
+          custom_steps = nil
+          bad_steps = false
+          filtered_args = []
+          i = 0
+          while i < args.length
+            arg = args[i]
+            if (m = arg.match(/\A--steps=(\d+)\z/))
+              custom_steps = m[1].to_i
+            elsif arg.start_with?("--steps=")
+              # --steps=X ama X sayı değil: flag metne sızmasın.
+              bad_steps = true
+            elsif ["--steps", "-s"].include?(arg)
+              if i + 1 < args.length && args[i + 1] =~ /\A\d+\z/
+                custom_steps = args[i + 1].to_i
+                i += 1
+              else
+                # Değersiz/sayı-olmayan değer: kullanım hatası (sessiz
+                # yanlış koşu yerine).
+                bad_steps = true
+              end
+            else
+              filtered_args << arg
             end
-            # Askı kimliği (issue #106): koşu boyunca SABİT — registry
-            # girdisinin anahtarı ve Σ damgası meta'sının goal_id'si.
-            # (Σ satır id'si her kabulde değişir; kimlik olarak kullanılamaz.)
-            goal_id = "goal-#{Process.pid}-#{SecureRandom.hex(4)}"
+            i += 1
+          end
 
-            ctx.out.puts "[Rubik::Goal] Starting autonomous goal loop (Budget: #{goal_steps} steps) with #{routed[:role]} model (#{routed[:model]})..."
-            ctx.out.puts "[Rubik::Goal] Target: #{goal_text}\n"
+          goal_text = filtered_args.join(" ").strip
+          valid = !bad_steps && (custom_steps.nil? || custom_steps >= 1)
+          { custom_steps: custom_steps, goal_text: goal_text, valid: valid }
+        end
 
-            orchestrator = ctx.orchestrator_loop(
-              provider: routed[:provider],
-              model: routed[:model],
-              max_steps: goal_steps,
-              warn_at_ratio: warn_ratio,
-              context_limit: routed[:context_limit],
-              max_output_tokens: routed[:max_output_tokens],
-              on_step: build_goal_on_step(ctx, goal_state)
-            )
+        private_class_method def self.initialize_goal_ledger(ctx, goal_text)
+          return nil unless Rubik::Orchestrator::GoalLedger::Ledger.enabled?(ctx.config)
 
-            # Plan 53 D-8 yardımcısı: nötr çift + kayıtçı eşlemesi tek yerde.
-            # Session restore kayıtçı OLAYLARINDAN hidrate eder — eşlenmiş
-            # restore için conversation_history VE record_assistant_response
-            # birlikte yazılmalı (başarısızlıkta da).
-            record_goal_pair = build_goal_record_pair(ctx, goal_text)
+          store = Rubik::Coeffects.get(ctx.runtime_manager&.context, Rubik::Coeffects::STORAGE_STORE)
+          dmesg = Rubik::Coeffects.get(ctx.runtime_manager&.context, Rubik::Coeffects::DMESG)
+          goal_ledger = Rubik::Orchestrator::GoalLedger::Ledger.create!(
+            goal_text: goal_text, config: ctx.config, store: store, dmesg: dmesg,
+            event_bus: ctx.event_bus
+          )
+          ctx.runtime_manager.provide(Rubik::Coeffects::GOAL_LEDGER, goal_ledger)
+          goal_ledger
+        end
 
-            # Pruner apply seam: hedef döngüsü de aynı sınırda tohumlanır —
-            # aşamalı budama planı varsa goal promptundan ÖNCE uygulanır.
-            ctx.apply_staged_prune_plan!
+        private_class_method def self.execute_goal(ctx, goal_text, custom_steps)
+          ctx.recorder&.record_user_turn("!goal #{goal_text}")
+          goal_steps = custom_steps || ctx.config.fetch("agent.goal_max_steps", 100).to_i
+          warn_ratio = ctx.config.fetch("agent.warn_at_ratio", 0.75).to_f
+          routed = ctx.router.route(task_type: :goal, prompt: goal_text)
+          ctx.runtime_manager.provide(:llm_client, routed[:provider]) if routed[:provider]
 
-            drive_goal_turn(ctx, orchestrator: orchestrator, goal_state: goal_state,
-                                 goal_ledger: goal_ledger, goal_text: goal_text, goal_id: goal_id,
-                                 record_pair: record_goal_pair,
-                                 start: ->(loop_inst) { loop_inst.run(goal_text, goal_mode: true, conversation_history: ctx.conversation_history) })
-          end
+          # Canlı hedef durumu: maestro ve alt ajanlar read_file
+          # rubik://goal/state ile aynı anlık görüntüyü okur. Provide swap
+          # semantiğine sahiptir — tekrarlanan !goal koşuları Ω'ya inverse
+          # yığmaz; session dispose'u tek delete-inverse ile temizler.
+          # event_bus: bitiş olayı (GoalState::FINISH_EVENT) Vakanüvis
+          # kronikçisinin goal kancasına akar (K3) — notice/wake yok.
+          goal_state = Rubik::Orchestrator::GoalState.new(event_bus: ctx.event_bus)
+          goal_state.start!(goal_text, goal_steps)
+          ctx.runtime_manager.provide(Rubik::Coeffects::GOAL_STATE, goal_state)
+
+          # Yapılandırılmış Σ defteri (goal-ledger planı A): knob ON iken
+          # koşuyla doğar, terminal dallarda finalize olur, provide swap
+          # semantiğiyle tekrarlanan !goal koşuları Ω'ya inverse yığmaz.
+          # OFF iken hiçbir yüz kurulmaz (araç/URI/prompt bayt-özdeş).
+          goal_ledger = initialize_goal_ledger(ctx, goal_text)
+
+          # Askı kimliği (issue #106): koşu boyunca SABİT — registry
+          # girdisinin anahtarı ve Σ damgası meta'sının goal_id'si.
+          # (Σ satır id'si her kabulde değişir; kimlik olarak kullanılamaz.)
+          goal_id = "goal-#{Process.pid}-#{SecureRandom.hex(4)}"
+
+          ctx.out.puts "[Rubik::Goal] Starting autonomous goal loop (Budget: #{goal_steps} steps) with #{routed[:role]} model (#{routed[:model]})..."
+          ctx.out.puts "[Rubik::Goal] Target: #{goal_text}\n"
+
+          orchestrator = ctx.orchestrator_loop(
+            provider: routed[:provider],
+            model: routed[:model],
+            max_steps: goal_steps,
+            warn_at_ratio: warn_ratio,
+            context_limit: routed[:context_limit],
+            max_output_tokens: routed[:max_output_tokens],
+            on_step: build_goal_on_step(ctx, goal_state)
+          )
+
+          # Plan 53 D-8 yardımcısı: nötr çift + kayıtçı eşlemesi tek yerde.
+          # Session restore kayıtçı OLAYLARINDAN hidrate eder — eşlenmiş
+          # restore için conversation_history VE record_assistant_response
+          # birlikte yazılmalı (başarısızlıkta da).
+          record_goal_pair = build_goal_record_pair(ctx, goal_text)
+
+          # Pruner apply seam: hedef döngüsü de aynı sınırda tohumlanır —
+          # aşamalı budama planı varsa goal promptundan ÖNCE uygulanır.
+          ctx.apply_staged_prune_plan!
+
+          drive_goal_turn(ctx, orchestrator: orchestrator, goal_state: goal_state,
+                               goal_ledger: goal_ledger, goal_text: goal_text, goal_id: goal_id,
+                               record_pair: record_goal_pair,
+                               start: ->(loop_inst) { loop_inst.run(goal_text, goal_mode: true, conversation_history: ctx.conversation_history) })
         end
 
         # ------------------------------------------------------------------

data/lib/rubik/repl/commands/agent_providers.rb

@@ -34,173 +34,207 @@ module Rubik
             when "list", "ls", "status"
               render_provider_catalog(ctx)
             when "add"
-              p_name = clean_args[1]&.downcase
-              arg2 = clean_args[2]
-              arg3 = clean_args[3]
-
-              p_type = "openai_compatible"
-              p_endpoint = nil
-
-              if arg2 && (arg2.start_with?("http://") || arg2.start_with?("https://"))
-                p_endpoint = arg2
-              elsif arg2 && arg3
-                p_type = arg2.downcase
-                p_endpoint = arg3
-              end
-
-              if p_name.nil? || p_name.empty? || p_endpoint.nil? || p_endpoint.empty?
-                ctx.out.puts "Usage: !provider add <name> [type] <endpoint_url> " \
-                             "[--key=API_KEY | --key-env=ENV_VAR] [--model=NAME] [--context=LIMIT] [--project|--global]"
-              elsif !p_endpoint.start_with?("http://") && !p_endpoint.start_with?("https://")
-                ctx.out.puts "Error: Endpoint must be a valid HTTP/HTTPS URL (starting with http:// or https://). " \
-                             "Received: '#{p_endpoint}'\nUsage: !provider add <name> [type] <endpoint_url> " \
-                             "[--key=API_KEY | --key-env=ENV_VAR] [--model=NAME] [--context=LIMIT] [--project|--global]"
-              else
-                key_arg = clean_args.find { |a| a.start_with?("--key=") || a.start_with?("--api-key=") }
-                key_env_arg = clean_args.find { |a| a.start_with?("--key-env=") }
-                model_arg = clean_args.find { |a| a.start_with?("--model=") }
-                context_arg = clean_args.find { |a| a.start_with?("--context=") }
-
-                api_key = key_arg&.split("=", 2)&.last
-                key_env = key_env_arg&.split("=", 2)&.last
-                m_name = model_arg ? model_arg.split("=", 2).last : "default"
-                c_limit = context_arg ? context_arg.split("=", 2).last.to_i : 32_768
-
-                normalized_endpoint = if ["openai_compatible", "openai"].include?(p_type)
-                                        Rubik::LLM::OpenAICompatibleProvider.normalize_endpoint(p_endpoint)
-                                      else
-                                        p_endpoint
-                                      end
-
-                p_spec = {
-                  "type" => p_type,
-                  "endpoint" => normalized_endpoint,
-                  "api_key" => api_key,
-                  "api_key_env" => key_env,
-                  "models" => [
-                    { "name" => m_name, "context_limit" => c_limit }
-                  ]
-                }.compact
-
-                res = ctx.config.set("providers.#{p_name}", p_spec, persist: scope)
-                ctx.refresh_llm_registry!
-                next if Base.report_persist_failure(ctx, res, scope)
-
-                ctx.out.puts "Successfully added provider '#{p_name}' (#{p_type} -> #{normalized_endpoint}) " \
-                             "with model '#{m_name}' [#{Base.scope_label(scope)}]."
-              end
+              handle_add_provider(clean_args, ctx, scope)
             when "add-model", "model-add"
-              p_name = clean_args[1]&.downcase
-              m_name = clean_args[2]
-              if p_name.nil? || p_name.empty? || m_name.nil? || m_name.empty?
-                ctx.out.puts "Usage: !provider add-model <provider_name> <model_name> [--context=LIMIT] [--project|--global]"
-              else
-                context_arg = clean_args.find { |a| a.start_with?("--context=") }
-                c_limit = context_arg ? context_arg.split("=", 2).last.to_i : 32_768
-
-                res = ctx.config.upsert_provider_model(p_name, m_name, context_limit: c_limit, persist: scope)
-                ctx.refresh_llm_registry!
-                if res[:ok]
-                  ctx.out.puts "Added model '#{m_name}' (#{c_limit} tokens) to provider '#{p_name}' [#{Base.scope_label(scope)}]."
-                elsif res[:reason] == :unknown_provider
-                  ctx.out.puts "Provider '#{p_name}' not found. Add it first via !provider add."
-                else
-                  Base.report_persist_failure(ctx, res, scope)
-                end
-              end
+              handle_add_provider_model(clean_args, ctx, scope)
             when "remove-model", "model-remove", "model-rm"
-              p_name = clean_args[1]&.downcase
-              m_name = clean_args[2]
-              if p_name.nil? || p_name.empty? || m_name.nil? || m_name.empty?
-                ctx.out.puts "Usage: !provider remove-model <provider_name> <model_name> [--project|--global]"
-              else
-                res = ctx.config.remove_provider_model(p_name, m_name, persist: scope)
-                ctx.refresh_llm_registry!
-                if res[:ok]
-                  ctx.out.puts "Removed model '#{m_name}' from provider '#{p_name}' [#{Base.scope_label(scope)}]."
-                elsif res[:reason] == :unknown_provider
-                  ctx.out.puts "Provider '#{p_name}' not found."
-                else
-                  Base.report_persist_failure(ctx, res, scope)
-                end
-              end
+              handle_remove_provider_model(clean_args, ctx, scope)
             when "set"
-              p_name = clean_args[1]&.downcase
-              field = clean_args[2]&.downcase
-              val = clean_args[3]
-              if p_name.nil? || p_name.empty? || field.nil? || val.nil?
-                ctx.out.puts "Usage: !provider set <name> <endpoint|key|key-env|type|stream|stream_timeout|open_timeout|tool_native|num_ctx> <value> [--project|--global]"
-              else
-                p_spec = ctx.config.provider_spec(p_name)
-                if p_spec.nil?
-                  ctx.out.puts "Provider '#{p_name}' not found."
-                else
-                  case field
-                  when "key", "api_key"
-                    p_spec["api_key"] = val
-                  when "key-env", "key_env", "api_key_env"
-                    p_spec["api_key_env"] = val
-                  when "endpoint", "url", "host"
-                    if !val.start_with?("http://") && !val.start_with?("https://")
-                      ctx.out.puts "Error: Endpoint must be a valid HTTP/HTTPS URL (starting with http:// or https://). Received: '#{val}'"
-                      next
-                    end
-                    p_spec["endpoint"] = val
-                  when "type"
-                    p_spec["type"] = val
-                  else
-                    # Free-form fields (stream, tool_native, num_ctx, ...) are
-                    # typed through parse_scalar_value so "false" becomes a
-                    # real false — a raw "false" String is truthy in Ruby and
-                    # would silently re-enable the flag it means to disable.
-                    p_spec[field] = ctx.config.parse_scalar_value(val)
-                  end
-
-                  res = ctx.config.set("providers.#{p_name}", p_spec, persist: scope)
-                  ctx.refresh_llm_registry!
-                  next if Base.report_persist_failure(ctx, res, scope)
-
-                  ctx.out.puts "Updated provider '#{p_name}' field '#{field}' to '#{val}' [#{Base.scope_label(scope)}]."
-                end
-              end
+              handle_set_provider_field(clean_args, ctx, scope)
             when "remove", "rm", "delete"
-              p_name = clean_args[1]&.downcase
-              if p_name.nil? || p_name.empty?
-                ctx.out.puts "Usage: !provider remove <name> [--project|--global]"
-              else
-                res = ctx.config.remove_provider(p_name, persist: scope)
-                ctx.refresh_llm_registry!
-                if res[:ok]
-                  ctx.out.puts "Removed provider '#{p_name}' [#{Base.scope_label(scope)}]."
-                elsif res[:reason] == :unknown_provider
-                  ctx.out.puts "Provider '#{p_name}' not found."
-                else
-                  Base.report_persist_failure(ctx, res, scope)
-                end
-              end
+              handle_remove_provider(clean_args, ctx, scope)
             when "set-context", "context", "limit"
-              p_name = clean_args[1]&.downcase
-              m_name = clean_args[2]
-              limit_val = clean_args[3]&.to_i
-              if p_name.nil? || p_name.empty? || m_name.nil? || m_name.empty? || limit_val.nil? || limit_val <= 0
-                ctx.out.puts "Usage: !provider set-context <provider> <model> <limit_in_tokens> [--project|--global]"
-              else
-                res = ctx.config.upsert_provider_model(p_name, m_name, context_limit: limit_val, persist: scope)
-                ctx.refresh_llm_registry!
-                if res[:ok]
-                  ctx.out.puts "Updated context limit for model '#{m_name}' on provider '#{p_name}' to #{limit_val} tokens [#{Base.scope_label(scope)}]."
-                elsif res[:reason] == :unknown_provider
-                  ctx.out.puts "Provider '#{p_name}' not found."
-                else
-                  Base.report_persist_failure(ctx, res, scope)
-                end
-              end
+              handle_set_provider_context(clean_args, ctx, scope)
             else
               ctx.out.puts USAGE_PROVIDER
             end
           end
         end
 
+        private_class_method def self.handle_add_provider(clean_args, ctx, scope)
+          p_name = clean_args[1]&.downcase
+          arg2 = clean_args[2]
+          arg3 = clean_args[3]
+
+          p_type = "openai_compatible"
+          p_endpoint = nil
+
+          if arg2 && (arg2.start_with?("http://") || arg2.start_with?("https://"))
+            p_endpoint = arg2
+          elsif arg2 && arg3
+            p_type = arg2.downcase
+            p_endpoint = arg3
+          end
+
+          if p_name.nil? || p_name.empty? || p_endpoint.nil? || p_endpoint.empty?
+            ctx.out.puts "Usage: !provider add <name> [type] <endpoint_url> " \
+                         "[--key=API_KEY | --key-env=ENV_VAR] [--model=NAME] [--context=LIMIT] [--project|--global]"
+            return
+          end
+
+          unless p_endpoint.start_with?("http://") || p_endpoint.start_with?("https://")
+            ctx.out.puts "Error: Endpoint must be a valid HTTP/HTTPS URL (starting with http:// or https://). " \
+                         "Received: '#{p_endpoint}'\nUsage: !provider add <name> [type] <endpoint_url> " \
+                         "[--key=API_KEY | --key-env=ENV_VAR] [--model=NAME] [--context=LIMIT] [--project|--global]"
+            return
+          end
+
+          key_arg = clean_args.find { |a| a.start_with?("--key=") || a.start_with?("--api-key=") }
+          key_env_arg = clean_args.find { |a| a.start_with?("--key-env=") }
+          model_arg = clean_args.find { |a| a.start_with?("--model=") }
+          context_arg = clean_args.find { |a| a.start_with?("--context=") }
+
+          api_key = key_arg&.split("=", 2)&.last
+          key_env = key_env_arg&.split("=", 2)&.last
+          m_name = model_arg ? model_arg.split("=", 2).last : "default"
+          c_limit = context_arg ? context_arg.split("=", 2).last.to_i : 32_768
+
+          normalized_endpoint = if ["openai_compatible", "openai"].include?(p_type)
+                                  Rubik::LLM::OpenAICompatibleProvider.normalize_endpoint(p_endpoint)
+                                else
+                                  p_endpoint
+                                end
+
+          p_spec = {
+            "type" => p_type,
+            "endpoint" => normalized_endpoint,
+            "api_key" => api_key,
+            "api_key_env" => key_env,
+            "models" => [
+              { "name" => m_name, "context_limit" => c_limit }
+            ]
+          }.compact
+
+          res = ctx.config.set("providers.#{p_name}", p_spec, persist: scope)
+          ctx.refresh_llm_registry!
+          return if Base.report_persist_failure(ctx, res, scope)
+
+          ctx.out.puts "Successfully added provider '#{p_name}' (#{p_type} -> #{normalized_endpoint}) " \
+                       "with model '#{m_name}' [#{Base.scope_label(scope)}]."
+        end
+
+        private_class_method def self.handle_add_provider_model(clean_args, ctx, scope)
+          p_name = clean_args[1]&.downcase
+          m_name = clean_args[2]
+          if p_name.nil? || p_name.empty? || m_name.nil? || m_name.empty?
+            ctx.out.puts "Usage: !provider add-model <provider_name> <model_name> [--context=LIMIT] [--project|--global]"
+            return
+          end
+
+          context_arg = clean_args.find { |a| a.start_with?("--context=") }
+          c_limit = context_arg ? context_arg.split("=", 2).last.to_i : 32_768
+
+          res = ctx.config.upsert_provider_model(p_name, m_name, context_limit: c_limit, persist: scope)
+          ctx.refresh_llm_registry!
+          if res[:ok]
+            ctx.out.puts "Added model '#{m_name}' (#{c_limit} tokens) to provider '#{p_name}' [#{Base.scope_label(scope)}]."
+          elsif res[:reason] == :unknown_provider
+            ctx.out.puts "Provider '#{p_name}' not found. Add it first via !provider add."
+          else
+            Base.report_persist_failure(ctx, res, scope)
+          end
+        end
+
+        private_class_method def self.handle_remove_provider_model(clean_args, ctx, scope)
+          p_name = clean_args[1]&.downcase
+          m_name = clean_args[2]
+          if p_name.nil? || p_name.empty? || m_name.nil? || m_name.empty?
+            ctx.out.puts "Usage: !provider remove-model <provider_name> <model_name> [--project|--global]"
+            return
+          end
+
+          res = ctx.config.remove_provider_model(p_name, m_name, persist: scope)
+          ctx.refresh_llm_registry!
+          if res[:ok]
+            ctx.out.puts "Removed model '#{m_name}' from provider '#{p_name}' [#{Base.scope_label(scope)}]."
+          elsif res[:reason] == :unknown_provider
+            ctx.out.puts "Provider '#{p_name}' not found."
+          else
+            Base.report_persist_failure(ctx, res, scope)
+          end
+        end
+
+        private_class_method def self.handle_set_provider_field(clean_args, ctx, scope)
+          p_name = clean_args[1]&.downcase
+          field = clean_args[2]&.downcase
+          val = clean_args[3]
+          if p_name.nil? || p_name.empty? || field.nil? || val.nil?
+            ctx.out.puts "Usage: !provider set <name> <endpoint|key|key-env|type|stream|stream_timeout|open_timeout|tool_native|num_ctx> <value> [--project|--global]"
+            return
+          end
+
+          p_spec = ctx.config.provider_spec(p_name)
+          if p_spec.nil?
+            ctx.out.puts "Provider '#{p_name}' not found."
+            return
+          end
+
+          case field
+          when "key", "api_key"
+            p_spec["api_key"] = val
+          when "key-env", "key_env", "api_key_env"
+            p_spec["api_key_env"] = val
+          when "endpoint", "url", "host"
+            unless val.start_with?("http://") || val.start_with?("https://")
+              ctx.out.puts "Error: Endpoint must be a valid HTTP/HTTPS URL (starting with http:// or https://). Received: '#{val}'"
+              return
+            end
+            p_spec["endpoint"] = val
+          when "type"
+            p_spec["type"] = val
+          else
+            # Free-form fields (stream, tool_native, num_ctx, ...) are
+            # typed through parse_scalar_value so "false" becomes a
+            # real false — a raw "false" String is truthy in Ruby and
+            # would silently re-enable the flag it means to disable.
+            p_spec[field] = ctx.config.parse_scalar_value(val)
+          end
+
+          res = ctx.config.set("providers.#{p_name}", p_spec, persist: scope)
+          ctx.refresh_llm_registry!
+          return if Base.report_persist_failure(ctx, res, scope)
+
+          ctx.out.puts "Updated provider '#{p_name}' field '#{field}' to '#{val}' [#{Base.scope_label(scope)}]."
+        end
+
+        private_class_method def self.handle_remove_provider(clean_args, ctx, scope)
+          p_name = clean_args[1]&.downcase
+          if p_name.nil? || p_name.empty?
+            ctx.out.puts "Usage: !provider remove <name> [--project|--global]"
+            return
+          end
+
+          res = ctx.config.remove_provider(p_name, persist: scope)
+          ctx.refresh_llm_registry!
+          if res[:ok]
+            ctx.out.puts "Removed provider '#{p_name}' [#{Base.scope_label(scope)}]."
+          elsif res[:reason] == :unknown_provider
+            ctx.out.puts "Provider '#{p_name}' not found."
+          else
+            Base.report_persist_failure(ctx, res, scope)
+          end
+        end
+
+        private_class_method def self.handle_set_provider_context(clean_args, ctx, scope)
+          p_name = clean_args[1]&.downcase
+          m_name = clean_args[2]
+          limit_val = clean_args[3]&.to_i
+          if p_name.nil? || p_name.empty? || m_name.nil? || m_name.empty? || limit_val.nil? || limit_val <= 0
+            ctx.out.puts "Usage: !provider set-context <provider> <model> <limit_in_tokens> [--project|--global]"
+            return
+          end
+
+          res = ctx.config.upsert_provider_model(p_name, m_name, context_limit: limit_val, persist: scope)
+          ctx.refresh_llm_registry!
+          if res[:ok]
+            ctx.out.puts "Updated context limit for model '#{m_name}' on provider '#{p_name}' to #{limit_val} tokens [#{Base.scope_label(scope)}]."
+          elsif res[:reason] == :unknown_provider
+            ctx.out.puts "Provider '#{p_name}' not found."
+          else
+            Base.report_persist_failure(ctx, res, scope)
+          end
+        end
+
         private_class_method def self.register_providers_command(shell)
           shell.register_command("providers", description: "List all configured LLM providers, endpoints, and models", audience: :both) do |_args, ctx|
             render_provider_catalog(ctx)