rubik 0.1.6 → 0.3.0

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

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Orchestrator
+    module Subagent
+      # Owns the transactional boundary for one subagent spawn. Kept separate
+      # from the root supervisor's query and lifecycle APIs.
+      module SpawnSupervisor
+        RESERVED_ROLE_PROFILES = {
+          "vakanüvis distiller" => "vakanuvis",
+          "context pruner" => "pruner"
+        }.freeze
+
+        CHILD_CONTEXT_COEFFECTS = [
+          Rubik::Coeffects::SUBAGENT_QUESTION_ASKER,
+          Rubik::Coeffects::SUBAGENT_SENDER_ID,
+          Rubik::Coeffects::TASK_CANCELLATION
+        ].freeze
+
+        def spawn(role:, prompt:, type_name: "research", system_prompt: nil,
+                  parent_id: ConversationId::ROOT_ID, workspace: "inherit", model: "inherit",
+                  max_steps: nil, provider: nil, depends_on: nil, reserved_id: nil, owner: nil)
+          role_str = role.to_s.strip
+          prompt_str = prompt.to_s.strip
+          raise ArgumentError, "Subagent role cannot be empty" if role_str.empty?
+          raise ArgumentError, "Subagent prompt cannot be empty" if prompt_str.empty?
+
+          # Issue #125: the owner's task was cancelled — refuse before any
+          # reservation, slot or context work happens.
+          refute_cancelled_owner!(owner)
+
+          # Bağımlı spec doğrudan spawn edilmez: kuyruğa girer (FS/SS
+          # kısıtı), bırakma süpürmesi gerçek koreografiyi oynatır.
+          if depends_on
+            return spawn_batch([{ role: role_str, prompt: prompt_str, type_name: type_name,
+                                  system_prompt: system_prompt, parent_id: parent_id, workspace: workspace,
+                                  model: model, max_steps: max_steps, provider: provider, depends_on: depends_on }],
+                               owner: owner).first[1]
+          end
+
+          created = @monitor.synchronize do
+            validate_concurrency!
+            validate_depth!(parent_id)
+
+            profile_snapshot = resolve_profile_snapshot(type_name: type_name, role: role_str,
+                                                        system_prompt: system_prompt)
+            effective_sys_prompt = profile_snapshot.effective_system_prompt
+            # A profile update must not redirect rollback to a newly provided
+            # init supervisor after this spawn registered its unit.
+            activation_init = init_for_activation
+            # Transcript persistence needs the full custom prompt, whereas an
+            # unchanged built-in prompt can be reconstructed from its type.
+            prompt_reconstructible = system_prompt.to_s.strip.empty? && !profile_snapshot.custom_prompt
+
+            # Queued specs already reserved this id; fresh spawns reserve the
+            # next sequence number here and return it if activation rolls back.
+            generated_id = reserved_id.nil?
+            subagent_id = generated_id ? "subagent-#{@counter + 1}" : reserved_id.to_s
+            id_in_use = @instances.key?(subagent_id) || (@finished || {}).key?(subagent_id)
+            raise ArgumentError, "Subagent id '#{subagent_id}' is already in use." if id_in_use
+
+            @counter += 1 if generated_id
+
+            child_ctx = nil
+            inst = nil
+            begin
+              child_ctx = extend_root_context!(:spawn)
+              effective_buffer = branch_or_inherit_buffer(workspace)
+              scoped_registry = build_scoped_registry(profile_snapshot, child_ctx, effective_buffer)
+              prov, effective_model = resolve_provider_and_model(model)
+              prov = provider if provider
+
+              inst = Instance.new(
+                id: subagent_id, parent_id: parent_id, role: role_str, type_name: profile_snapshot.name,
+                prompt: prompt_str, system_prompt: effective_sys_prompt, workspace: workspace,
+                model: effective_model, context: child_ctx, tool_registry: scoped_registry,
+                provider: prov, buffer_manager: effective_buffer, max_steps: (max_steps || @default_max_steps).to_i,
+                provider_gate: @provider_gate, root_dir: @root_dir, config: @config,
+                context_limit: (@config.respond_to?(:fetch) ? @config.fetch("context.max_tokens", 32_768) : 32_768),
+                event_bus: @event_bus, transcript_storage: absorb_storage, owner_task: owner,
+                prompt_reconstructible: prompt_reconstructible, profile_snapshot: profile_snapshot
+              )
+
+              @instances[subagent_id] = inst
+              activate_instance!(inst, child_ctx: child_ctx, owner_token: owner,
+                                       init_supervisor: activation_init, defer_start: true)
+              raise "Subagent worker start gate could not be released." unless inst.release_start!
+
+              inst
+            rescue StandardError
+              rollback_spawn!(subagent_id: subagent_id, inst: inst, child_ctx: child_ctx,
+                              init_supervisor: activation_init, generated_id: generated_id)
+              raise
+            end
+          end
+          # SS bırakma kancası: yeni başlayan instance, onu bekleyen kuyruk
+          # spesifikasyonlarını serbest bırakır (kilit DIŞINDA — emit kuralı).
+          begin
+            release_ready!
+          rescue StandardError => e
+            Rubik::Log.warn(:orchestrator, "subagent dependency release failed after successful spawn (#{e.class}: #{e.message})")
+          end
+          created
+        end
+
+        private
+
+        def resolve_profile_snapshot(type_name:, role:, system_prompt:)
+          reserved_name = RESERVED_ROLE_PROFILES[role.to_s.downcase.strip]
+          if reserved_name
+            requested = type_name.to_s.downcase.strip
+            unless requested.empty? || requested == "research" || requested == reserved_name
+              raise ReservedProfileError,
+                    "Reserved subagent role '#{role}' must use built-in archetype '#{reserved_name}', not '#{requested}'."
+            end
+
+            type_def = @type_registry.builtins.find { |candidate| candidate.name.to_s.downcase == reserved_name }
+            unless type_def
+              raise ReservedProfileError,
+                    "Reserved subagent role '#{role}' requires built-in archetype '#{reserved_name}', which is unavailable."
+            end
+
+            if !system_prompt.to_s.strip.empty? && system_prompt.to_s != type_def.system_prompt.to_s
+              raise ReservedProfileError, "Reserved subagent role '#{role}' cannot override its built-in system prompt."
+            end
+
+            effective_prompt = type_def.system_prompt
+          else
+            type_def = @type_registry.get(type_name) || @type_registry.get("research")
+            raise ReservedProfileError, "No subagent archetype is available for '#{type_name}'." unless type_def
+
+            effective_prompt = system_prompt.nil? ? type_def.system_prompt : system_prompt
+          end
+
+          snapshot = ProfileSnapshot.capture(type_def, effective_system_prompt: effective_prompt)
+          missing = snapshot.requires.reject do |name|
+            CHILD_CONTEXT_COEFFECTS.include?(name) || !Rubik::Coeffects.get(@root_context, name).nil?
+          end
+          raise UnsatisfiedCoeffectsError.new(snapshot.name, missing) unless missing.empty?
+
+          snapshot
+        end
+
+        def rollback_spawn!(subagent_id:, inst:, child_ctx:, init_supervisor:, generated_id:)
+          @instances.delete(subagent_id) if inst && @instances[subagent_id].equal?(inst)
+
+          begin
+            inst&.abort_start!
+          rescue StandardError => e
+            Rubik::Log.warn(:orchestrator, "subagent spawn thread rollback failed (#{e.class}: #{e.message})")
+          end
+
+          begin
+            init_supervisor&.unregister(inst.unit) if inst&.unit
+          rescue StandardError => e
+            Rubik::Log.warn(:orchestrator, "subagent kernel unit rollback failed (#{e.class}: #{e.message})")
+          end
+
+          begin
+            child_ctx&.dispose
+          rescue StandardError => e
+            Rubik::Log.warn(:orchestrator, "subagent context rollback failed (#{e.class}: #{e.message})")
+          end
+
+          @counter -= 1 if generated_id && subagent_id == "subagent-#{@counter}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Orchestrator
+    module Subagent
+      # Owns the parked worker gate used to make subagent startup reversible.
+      module StartGate
+        def start_async(defer_start: false, &on_complete)
+          run_gate = Queue.new
+          @monitor.synchronize do
+            return false if @thread&.alive?
+
+            @started_at = Time.now
+            @run_started_monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            @run_started_step = @budget.current_step
+            @run_seq += 1
+            @start_aborted = false
+            @start_gate = run_gate
+            transition!(:running)
+            @unit&.sync_state!
+          end
+
+          ready = Queue.new
+          thread = Thread.new do
+            Thread.handle_interrupt(Object => :never) do
+              ready << true # cleanup is armed before cancellation is enabled
+              Thread.handle_interrupt(Object => :immediate) do
+                run_execution_cycle if run_gate.pop == :start
+              end
+            ensure
+              aborted = @monitor.synchronize { @start_aborted }
+              @ended_at ||= Time.now
+              if aborted
+                cleanup_context
+              else
+                profile_name = @profile_snapshot&.name || @type_name
+                profile_version = @profile_snapshot ? @profile_snapshot.profile_version.to_s : "unknown"
+                @journal&.record_run_finished(run: @run_seq, state: @state.to_s, result: @result,
+                                              result_ref: (result_ref if settled?), outcome: @state.to_s,
+                                              error_summary: @last_error,
+                                              duration_ms: ((Process.clock_gettime(Process::CLOCK_MONOTONIC) -
+                                                @run_started_monotonic) * 1000).round,
+                                              step_count: [@budget.current_step - @run_started_step, 0].max,
+                                              profile_name: profile_name, profile_version: profile_version)
+                save_transcript! if @transcript_path.nil?
+                @cancelled_by_operator ? cleanup : cleanup_context
+                on_complete&.call(self)
+              end
+            end
+          end
+          @monitor.synchronize { @thread = thread }
+          ready.pop
+          release_start! unless defer_start
+          true
+        rescue StandardError
+          abort_start!
+          raise
+        end
+
+        # The spawn transaction releases the worker only after every
+        # fallible registration step has completed.
+        def release_start!
+          @monitor.synchronize do
+            return false unless @start_gate && !@start_aborted
+
+            profile_name = @profile_snapshot&.name || @type_name
+            profile_version = @profile_snapshot ? @profile_snapshot.profile_version.to_s : "unknown"
+            @journal&.record_run_started(run: @run_seq, role: @role, type: @type_name, prompt: @prompt,
+                                         profile_name: profile_name, profile_version: profile_version)
+            @start_gate << :start
+            @start_gate = nil
+          end
+          true
+        end
+
+        def abort_start!
+          thread = @monitor.synchronize do
+            @start_aborted = true
+            gate = @start_gate
+            @start_gate = nil
+            gate << :abort if gate
+            @thread
+          end
+
+          if thread && thread != Thread.current
+            thread.join(0.5)
+            if thread.alive?
+              thread.kill
+              thread.join
+            end
+          end
+          cleanup_context
+          true
+        end
+      end
+    end
+  end
+end

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

@@ -4,6 +4,8 @@ require "monitor"
 require_relative "../../platform"
 require_relative "../task_cancellation"
 require_relative "type_registry"
+require_relative "profile_snapshot"
+require_relative "spawn_transaction"
 require_relative "instance"
 require_relative "result_archive"
 require_relative "execution_reads"
@@ -44,6 +46,7 @@ module Rubik
         include DependencySupervisor
         include MessagingSupervisor
         include ActivationSupervisor
+        include SpawnSupervisor
         include ExecutionReads
         include TaskOwnershipSupervisor
         include WaitSupervisor
@@ -60,7 +63,7 @@ module Rubik
           @event_bus = event_bus
           @init = init
 
-          @type_registry = TypeRegistry.new
+          @type_registry = TypeRegistry.new(default_context: @root_context)
           @instances = {}
           @deferred = {}
           @monitor = Monitor.new
@@ -78,72 +81,6 @@ module Rubik
           @root_context.register_disposable { shutdown_all } if @root_context.respond_to?(:register_disposable)
         end
 
-        def spawn(role:, prompt:, type_name: "research", system_prompt: nil,
-                  parent_id: ConversationId::ROOT_ID, workspace: "inherit", model: "inherit",
-                  max_steps: nil, provider: nil, depends_on: nil, reserved_id: nil, owner: nil)
-          role_str = role.to_s.strip
-          prompt_str = prompt.to_s.strip
-          raise ArgumentError, "Subagent role cannot be empty" if role_str.empty?
-          raise ArgumentError, "Subagent prompt cannot be empty" if prompt_str.empty?
-
-          # Issue #125: the owner's task was cancelled — refuse before any
-          # reservation, slot or context work happens.
-          refute_cancelled_owner!(owner)
-
-          # Bağımlı spec doğrudan spawn edilmez: kuyruğa girer (FS/SS
-          # kısıtı), bırakma süpürmesi gerçek koreografiyi oynatır.
-          if depends_on
-            return spawn_batch([{ role: role_str, prompt: prompt_str, type_name: type_name,
-                                  system_prompt: system_prompt, parent_id: parent_id, workspace: workspace,
-                                  model: model, max_steps: max_steps, provider: provider, depends_on: depends_on }],
-                               owner: owner).first[1]
-          end
-
-          created = @monitor.synchronize do
-            validate_concurrency!
-            validate_depth!(parent_id)
-
-            type_def = @type_registry.get(type_name) || @type_registry.get("research")
-            effective_sys_prompt = system_prompt || type_def.system_prompt
-            # Transcript sağlık paketi (2026-10-10): etkili prompt yalnızca
-            # builtin archetype default'undan türemişse kurulabilirdir →
-            # kalıcı dosyada meta stub yeterli. Çağıranın kendi system_prompt'i
-            # veya custom tip prompt'u tek kayıttır → bire bir kopya kalır.
-            prompt_reconstructible = system_prompt.to_s.strip.empty? && !type_def.custom_prompt
-
-            child_ctx = extend_root_context!(:spawn)
-            effective_buffer = branch_or_inherit_buffer(workspace)
-            scoped_registry = build_scoped_registry(type_def, child_ctx, effective_buffer)
-            prov, effective_model = resolve_provider_and_model(model)
-            prov = provider if provider
-
-            # Kuyruktan bırakılan spec kendi REZERVE id'siyle doğar — modelin
-            # depends_on/wait referansı kopmaz. Taze spawn yalnız sayaç ilerletir.
-            subagent_id = reserved_id || "subagent-#{@counter += 1}"
-
-            inst = Instance.new(
-              id: subagent_id, parent_id: parent_id, role: role_str, type_name: type_def.name,
-              prompt: prompt_str, system_prompt: effective_sys_prompt, workspace: workspace,
-              model: effective_model, context: child_ctx, tool_registry: scoped_registry,
-              provider: prov, buffer_manager: effective_buffer, max_steps: (max_steps || @default_max_steps).to_i,
-              provider_gate: @provider_gate, root_dir: @root_dir, config: @config,
-              context_limit: (@config.respond_to?(:fetch) ? @config.fetch("context.max_tokens", 32_768) : 32_768),
-              event_bus: @event_bus, transcript_storage: absorb_storage, owner_task: owner,
-              prompt_reconstructible: prompt_reconstructible
-            )
-
-            @instances[subagent_id] = inst
-            activate_instance!(inst, child_ctx: child_ctx, owner_token: owner)
-            inst
-          end
-          # SS bırakma kancası: yeni başlayan instance, onu bekleyen kuyruk
-          # spesifikasyonlarını serbest bırakır (kilit DIŞINDA — emit kuralı).
-          release_ready!
-          created
-        end
-
-        # Tombstone + kuyruk dahil arama: reap/rezervasyon sonrası da
-        # status/transcript/list sorgulanır.
         def get(id) = @monitor.synchronize { @instances[id.to_s] || (@finished ||= {})[id.to_s] || queued_spec(id.to_s) }
 
         def extend_budget(id, steps = Budget::DEFAULT_GRANT_STEPS)

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Orchestrator
+    module Subagent
+      # Registered archetype representing a subagent role profile, baseline
+      # system prompt, capability filtering policies, and lifecycle revision.
+      TypeDefinition = Struct.new(
+        :name,
+        :description,
+        :system_prompt,
+        :requires, :grants,
+        :tool_filter,
+        :enable_write_tools, :enable_subagent_tools, :custom_prompt,
+        :revision, :context, :handle,
+        keyword_init: true
+      )
+
+      # Internal tracking struct for a single archetype registration revision.
+      Registration = Struct.new(:revision, :name, :type_def, :handle, :context, :active, keyword_init: true)
+
+      # Handle returned by dynamic archetype registration, allowing explicit
+      # reversible cleanup and exposing lifecycle revision metadata. Delegates
+      # all profile properties to the underlying TypeDefinition.
+      class RegistrationHandle
+        attr_reader :revision, :type_def, :context, :registry, :name
+
+        def initialize(revision:, type_def:, context:, registry:)
+          @revision = revision
+          @type_def = type_def
+          @context = context
+          @registry = registry
+          @name = type_def.name
+          @active = true
+        end
+
+        def active?
+          @active
+        end
+
+        def undo
+          return false unless @active
+
+          @registry.unregister_dynamic(self)
+        end
+        alias unregister undo
+
+        def to_type_def
+          @type_def
+        end
+
+        def handle
+          self
+        end
+
+        def description = @type_def.description
+        def system_prompt = @type_def.system_prompt
+        def tool_filter = @type_def.tool_filter
+        def requires = @type_def.requires
+        def grants = @type_def.grants
+        def enable_write_tools = @type_def.enable_write_tools
+        def enable_subagent_tools = @type_def.enable_subagent_tools
+        def custom_prompt = @type_def.custom_prompt
+
+        def is_a?(klass)
+          klass == TypeDefinition || klass == RegistrationHandle || super
+        end
+        alias kind_of? is_a?
+
+        def respond_to_missing?(mid, include_private = false)
+          @type_def.respond_to?(mid, include_private) || super
+        end
+
+        def method_missing(mid, *, &)
+          if @type_def.respond_to?(mid)
+            @type_def.public_send(mid, *, &)
+          else
+            super
+          end
+        end
+      end
+    end
+  end
+end