rubik 0.3.3 → 0.3.5

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
 
         # ------------------------------------------------------------------
@@ -195,75 +208,16 @@ module Rubik
         # çıktısını bayt-baytına korur.
         private_class_method def self.drive_goal_turn(ctx, orchestrator:, goal_state:, goal_ledger:,
                                                       goal_text:, goal_id:, record_pair:, start:)
-          finalize_ledger = lambda do |status|
-            next unless goal_ledger
-
-            goal_ledger.finalize!(status)
-            goal_state.ledger_id = goal_ledger.snapshot[:storage_id]
-          end
-
-          fail_goal = lambda do |reason, tokens: nil, steps: nil|
-            sanitized = Rubik::Platform.safe_utf8(reason.to_s)
-            steps_used = steps || goal_state.step_count
-            goal_state.fail!(sanitized, tokens: tokens)
-            finalize_ledger.call(:failed)
-            forget_suspended_goal(ctx, goal_id)
-            ctx.out.puts "\n❌ Goal could not be completed: #{sanitized}"
-            record_pair.call("[Goal attempt ended after #{steps_used} steps: #{sanitized}]", tokens: tokens)
-          end
-
-          suspend_goal = lambda do |reason, tokens: nil|
-            attempt = suspended_attempt(ctx, goal_id) + 1
-            goal_state.suspend!(reason, tokens: tokens)
-            goal_ledger&.suspend!(suspend_stamp_meta(goal_state, goal_id, reason, attempt))
-            registry = goal_registry_for(ctx)
-            registry.register(Rubik::Orchestrator::GoalRegistry::Entry.new(
-                                goal_id: goal_id, goal_text: goal_text, loop: orchestrator,
-                                goal_state: goal_state, ledger: goal_ledger, reason: reason.to_s,
-                                suspended_at: Time.now, attempt: attempt
-                              ))
-            ctx.out.puts "\n⏸️ [Rubik::Goal] Suspended after #{goal_state.step_count} steps (transient provider error): #{reason}"
-            ctx.out.puts "   Loop, counters and Σ ledger are preserved — resume with `!goal resume`."
-            record_pair.call("[Goal suspended after #{goal_state.step_count} steps: #{reason}]", tokens: tokens)
-          end
-
           ctx.active_loop = orchestrator
           begin
             res = start.call(orchestrator)
-
-            # Bütçe tükenince sor (execute_free_text simetrisi; aynı knob,
-            # aynı +20). continue_loop boyunca active_loop DOLU kalmalı:
-            # notice yönlendirmesi aktif döngüye bakar (lifecycle.rb
-            # route_subagent_notice) — soruya beklerken gelen subagent
-            # olayları loop inbox'a girer ve devam adımında boşaltılır.
-            auto_extensions = 0
-            max_auto = ctx.config.fetch("agent.goal_auto_continue_limit", 0).to_i
-            while !res[:ok] && res[:error]&.include?("Max steps budget exceeded")
-              if auto_extensions < max_auto
-                auto_extensions += 1
-                ctx.out.puts "\n🤖 [Rubik::Goal] Adım bütçesi doldu (#{res[:error]}). " \
-                             "Otonom devam hakkı (#{auto_extensions}/#{max_auto}) kullanılarak +20 adım ekleniyor..."
-                goal_state.extend!(goal_state.max_steps + 20)
-                res = orchestrator.continue_loop(20, auto: true)
-                next
-              end
-
-              break unless ctx.config.fetch("agent.ask_continue_on_limit", true)
-
-              ctx.out.puts "\n⚠️ [Rubik::Goal] #{res[:error]}"
-              ans = ctx.ask_yes_no(" [Rubik::Goal] +20 adım ile devam edilsin mi?", default: "n")
-              break unless ["y", "yes", "evet"].include?(ans)
-
-              ctx.out.puts " [Rubik::Goal] Adım bütçesi +20 artırılıyor ve hedef sürdürülüyor..."
-              goal_state.extend!(goal_state.max_steps + 20)
-              res = orchestrator.continue_loop(20)
-            end
+            res = handle_goal_budget_extensions(ctx, orchestrator: orchestrator, goal_state: goal_state, res: res)
           rescue Interrupt
             # ^C hedefi 'running' bırakmasın; eşlenmiş kayıt otursun. Interrupt
             # yeniden yükselir — kullanıcı mesajını execute_command basar.
             # Resume üstüne ^C = askıyı terk (terminal :stopped damgası).
             goal_state.stop!("Interrupted by user (^C)")
-            finalize_ledger.call(:stopped)
+            finalize_goal_ledger(goal_ledger, goal_state, :stopped)
             forget_suspended_goal(ctx, goal_id)
             record_pair.call("[Goal attempt interrupted after #{goal_state.step_count} steps]")
             raise
@@ -276,18 +230,92 @@ module Rubik
             # next yerine return: rescue sonrası res'siz terminal
             # eşlemesine düşülmesin.
             if e.respond_to?(:transient?) && e.transient?
-              suspend_goal.call(e.message)
+              suspend_goal_turn(ctx, orchestrator: orchestrator, goal_state: goal_state, goal_ledger: goal_ledger,
+                                     goal_text: goal_text, goal_id: goal_id, record_pair: record_pair, reason: e.message)
             else
-              fail_goal.call(e.message)
+              fail_goal_turn(ctx, goal_state: goal_state, goal_ledger: goal_ledger, goal_id: goal_id,
+                                  record_pair: record_pair, reason: e.message)
             end
             return
           rescue StandardError => e
-            fail_goal.call("#{e.class}: #{e.message}")
+            fail_goal_turn(ctx, goal_state: goal_state, goal_ledger: goal_ledger, goal_id: goal_id,
+                                record_pair: record_pair, reason: "#{e.class}: #{e.message}")
             return
           ensure
             ctx.active_loop = nil
           end
 
+          handle_goal_completion(ctx, res: res, goal_state: goal_state, goal_ledger: goal_ledger,
+                                      goal_id: goal_id, record_pair: record_pair)
+        end
+
+        private_class_method def self.finalize_goal_ledger(goal_ledger, goal_state, status)
+          return unless goal_ledger
+
+          goal_ledger.finalize!(status)
+          goal_state.ledger_id = goal_ledger.snapshot[:storage_id]
+        end
+
+        private_class_method def self.fail_goal_turn(ctx, goal_state:, goal_ledger:, goal_id:, record_pair:,
+                                                     reason:, tokens: nil, steps: nil)
+          sanitized = Rubik::Platform.safe_utf8(reason.to_s)
+          steps_used = steps || goal_state.step_count
+          goal_state.fail!(sanitized, tokens: tokens)
+          finalize_goal_ledger(goal_ledger, goal_state, :failed)
+          forget_suspended_goal(ctx, goal_id)
+          ctx.out.puts "\n❌ Goal could not be completed: #{sanitized}"
+          record_pair.call("[Goal attempt ended after #{steps_used} steps: #{sanitized}]", tokens: tokens)
+        end
+
+        private_class_method def self.suspend_goal_turn(ctx, orchestrator:, goal_state:, goal_ledger:,
+                                                        goal_text:, goal_id:, record_pair:, reason:, tokens: nil)
+          attempt = suspended_attempt(ctx, goal_id) + 1
+          goal_state.suspend!(reason, tokens: tokens)
+          goal_ledger&.suspend!(suspend_stamp_meta(goal_state, goal_id, reason, attempt))
+          registry = goal_registry_for(ctx)
+          registry.register(Rubik::Orchestrator::GoalRegistry::Entry.new(
+                              goal_id: goal_id, goal_text: goal_text, loop: orchestrator,
+                              goal_state: goal_state, ledger: goal_ledger, reason: reason.to_s,
+                              suspended_at: Time.now, attempt: attempt
+                            ))
+          ctx.out.puts "\n⏸️ [Rubik::Goal] Suspended after #{goal_state.step_count} steps (transient provider error): #{reason}"
+          ctx.out.puts "   Loop, counters and Σ ledger are preserved — resume with `!goal resume`."
+          record_pair.call("[Goal suspended after #{goal_state.step_count} steps: #{reason}]", tokens: tokens)
+        end
+
+        private_class_method def self.handle_goal_budget_extensions(ctx, orchestrator:, goal_state:, res:)
+          # Bütçe tükenince sor (execute_free_text simetrisi; aynı knob,
+          # aynı +20). continue_loop boyunca active_loop DOLU kalmalı:
+          # notice yönlendirmesi aktif döngüye bakar (lifecycle.rb
+          # route_subagent_notice) — soruya beklerken gelen subagent
+          # olayları loop inbox'a girer ve devam adımında boşaltılır.
+          auto_extensions = 0
+          max_auto = ctx.config.fetch("agent.goal_auto_continue_limit", 0).to_i
+          while !res[:ok] && res[:error]&.include?("Max steps budget exceeded")
+            if auto_extensions < max_auto
+              auto_extensions += 1
+              ctx.out.puts "\n🤖 [Rubik::Goal] Adım bütçesi doldu (#{res[:error]}). " \
+                           "Otonom devam hakkı (#{auto_extensions}/#{max_auto}) kullanılarak +20 adım ekleniyor..."
+              goal_state.extend!(goal_state.max_steps + 20)
+              res = orchestrator.continue_loop(20, auto: true)
+              next
+            end
+
+            break unless ctx.config.fetch("agent.ask_continue_on_limit", true)
+
+            ctx.out.puts "\n⚠️ [Rubik::Goal] #{res[:error]}"
+            ans = ctx.ask_yes_no(" [Rubik::Goal] +20 adım ile devam edilsin mi?", default: "n")
+            break unless ["y", "yes", "evet"].include?(ans)
+
+            ctx.out.puts " [Rubik::Goal] Adım bütçesi +20 artırılıyor ve hedef sürdürülüyor..."
+            goal_state.extend!(goal_state.max_steps + 20)
+            res = orchestrator.continue_loop(20)
+          end
+          res
+        end
+
+        private_class_method def self.handle_goal_completion(ctx, res:, goal_state:, goal_ledger:,
+                                                             goal_id:, record_pair:)
           if res[:ok]
             active = goal_active_subagent_count(ctx)
             if active.positive?
@@ -297,12 +325,12 @@ module Rubik
               # "Goal Achieved" (field incident 2026-10-05).
               reason = "Goal loop concluded with #{active} active subagent(s) still running — not marked complete"
               goal_state.stop!(reason)
-              finalize_ledger.call(:stopped)
+              finalize_goal_ledger(goal_ledger, goal_state, :stopped)
               ctx.out.puts "\n⚠️ [Rubik::Goal] #{reason}."
               record_pair.call("[Goal attempt ended after #{goal_state.step_count} steps: #{reason}]", tokens: res[:tokens])
             else
               goal_state.complete!(res[:output].to_s, tokens: res[:tokens])
-              finalize_ledger.call(:completed)
+              finalize_goal_ledger(goal_ledger, goal_state, :completed)
               forget_suspended_goal(ctx, goal_id)
               ctx.out.puts "\n🎉 Goal Achieved in #{res[:steps]} steps!"
               ctx.out.puts res[:output]
@@ -316,10 +344,10 @@ module Rubik
             # Başarısızlık eşlemesi yukarıdaki tek hata kanalından akar:
             # GoalState → ledger finalize → kayıtçı çifti, istisna yoluyla
             # aynı sırayla.
-            fail_goal.call(res[:error], tokens: res[:tokens], steps: res[:steps])
+            fail_goal_turn(ctx, goal_state: goal_state, goal_ledger: goal_ledger, goal_id: goal_id,
+                                record_pair: record_pair, reason: res[:error], tokens: res[:tokens], steps: res[:steps])
           end
         end
-
         # ------------------------------------------------------------------
         # !goal resume (issue #106). İki yol, dönüşüm sırasına göre:
         #   1) Oturum kaydında canlı girdi varsa süreç-içi resume — hayatta

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

@@ -110,99 +110,124 @@ module Rubik
           end
         end
 
+        private_class_method def self.handle_list_models(ctx)
+          mode = ctx.config.fetch("router.mode", "auto")
+          def_spec = ctx.config.model_spec(:default)
+          fast_spec = ctx.config.model_spec(:fast)
+          adv_spec = ctx.config.model_spec(:advanced)
+
+          def_limit = ctx.llm_registry.context_limit_for(def_spec["provider"], def_spec["name"])
+          fast_limit = ctx.llm_registry.context_limit_for(fast_spec["provider"], fast_spec["name"])
+          adv_limit = ctx.llm_registry.context_limit_for(adv_spec["provider"], adv_spec["name"])
+
+          def_ep = def_spec["endpoint"] || def_spec["host"] || "cloud"
+          fast_ep = fast_spec["endpoint"] || fast_spec["host"] || "cloud"
+          adv_ep = adv_spec["endpoint"] || adv_spec["host"] || "cloud"
+
+          ctx.out.puts "Model Router Configuration (Mode: #{mode}):"
+          ctx.out.puts "  • default  : #{def_spec['provider']}/#{def_spec['name']} [Context: #{def_limit} tokens] (#{def_ep})"
+          ctx.out.puts "  • fast     : #{fast_spec['provider']}/#{fast_spec['name']} [Context: #{fast_limit} tokens] (#{fast_ep})"
+          ctx.out.puts "  • advanced : #{adv_spec['provider']}/#{adv_spec['name']} [Context: #{adv_limit} tokens] (#{adv_ep})"
+          ctx.out.puts "Global Config  : #{ctx.config.global_config_path}"
+          ctx.out.puts "Project Config : #{ctx.config.project_config_path}"
+        end
+
+        private_class_method def self.handle_route_command(clean_args, ctx, scope)
+          mode = clean_args[1].to_s.downcase
+          if ["auto", "manual"].include?(mode)
+            res = ctx.config.set("router.mode", mode, persist: scope)
+            return if Base.report_persist_failure(ctx, res, scope)
+
+            ctx.out.puts "Router mode set to #{mode} [#{Base.scope_label(scope)}]."
+          else
+            ctx.out.puts "Usage: !model route <auto|manual>"
+          end
+        end
+
+        private_class_method def self.handle_add_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: !model add <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 provider first via !provider add."
+            else
+              Base.report_persist_failure(ctx, res, scope)
+            end
+          end
+        end
+
+        private_class_method def self.handle_context_command(clean_args, ctx, scope)
+          if clean_args.size == 2 && clean_args[1] =~ /^\d+$/
+            def_spec = ctx.config.model_spec(:default)
+            update_context_limit(ctx, scope, def_spec["provider"], def_spec["name"],
+                                 clean_args[1].to_i, "default model #{def_spec['provider']}/#{def_spec['name']}")
+          elsif clean_args.size == 3 && ["default", "fast", "advanced"].include?(clean_args[1].downcase) && clean_args[2] =~ /^\d+$/
+            role = clean_args[1].downcase.to_sym
+            spec = ctx.config.model_spec(role)
+            update_context_limit(ctx, scope, spec["provider"], spec["name"],
+                                 clean_args[2].to_i, "#{role} model #{spec['provider']}/#{spec['name']}")
+          elsif clean_args.size == 4 && clean_args[3] =~ /^\d+$/
+            update_context_limit(ctx, scope, clean_args[1].downcase, clean_args[2],
+                                 clean_args[3].to_i, "#{clean_args[1].downcase}/#{clean_args[2]}")
+          else
+            ctx.out.puts "Usage: !model context <limit> | !model context <default|fast|advanced> <limit> | " \
+                         "!model context <provider> <model> <limit> [--project|--global]"
+          end
+        end
+
+        private_class_method def self.handle_set_role_command(clean_args, ctx, scope)
+          role = clean_args[1].to_s.downcase
+          model_args = clean_args[2..]
+          if model_args.nil? || model_args.empty?
+            ctx.out.puts "Usage: !model set <default|fast|advanced> [<provider>] <model_name> [--project|--global]"
+          else
+            prov, mod = parse_model_args(model_args, ctx)
+            res = ctx.config.set_model_spec(role, provider: prov, name: mod, persist: scope)
+            ctx.resync_llm_route!
+            return if Base.report_persist_failure(ctx, res, scope)
+
+            limit = ctx.llm_registry.context_limit_for(prov, mod)
+            ctx.out.puts "Set model role '#{role}' to #{prov}/#{mod} [Context: #{limit} tokens] [#{Base.scope_label(scope)}]."
+          end
+        end
+
+        private_class_method def self.handle_switch_default_model(clean_args, ctx, scope)
+          prov, mod = parse_model_args(clean_args, ctx)
+          res = ctx.config.set_model_spec(:default, provider: prov, name: mod, persist: scope)
+          ctx.resync_llm_route!
+          return if Base.report_persist_failure(ctx, res, scope)
+
+          limit = ctx.llm_registry.context_limit_for(prov, mod)
+          ctx.out.puts "Switched default model to #{prov}/#{mod} [Context: #{limit} tokens] [#{Base.scope_label(scope)}]."
+        end
+
         private_class_method def self.register_model_command(shell)
           shell.register_command("model",
                                  audience: :both,
                                  description: "Switch or view LLM provider/model roles (default, fast, advanced) with auto-persistence") do |args, ctx|
             scope, clean_args = Base.parse_scope(args)
-
-            if clean_args.empty? || clean_args.first.downcase == "list"
-              mode = ctx.config.fetch("router.mode", "auto")
-              def_spec = ctx.config.model_spec(:default)
-              fast_spec = ctx.config.model_spec(:fast)
-              adv_spec = ctx.config.model_spec(:advanced)
-
-              def_limit = ctx.llm_registry.context_limit_for(def_spec["provider"], def_spec["name"])
-              fast_limit = ctx.llm_registry.context_limit_for(fast_spec["provider"], fast_spec["name"])
-              adv_limit = ctx.llm_registry.context_limit_for(adv_spec["provider"], adv_spec["name"])
-
-              def_ep = def_spec["endpoint"] || def_spec["host"] || "cloud"
-              fast_ep = fast_spec["endpoint"] || fast_spec["host"] || "cloud"
-              adv_ep = adv_spec["endpoint"] || adv_spec["host"] || "cloud"
-
-              ctx.out.puts "Model Router Configuration (Mode: #{mode}):"
-              ctx.out.puts "  • default  : #{def_spec['provider']}/#{def_spec['name']} [Context: #{def_limit} tokens] (#{def_ep})"
-              ctx.out.puts "  • fast     : #{fast_spec['provider']}/#{fast_spec['name']} [Context: #{fast_limit} tokens] (#{fast_ep})"
-              ctx.out.puts "  • advanced : #{adv_spec['provider']}/#{adv_spec['name']} [Context: #{adv_limit} tokens] (#{adv_ep})"
-              ctx.out.puts "Global Config  : #{ctx.config.global_config_path}"
-              ctx.out.puts "Project Config : #{ctx.config.project_config_path}"
-            elsif clean_args.first.downcase == "route"
-              mode = clean_args[1].to_s.downcase
-              if ["auto", "manual"].include?(mode)
-                res = ctx.config.set("router.mode", mode, persist: scope)
-                next if Base.report_persist_failure(ctx, res, scope)
-
-                ctx.out.puts "Router mode set to #{mode} [#{Base.scope_label(scope)}]."
-              else
-                ctx.out.puts "Usage: !model route <auto|manual>"
-              end
-            elsif clean_args.first.downcase == "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: !model add <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 provider first via !provider add."
-                else
-                  Base.report_persist_failure(ctx, res, scope)
-                end
-              end
-            elsif ["context", "limit"].include?(clean_args.first.downcase)
-              if clean_args.size == 2 && clean_args[1] =~ /^\d+$/
-                def_spec = ctx.config.model_spec(:default)
-                update_context_limit(ctx, scope, def_spec["provider"], def_spec["name"],
-                                     clean_args[1].to_i, "default model #{def_spec['provider']}/#{def_spec['name']}")
-              elsif clean_args.size == 3 && ["default", "fast", "advanced"].include?(clean_args[1].downcase) && clean_args[2] =~ /^\d+$/
-                role = clean_args[1].downcase.to_sym
-                spec = ctx.config.model_spec(role)
-                update_context_limit(ctx, scope, spec["provider"], spec["name"],
-                                     clean_args[2].to_i, "#{role} model #{spec['provider']}/#{spec['name']}")
-              elsif clean_args.size == 4 && clean_args[3] =~ /^\d+$/
-                update_context_limit(ctx, scope, clean_args[1].downcase, clean_args[2],
-                                     clean_args[3].to_i, "#{clean_args[1].downcase}/#{clean_args[2]}")
-              else
-                ctx.out.puts "Usage: !model context <limit> | !model context <default|fast|advanced> <limit> | " \
-                             "!model context <provider> <model> <limit> [--project|--global]"
-              end
-            elsif clean_args.first.downcase == "set"
-              role = clean_args[1].to_s.downcase
-              model_args = clean_args[2..]
-              if model_args.nil? || model_args.empty?
-                ctx.out.puts "Usage: !model set <default|fast|advanced> [<provider>] <model_name> [--project|--global]"
-              else
-                prov, mod = parse_model_args(model_args, ctx)
-                res = ctx.config.set_model_spec(role, provider: prov, name: mod, persist: scope)
-                ctx.resync_llm_route!
-                next if Base.report_persist_failure(ctx, res, scope)
-
-                limit = ctx.llm_registry.context_limit_for(prov, mod)
-                ctx.out.puts "Set model role '#{role}' to #{prov}/#{mod} [Context: #{limit} tokens] [#{Base.scope_label(scope)}]."
-              end
+            subcmd = clean_args.first&.downcase
+
+            if clean_args.empty? || subcmd == "list"
+              handle_list_models(ctx)
+            elsif subcmd == "route"
+              handle_route_command(clean_args, ctx, scope)
+            elsif subcmd == "add"
+              handle_add_model(clean_args, ctx, scope)
+            elsif ["context", "limit"].include?(subcmd)
+              handle_context_command(clean_args, ctx, scope)
+            elsif subcmd == "set"
+              handle_set_role_command(clean_args, ctx, scope)
             else
-              prov, mod = parse_model_args(clean_args, ctx)
-              res = ctx.config.set_model_spec(:default, provider: prov, name: mod, persist: scope)
-              ctx.resync_llm_route!
-              next if Base.report_persist_failure(ctx, res, scope)
-
-              limit = ctx.llm_registry.context_limit_for(prov, mod)
-              ctx.out.puts "Switched default model to #{prov}/#{mod} [Context: #{limit} tokens] [#{Base.scope_label(scope)}]."
+              handle_switch_default_model(clean_args, ctx, scope)
             end
           end
         end