rubik 0.1.0

data/lib/rubik/orchestrator/subagent/reuse.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative "reaper"
+
+module Rubik
+  module Orchestrator
+    module Subagent
+      # Subagent reuse (context preserved redeploy): bitmiş bir subagent'a
+      # (completed/failed, thread ölmüş) aynı kimlik ve birikmiş LLM
+      # history'si ile YENİ görev verilir — taze spawn + yeniden açıklama
+      # maliyeti yok. maestro doktrininin temel taşı.
+      module Redeploy
+        # Sadece terminal VE thread'i ölmüş stateler: ölü thread, run'ın
+        # ensure bloğunun (save_transcript! → cleanup_context →
+        # on_complete) TAMAMEN çalıştığını kanıtlar — redeploy kendi
+        # tamamlanma işleyişiyle yarışamaz. settled? = :completed/:failed
+        # (Instance'ın lifecycle sözlüğü); :disposed bilinçli dışarıda.
+        def terminal_and_settled?
+          settled? && !@thread&.alive?
+        end
+
+        def redeployable?
+          terminal_and_settled? && !@archived
+        end
+
+        # Issue #55 3.2 buffer: a steering message for a finished-but-unreaped
+        # instance. Check and push under ONE monitor acquisition — the
+        # reaper's archive! shares this monitor, so an archive between a
+        # redeployable? check and the push (which would strand the message
+        # in a wiped history) cannot interleave. No grant branches here: the
+        # redeploy mints a fresh budget, and a settled instance must not
+        # resurrect.
+        def buffer_for_redeploy(message, sender: nil)
+          @monitor.synchronize do
+            return false unless redeployable?
+
+            @inbox.push(Instance::InboxMessage.new(message, sender))
+            true
+          end
+        end
+
+        # Operator diagnostics for the reap path: queued steering that died
+        # with the instance instead of being delivered by a redeploy.
+        def pending_redeploy_messages?
+          @monitor.synchronize { !@inbox.empty? }
+        end
+
+        # Sadece sıfırlama — @state'i ASLA çevirme; :running flip'i ve
+        # thread başlatmayı start_async sahiplenir (flip-sonrası-start
+        # hatası penceresi olmasın). Budget taze mint edilir (bitmiş
+        # run'ın exhausted bayrağı taşıyabilir), ölü child ctx yerine yenisi
+        # ve taze scoped registry bağlanır (eskisinin ask_question'ı
+        # dispose'lu ctx'e rebind'lıydı). Yeni görev history'ye user
+        # mesajı olarak eklenir; run cycle yalnız BOŞ history seed eder.
+        def redeploy_for!(prompt:, max_steps:, context:, tool_registry:)
+          @monitor.synchronize do
+            return false unless redeployable?
+
+            drain_inbox_into_history
+            @history << { role: "user", content: "[New task from maestro]: #{prompt}" }
+            @prompt = prompt.to_s
+            @budget = Budget.new(max_steps: max_steps.to_i)
+            # @result reset is the ONE sanctioned clearer (terminal-only
+            # contract): a new lineage begins. @pause_facts rides along —
+            # the old run's wait fact must not narrate the new one.
+            @result = @last_error = @ended_at = @transcript_path = nil
+            @pause_facts = nil
+            @context = context
+            @tool_registry = tool_registry
+            @context_cleaned_up = false
+            true
+          end
+        end
+      end
+
+      # Supervisor düzlemi: spawn'ın coeffect koreografisini (child ctx,
+      # scoped registry, asker provide, SubagentUnit register, start_async)
+      # ActivationSupervisor TEK seam'den oynatır — spawn ile birebir aynı
+      # düzen: unit kaydı start_async'DEN ÖNCE, derived birth state ile
+      # (settled girişte :pending; ölü-doğan unit tuzağı yapısal olarak
+      # imkânsız — bkz. activation.rb). provider/buffer/provider_gate/
+      # storage_id/kimlik AYNEN KALIR (reuse'un kendisi bu).
+      module RedeploySupervisor
+        def redeploy(id, prompt:, max_steps: nil)
+          prompt_str = prompt.to_s.strip
+          raise ArgumentError, "Redeploy prompt cannot be empty" if prompt_str.empty?
+
+          redeployed = @monitor.synchronize do
+            key = id.to_s
+            inst = @instances[key] || (@finished || {})[key]
+            raise ArgumentError, redeploy_refusal(key, inst) unless inst&.redeployable?
+
+            validate_concurrency!
+            child_ctx = extend_root_context!(:redeploy)
+            scoped_registry = build_scoped_registry(@type_registry.get(inst.type_name), child_ctx, inst.buffer_manager)
+            return false unless inst.redeploy_for!(prompt: prompt_str, max_steps: (max_steps || @default_max_steps).to_i,
+                                                   context: child_ctx, tool_registry: scoped_registry)
+
+            @finished&.delete(inst.id)
+            @instances[inst.id] = inst
+            activate_instance!(inst, child_ctx: child_ctx)
+          end
+          # SS bırakma kancası: redeploy da bir başlangıçtır — taze :running
+          # flip'i, bu id'yi SS ile bekleyen kuyruk spesifikasyonlarını
+          # bırakır (kilit DIŞINDA — emit kuralı; spawn ile aynı düzen).
+          release_ready!
+          redeployed
+        end
+
+        private
+
+        # Reddetme gerekçesi durum-bazlı yönlendirme içerir: maestro doğru
+        # aksiyona (steer / wait / taze spawn) yönelsin.
+        def redeploy_refusal(id, inst)
+          return "Subagent '#{id}' not found." unless inst
+          return "Subagent '#{id}' is archived (reaped) — spawn a fresh subagent via invoke_subagent." if inst.archived?
+
+          if inst.settled?
+            "Subagent '#{id}' is still settling (completion handling in flight); retry shortly."
+          else
+            "Subagent '#{id}' is #{inst.state} with a live thread — steer it (send_message / extend_budget) or kill it first."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubik/orchestrator/subagent/scoped_registry.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Orchestrator
+    module Subagent
+      # Supervisor'dan çıkarılan araç kapsamlandırıcı (satır sınırı, G-plan
+      # hygiene cap'leri): archetype filtresiyle subagent kayıt defterini
+      # kurar ve branch-workspace araçlarını yeni buffer'a bağlar.
+      module ScopedRegistry
+        module_function
+
+        # K7 (plan 2026-10-04) + context-pruner (2026-10-09): kronikçinin ve
+        # budayıcının masaları yalnız kök/maestro düzlemine aittir —
+        # subagent kayıt defterlerine ('self' klonu dahil, çünkü onun
+        # filtresi yalnız spawn setini dışlar) asla kopyalanmaz. Orkestrasyon
+        # belleği tek elde kalır.
+        ROOT_ONLY_TOOLS = ["prune_context", "vakanuvis", "update_goal_ledger"].freeze
+
+        def build(source_registry:, type_def:, child_ctx:, buffer:, parent_buffer:)
+          return nil unless source_registry
+
+          new_reg = Rubik::Tools::Registry.new(coeffect_ctx: child_ctx)
+          filter = type_def.tool_filter
+
+          source_registry.list.each do |tool|
+            next if ROOT_ONLY_TOOLS.include?(tool.name)
+            next unless filter.nil? || filter.call(tool.name)
+
+            new_reg.register(bind_tool_buffer(tool, buffer, ctx: child_ctx, parent_buffer: parent_buffer))
+          end
+          new_reg
+        end
+
+        # Buffer-bound tools (rebuilt only when a branch buffer splits them
+        # off the parent); everything else is context-rebind territory.
+        BUFFER_BOUND_TOOLS = ["read_file", "write_file", "replace_file_content", "apply_buffer"].freeze
+
+        # Buffer rebinding must preserve runtime-context coeffect reads
+        # (rubik://goal/state, rubik://storage, subagent transcripts resolve
+        # through ctx): a branch-workspace coder still shares the session's
+        # live state.
+        def bind_tool_buffer(tool, buffer, ctx: nil, parent_buffer: nil)
+          return rebind_to_context(tool, ctx) unless BUFFER_BOUND_TOOLS.include?(tool.name)
+          return tool unless buffer && buffer != parent_buffer
+
+          case tool.name
+          when "read_file" then Rubik::Tools::ReadFileTool.new(buffer, runtime_context: ctx)
+          when "write_file" then Rubik::Tools::WriteFileTool.new(buffer)
+          when "replace_file_content" then Rubik::Tools::ReplaceFileContentTool.new(buffer)
+          else Rubik::Tools::ApplyBufferTool.new(buffer)
+          end
+        end
+
+        # Subagent düzlemine geçen araçlar (ask_question + send_message):
+        # her ikisinin de coeffect çözümü yalnız child ctx'te sağlanır
+        # (supervisor#spawn/redeploy provide). The rebind MUST precede the
+        # buffer guard conceptually: research-type subagents inherit
+        # workspace buffers, but ask_question still has to swap to the child
+        # ctx — otherwise it would keep the ROOT tool (live shell) and pop a
+        # HUMAN dialog from the worker thread; send_message swaps so the
+        # subagent-plane message carries its REAL sender id to the maestro.
+        # Class-matched (not name-matched): a plugin/dynamic tool registered
+        # under the same name keeps its own implementation in every plane.
+        def rebind_to_context(tool, ctx)
+          return tool unless ctx.respond_to?(:get)
+
+          case tool
+          when Rubik::Tools::AskQuestionTool
+            Rubik::Tools::AskQuestionTool.new(shell: nil, runtime_context: ctx)
+          when Rubik::Tools::SendMessageTool
+            Rubik::Tools::SendMessageTool.new(runtime_context: ctx)
+          else
+            tool
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubik/orchestrator/subagent/step_runner.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../../prompt"
+require_relative "../../tools/truncator"
+require_relative "../provider_recovery"
+require_relative "../auto_apply"
+require_relative "../tool_call_id"
+require_relative "../tool_history"
+require_relative "../turn_executor"
+require_relative "../turn_executor/subagent_channel"
+require_relative "../../coeffects"
+require_relative "notices"
+require_relative "resilience"
+require_relative "conversation_id"
+
+module Rubik
+  module Orchestrator
+    module Subagent
+      # Step execution loop, compaction evaluation, emergency recovery, and tool dispatch
+      # extracted from Instance to satisfy module hygiene and maintain vertical cohesion (Plan 95);
+      # budget state is reached only through the shared Budget collaborator (Candidate 04).
+      # Response processing itself is shared with the user channel through the TurnExecutor
+      # spine (agent-turn-executor plan); this module keeps the invocation path, budget
+      # mechanics, and the subagent dispatch.
+      module StepRunner
+        # The shared response-processing spine, built lazily on first use so
+        # objects that skip initialize (test doubles) stay safe.
+        def turn_executor
+          @turn_executor ||= Rubik::Orchestrator::TurnExecutor.new(
+            channel: Rubik::Orchestrator::TurnExecutor::SubagentChannel.new(self)
+          )
+        end
+
+        def execute_steps_with_provider
+          turn_executor.reset!
+          loop do
+            while !@budget.exhausted? && executing?
+              @budget.consume
+              drain_inbox_into_history
+              inject_step_marker
+              evaluate_subagent_context_compaction!
+
+              opts = { tools: (@tool_registry.respond_to?(:schemas) ? @tool_registry.schemas : []) }
+              opts[:model] = @model unless @model.nil? || @model == "inherit"
+
+              begin
+                raw_response = invoke_provider_with_recovery(opts)
+              rescue StandardError => e
+                if Resilience.transient_error?(e) && auto_pause_on_error?
+                  break unless pause_on_error!(e)
+
+                  next
+                end
+                raise e
+              end
+
+              terminal = turn_executor.call(raw_response)
+              return if terminal
+            end
+
+            break unless executing? && @budget.exhausted?
+            break unless pause_and_await_budget_expansion!
+          end
+        end
+
+        # Public seams for the SubagentChannel adapter (a separate object —
+        # it cannot reach this module's context). Recording the outcome and
+        # transitioning stay paired here so the lifecycle's only-mutation-
+        # path doctrine holds.
+        def complete_turn!(result)
+          @result = result
+          transition!(:completed)
+        end
+
+        def fail_turn!(reason)
+          @last_error = reason
+          transition!(:failed)
+        end
+
+        def evaluate_subagent_context_compaction!
+          return unless @context_limit&.positive?
+
+          context_cfg = ProviderRecovery.compaction_config(@config)
+          needs = Rubik::Prompt::ContextCompactor.needs_compaction?(
+            @history, context_limit: @context_limit, max_output_tokens: @max_output_tokens, config: context_cfg
+          )
+          return unless needs
+
+          compacted = Rubik::Prompt::ContextCompactor.compact_history(
+            @history, context_limit: @context_limit, max_output_tokens: @max_output_tokens, config: context_cfg
+          )
+          @history.replace(compacted)
+        end
+
+        def invoke_provider_with_recovery(opts)
+          ProviderRecovery.with_recovery(config: @config, compact: method(:emergency_compact_and_notify!)) do
+            Resilience.retry_transient(config: @config, gate: @provider_gate) do
+              invoke_provider(opts)
+            end
+          end
+        end
+
+        def auto_pause_on_error?
+          @config.respond_to?(:fetch) ? @config.fetch("subagents.auto_pause_on_network_error", true) != false : true
+        end
+
+        # Compaction actuator for the subagent path (mirrors Loop's public
+        # seam of the same name): the compaction body lives in
+        # TurnExecutor#emergency_compact! (one home for both channels); this
+        # delegates and the channel announces on the bus. Runs on the worker
+        # thread between monitor sections — never call it while holding
+        # @monitor (the emit stays lock-free).
+        def emergency_compact_and_notify!(reason)
+          turn_executor.emergency_compact!(reason)
+        end
+
+        # The object that owns the fact emits it — outside the monitor, so
+        # subscribers never run under the instance lock.
+        def emit_compacted_event(reason, layer)
+          Notices.emit(@event_bus, Notices::COMPACTED_EVENT, { id: @id, role: @role, state: @state, reason: reason.to_s, layer: layer })
+        end
+
+        def invoke_provider(opts)
+          effective_opts = opts.dup
+          effective_opts[:timeout] ||= ProviderRecovery::SUBAGENT_REQUEST_TIMEOUT
+          effective_opts[:open_timeout] ||= ProviderRecovery::DEFAULT_OPEN_TIMEOUT
+          effective_opts[:context_limit] ||= @context_limit if @context_limit
+          effective_opts[:max_tokens] ||= @max_output_tokens if @max_output_tokens&.positive?
+
+          return @provider.complete(@history, effective_opts) if @provider.respond_to?(:complete)
+          return @provider.chat(@history, **effective_opts) if @provider.respond_to?(:chat)
+
+          raise "Provider #{@provider.class} does not support complete or chat"
+        end
+
+        def drain_inbox_into_history
+          until @inbox.empty?
+            begin
+              entry = @inbox.pop(true)
+              @history << { role: "user", content: "[Message from #{sender_label(entry)}]: #{entry.text}" } if entry
+            rescue ThreadError
+              break
+            end
+          end
+        end
+
+        # İki-düzlem sözleşme: gönderen yoksa ya da makine adı agent-0'sa
+        # model persona'sı maestro ile etiketlenir; subagent gönderenler
+        # (sibling mesajları) kendi id'leriyle görünür.
+        def sender_label(entry)
+          return "maestro" if entry.from.nil? || entry.from == ConversationId::ROOT_ID
+
+          entry.from
+        end
+
+        # Single-call subagent dispatch (the TurnExecutor's per-call seam):
+        # pre-execution auto-apply, timed execution, and the canonical
+        # ToolHistory row — which now carries status + duration_ms like every
+        # other channel (the row-superset delta of the agent-turn-executor
+        # plan; no wire-side formatter reads them, observability only).
+        def execute_subagent_tool_call(tool_call)
+          name = tool_call["tool"]
+          args = tool_call["args"] || {}
+          tool = @tool_registry.respond_to?(:get) ? @tool_registry.get(name) : nil
+          canonical_name = tool ? tool.name : name.to_s.downcase
+
+          auto_apply_buffer!(:pre_execution, tool: canonical_name)
+
+          t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          output, status = dispatch_subagent_tool(tool, name, args)
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round(1)
+          Rubik::Orchestrator::ToolHistory.write(@history, tool_call_id: tool_call["id"], tool_name: name,
+                                                           status: status, duration_ms: duration_ms, content: output.to_s)
+          nil
+        end
+
+        # The subagent's own spelling of the shared auto-apply policy (AutoApply
+        # owns the decision): decide, apply+sync through the coeffect shell,
+        # and REPORT failures instead of swallowing them — a failed pre-test
+        # apply used to mean tests silently ran on stale disk. The decision
+        # sits OUTSIDE the rescue: a policy bug must fail the subagent as a
+        # code error, not masquerade as a runtime apply failure. Runs on the
+        # worker thread between monitor sections — never call it while
+        # holding @monitor (same discipline as emergency_compact_and_notify!).
+        def auto_apply_buffer!(trigger, tool: nil)
+          return unless AutoApply.apply?(@config, trigger: trigger, subagent: true, tool: tool)
+
+          begin
+            AutoApply.apply_and_sync(@buffer_manager, coeffect_shell)
+            AutoApply.report_conflicts(@event_bus, @buffer_manager,
+                                       id: @id, role: @role, state: @state, trigger: trigger)
+          rescue StandardError => e
+            AutoApply.report_failure(@event_bus, id: @id, role: @role, state: @state,
+                                                 trigger: trigger, reason: "#{e.class}: #{e.message}")
+            # The subagent itself is the actor about to trust the disk (its
+            # next step is usually run_tests) — a parent notice alone keeps
+            # the one participant who could react in the dark.
+            @history << { role: "user",
+                          content: "[AutoApply] buffer auto-apply (#{trigger}) failed: #{e.message}" }
+          end
+        end
+
+        # The subagent's own child context walks the parent chain to the
+        # root-provided :shell, so its applies sync the AST index exactly
+        # like every main-path apply (previously this path never synced).
+        def coeffect_shell
+          Rubik::Coeffects.get(@context, Rubik::Coeffects::SHELL)
+        end
+
+        # Returns [truncated_output, status] so the dispatch site can build
+        # the canonical tool row. Unknown tools and execution errors carry
+        # :error; plain results are :ok (Result-backed tools carry their own).
+        def dispatch_subagent_tool(tool, name, args)
+          return ["Tool '#{name}' is not available in subagent toolset.", :error] unless tool
+
+          raw = tool.execute(args)
+          out_str = raw.respond_to?(:output) ? raw.output.to_s : raw.to_s
+          max_chars = (@config.respond_to?(:fetch) ? @config.fetch("tools.max_output_chars", 12_000) : 12_000) || 12_000
+          max_lines = (@config.respond_to?(:fetch) ? @config.fetch("tools.max_output_lines", 300) : 300) || 300
+          trunc = Rubik::Tools::Truncator.truncate(out_str, max_chars: max_chars.to_i, max_lines: max_lines.to_i)
+          status = raw.respond_to?(:status) ? raw.status : :ok
+          [trunc[:text], status]
+        rescue StandardError => e
+          ["Tool execution error: #{e.class}: #{e.message}", :error]
+        end
+
+        private
+
+        # Plan 109 Faz A: per-step budget transparency replaces the 75%
+        # warning latch — Budget owns the marker string under its lock; the
+        # step loop owns only the history mutation (a conversation fact),
+        # the same split the warning used.
+        def inject_step_marker
+          @history << { role: "user", content: @budget.step_marker }
+        end
+      end
+    end
+  end
+end

data/lib/rubik/orchestrator/subagent/storage_id.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Orchestrator
+    module Subagent
+      # Mints process-unique transcript storage ids (Plan 110, closes #48).
+      #
+      # Display ids restart at "subagent-1" in every process, so bare display
+      # ids collide across sessions sharing a workspace: transcript paths
+      # derived from them let one session's save clobber another's, or serve
+      # a dead run's file as live evidence (2026-09-27 phantom-subagent
+      # incident). A storage id suffixes the display id with three factors:
+      #   * pid — two live processes can never mint the same id;
+      #   * epoch seconds — same-process re-runs (test suites) differ;
+      #   * rand4 — same-second re-mints stay distinct.
+      # Unlike ToolCallId — whose doc scopes it to tool-call id spellings and
+      # whose bounded session histories make rand-only viable — a transcript
+      # filesystem accumulates forever, so uniqueness needs pid + time.
+      module StorageId
+        def self.mint(display_id)
+          "#{display_id}-#{Process.pid}-#{Time.now.to_i}-#{rand(1000..9999)}"
+        end
+      end
+    end
+  end
+end