rubik 0.1.0

data/lib/rubik/orchestrator/subagent_notice_inbox.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Orchestrator
+    # The Loop-side mailbox for subagent notices (fresh-scan card 4;
+    # ContinuationManager mold: plain constructor, own state, eager init in
+    # Loop#initialize plus a lazy reader for Loop.allocate test doubles).
+    #
+    # Boundary: QUEUE-ONLY. This class owns the thread-safe queue, the
+    # notice-shape validation at entry, and the run/continuation lifecycle
+    # of that queue. It deliberately does NOT render notices
+    # (Subagent::Notices owns the vocabulary) and does NOT merge into
+    # history (Loop owns @history): drain_all hands back validated notice
+    # hashes and the caller renders.
+    #
+    # Threading contract (inherited verbatim from the pre-extraction Loop
+    # code; see also repl/lifecycle.rb handle_subagent_event):
+    # - enqueue runs on subagent worker threads (the bus emit is
+    #   synchronous): validation plus a bare Queue#push, never a lock a
+    #   REPL thread might hold while routing an event.
+    # - drain_all / reset_for_new_run! run on the turn thread between
+    #   steps and may race a concurrent enqueue safely: pop(true) raises
+    #   ThreadError on empty, the race-safe terminator for the
+    #   check-then-act window a conditional loop would miss.
+    # - reset_for_new_run! REASSIGNS the queue (faithful to Loop's old
+    #   `@subagent_notices = Queue.new`), it does not clear it. A notice
+    #   pushed to the old Queue object in the microscopic window between
+    #   the previous run's last drain and the reassign is stranded on the
+    #   dead queue: accepted by design — the user channel already rendered
+    #   its line at enqueue time, and manage_subagents wait remains the
+    #   model's recovery path.
+    class SubagentNoticeInbox
+      def initialize
+        @queue = Queue.new
+      end
+
+      # Entry point and the ONLY mutation path: validate, then push. The
+      # REPL routing seam reaches this via Loop#enqueue_subagent_notice
+      # with Notices.normalize output; this raise is the safety net against
+      # the legacy string dialect. Message pinned verbatim by tests.
+      def enqueue(notice)
+        raise ArgumentError, "subagent notice must be a Hash with :kind, got #{notice.inspect}" unless notice.is_a?(Hash) && notice[:kind]
+
+        @queue.push(notice)
+      end
+
+      # Pops everything pending (FIFO) and returns the notice hashes.
+      # Empty-after-drain by construction; a second call returns [].
+      def drain_all
+        notices = []
+        loop { notices << @queue.pop(true) }
+      rescue ThreadError
+        notices
+      end
+
+      # Non-blocking emptiness probe (GoalWait's wake check). Advisory
+      # only: an enqueue racing this check is caught on the next poll or
+      # drain — Queue#pop remains the authoritative consumer.
+      def empty?
+        @queue.empty?
+      end
+
+      # Per-run lifecycle (Loop#run, aligned with the @history reset):
+      # stale notices from a previous run on a cached Loop instance must
+      # never drain into the fresh history. Reassigns — see the class
+      # comment for the stranding window this preserves on purpose.
+      def reset_for_new_run!
+        @queue = Queue.new
+      end
+
+      # Continuation lifecycle (Loop#continue_loop): an explicit,
+      # contract-carrying no-op. Continuation resumes the same run, so
+      # undelivered notices must survive into the next execute_steps pass.
+      # Retention is the decision — encoding it as a named call at the
+      # continuation seam keeps the run/continue asymmetry greppable in
+      # code instead of living only in a comment inside #run.
+      def keep_for_continuation; end
+    end
+  end
+end

data/lib/rubik/orchestrator/tool_call_id.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Orchestrator
+    # THE single vocabulary home for the orchestrator family's tool-call
+    # id spellings (previously three independent interpolations: Loop's
+    # response normalizer, Subagent::StepRunner, StepExecutor's defensive
+    # fallback). One prefix and joining convention; TWO deliberate
+    # uniqueness policies — the sites' collision realities differ:
+    #
+    # - Loop (unique: true): production builds a fresh Loop per turn while
+    #   the session history persists, so step_count restarts every turn
+    #   and a deterministic "call_3_1" WILL recur inside one history —
+    #   duplicate tool_use ids break strict providers' tool_result
+    #   pairing. The 4-digit random suffix is load-bearing, not decor.
+    # - Subagent StepRunner (deterministic): a subagent's history lives
+    #   and dies with its own run — never restored, never continued — so
+    #   (subagent id, step, index) is unique by construction, and
+    #   determinism keeps ids greppable across subagents in transcripts.
+    # - StepExecutor (unique: true): dead on the production path (the
+    #   TurnExecutor normalizes ids before dispatch) but live on the
+    #   executor's own seam — test doubles call it with bare, id-less tool
+    #   calls, and no turn-local index exists there.
+    #
+    # mint is spelling-only by design: the id PRECEDENCE chain
+    # (tc["id"] || tc[:id] || mint) lives in one place now — the shared
+    # TurnExecutor normalizer — while the mint policy per channel is
+    # supplied through Channel#mint_call_id. Both channels receive fresh
+    # normalized {"id","tool","args"} hashes; the llm/ layer's dumb
+    # call_#{rand} fallbacks stay there: llm must never require
+    # orchestrator (layering).
+    module ToolCallId
+      module_function
+
+      # mint(3, 2)                        -> "call_3_2"
+      # mint("subagent-2", 5, 3)          -> "call_subagent-2_5_3"
+      # mint(4, unique: true)             -> "call_4_4821"
+      # mint(3, 2, unique: true)          -> "call_3_2_4821"
+      # Byte-compatible with every pre-extraction spelling.
+      def mint(*parts, unique: false)
+        id = "call_#{parts.join('_')}"
+        id = "#{id}_#{rand(1000..9999)}" if unique
+        id
+      end
+    end
+  end
+end

data/lib/rubik/orchestrator/tool_circuit_breaker.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+# Opt-in failure isolation for tool execution (G19): after `threshold`
+# consecutive failures of the same tool, short-circuit further calls for a
+# cooldown instead of burning agent steps on a wedged backend. Disabled by
+# default — synchronous execution is the agent loop's design; this only
+# stops repeated futile calls once the operator turns it on.
+module Rubik
+  module Orchestrator
+    class ToolCircuitBreaker
+      # Raised by the StepExecutor when a call is refused; the executor's
+      # normal rescue converts it into a failed tool result so the loop
+      # plumbing (events, history) is reused untouched.
+      class CircuitOpenError < StandardError; end
+
+      STATES = [:closed, :open, :half_open].freeze
+
+      def initialize(threshold: 5, cooldown_seconds: 60.0)
+        @threshold = threshold
+        @cooldown_seconds = cooldown_seconds.to_f
+        @monitor = Monitor.new
+        @tools = {} # name -> { failures:, opened_at:, probing: }
+      end
+
+      def state(tool_name)
+        @monitor.synchronize { circuit(tool_name)[:state] }
+      end
+
+      def allow?(tool_name)
+        @monitor.synchronize do
+          circuit = circuit(tool_name)
+          case circuit[:state]
+          when :open
+            return false unless cooldown_elapsed?(circuit)
+
+            # one probe through the half-open gate
+            circuit[:state] = :half_open
+            circuit[:probing] = true
+            true
+          when :half_open
+            if circuit[:probing]
+              true
+            else
+              cooldown_elapsed?
+            end
+          else
+            true
+          end
+        end
+      end
+
+      def record_success(tool_name)
+        @monitor.synchronize do
+          @tools.delete(tool_name)
+        end
+      end
+
+      def record_failure(tool_name)
+        @monitor.synchronize do
+          circuit = circuit(tool_name)
+          if circuit[:state] == :half_open
+            # probe failed: reopen for another full cooldown
+            circuit[:opened_at] = now
+            circuit[:probing] = false
+            circuit[:state] = :open
+          else
+            circuit[:failures] += 1
+            circuit[:state] = :open if circuit[:failures] >= @threshold
+            circuit[:opened_at] = now if circuit[:state] == :open && circuit[:opened_at].nil?
+          end
+        end
+      end
+
+      private
+
+      def circuit(tool_name)
+        @tools[tool_name] ||= { failures: 0, opened_at: nil, probing: false, state: :closed }
+      end
+
+      def cooldown_elapsed?(circuit)
+        circuit[:opened_at] && (now - circuit[:opened_at]) >= @cooldown_seconds
+      end
+
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/rubik/orchestrator/tool_history.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Orchestrator
+    # THE canonical tool-result history row — the dictionary single source
+    # of truth (agent-turn-executor plan, Phase 1). Every channel's writer
+    # (StepExecutor registered/invalid, MaestroGate refusal, subagent
+    # dispatch) constructs its row through ToolHistory.write, so key drift
+    # between channels is structurally impossible.
+    #
+    # Provider-consumption evidence (formatter.rb et al.):
+    # - tool_call_id — required by OpenAI native function calling
+    #   (formatter.rb, extract_call_id) and Anthropic tool_use pairing;
+    #   also read by TokenEstimator.
+    # - tool_name — OpenAI non-native and Ollama prefixed-user-message
+    #   paths, TokenEstimator, ContextCompactor skill-tool filter,
+    #   TranscriptFormatter.
+    # - status / duration_ms — read by NO wire-side consumer; observability
+    #   only (tests, REPL events, stored transcripts). Formatters build
+    #   fresh hashes and ignore unknown keys, so carrying them everywhere is
+    #   wire-safe for every provider path.
+    # - content — an opaque String per channel (main path: Result#to_xml;
+    #   subagent: truncated plain output). The dictionary unifies the row
+    #   SHAPE, not the content encoding.
+    module ToolHistory
+      ROW_KEYS = [:role, :tool_call_id, :tool_name, :status, :duration_ms, :content].freeze
+
+      module_function
+
+      # Appends exactly one canonical row to +history+ and returns it.
+      def write(history, tool_call_id:, tool_name:, status:, duration_ms:, content:)
+        row = { role: "tool", tool_call_id: tool_call_id, tool_name: tool_name,
+                status: status, duration_ms: duration_ms, content: content }
+        history << row
+        row
+      end
+    end
+  end
+end

data/lib/rubik/orchestrator/turn_executor/subagent_channel.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "../tool_call_id"
+
+module Rubik
+  module Orchestrator
+    class TurnExecutor
+      # The subagent-channel adapter: wraps the Subagent::Instance. Its
+      # methods run on the worker thread only, between monitor sections —
+      # the channel never holds @monitor and never emits on the bus under
+      # it (the same discipline as the StepRunner methods it replaces).
+      class SubagentChannel < Channel
+        def initialize(instance)
+          super()
+          @inst = instance
+        end
+
+        attr_reader :inst
+
+        # ── required state ──
+        def history = @inst.history
+
+        def tool_registry = @inst.tool_registry
+
+        def limits
+          { context_limit: @inst.context_limit, max_output_tokens: @inst.max_output_tokens, config: @inst.config }
+        end
+
+        # Subagent policy (ToolCallId doctrine): deterministic
+        # (subagent id, step, index) — the history lives and dies with the
+        # run, and greppable ids beat collision-proof ones here.
+        def mint_call_id(idx)
+          ToolCallId.mint(@inst.id, @inst.current_step, idx + 1)
+        end
+
+        # ── response shaping ──
+        # Moved verbatim from StepRunner#extract_response_content: Struct
+        # mock providers expose #content, real responses expose #text.
+        def response_text(res)
+          return res.text.to_s if res.respond_to?(:text)
+          return res.content.to_s if res.respond_to?(:content)
+
+          res.to_s
+        end
+
+        # Struct/duck mock providers expose the array attribute without the
+        # Response predicate — read the attribute directly.
+        def raw_tool_calls(res)
+          res.respond_to?(:tool_calls) ? res.tool_calls : []
+        end
+
+        # Deferred: Instance carries no total_tokens state.
+        def track_usage(_res) = nil
+
+        # Deferred: subagent continuation is future work.
+        def handle_truncation(_res, _text, _tool_calls, _finish_reason) = nil
+
+        # ── announce ──
+        def announce_compaction(reason, layer)
+          @inst.emit_compacted_event(reason, layer)
+        end
+
+        def announce_llm_thought(_text) = nil
+
+        # ── terminals & dispatch ──
+        # The shared two-strike nudge policy (Channel#empty_response_turn)
+        # now governs empty, tool-less responses: one standard nudge row,
+        # then the terminal below on the second consecutive strike. The
+        # subagent can no longer "complete" with an empty result — the
+        # declared Phase 4 delta.
+        def empty_response_failure
+          @inst.fail_turn!("Empty response from model (2 consecutive)")
+          { ok: false, completed: false }
+        end
+
+        def final_text_result(final_text)
+          @inst.history << { role: "assistant", content: final_text.empty? ? nil : final_text, tool_calls: nil }
+          @inst.complete_turn!(final_text)
+          { ok: true, completed: true }
+        end
+
+        def append_tool_call_row(final_text, tool_calls)
+          @inst.history << { role: "assistant", content: final_text.empty? ? nil : final_text, tool_calls: tool_calls }
+        end
+
+        def on_finish(args, fallback_text)
+          message = args["message"] || args[:message] || fallback_text || "Completed"
+          @inst.auto_apply_buffer!(:finish) unless @inst.workspace == "branch"
+          @inst.complete_turn!(message)
+          { ok: true, completed: true }
+        end
+
+        def execute_tool_call(tool_call, text)
+          return on_finish(tool_call["args"] || {}, text) if TurnExecutor.finish_call?(@inst.tool_registry, tool_call)
+
+          @inst.execute_subagent_tool_call(tool_call)
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/rubik/orchestrator/turn_executor/user_channel.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require_relative "../shell_deps"
+require_relative "../tool_call_id"
+require_relative "../tool_history"
+
+module Rubik
+  module Orchestrator
+    class TurnExecutor
+      # The user-channel adapter: wraps the Loop through the ShellDeps
+      # façade, so bare Class#allocate-built test loops keep working
+      # (the StepExecutor/BudgetManager/StreamManager precedent). Owns the
+      # user channel's response shaping: continuation stitching, the
+      # truncation/auto-continue flow, thought-aware nudges, step events,
+      # and the turn_result contract.
+      class UserChannel < Channel
+        def initialize(loop_or_deps)
+          super()
+          @deps = ShellDeps.wrap(loop_or_deps)
+        end
+
+        attr_reader :deps
+
+        # ── required state ──
+        def history = @deps.history
+
+        def tool_registry = @deps.tool_registry
+
+        # Observation projection directive (plan D): yalnız goal-mode user
+        # kanalında çözülür; directive_for önkoşul matrisi (knob'lar,
+        # coeffect, rev ≥ 1) sağlanmazsa nil döner → compaction byte-özdeş.
+        def absorb_directive
+          return nil unless @deps.goal_mode?
+
+          Rubik::Orchestrator::GoalLedger::ObservationProjection.directive_for(deps: @deps)
+        end
+
+        def limits
+          { context_limit: @deps.context_limit, max_output_tokens: @deps.max_output_tokens, config: @deps.config }
+        end
+
+        # Loop policy (ToolCallId doctrine): unique-by-suffix ids — the
+        # session history survives across turns while step_count restarts.
+        def mint_call_id(idx)
+          ToolCallId.mint(@deps.step_count, idx + 1, unique: true)
+        end
+
+        # ── response shaping ──
+        # Moved stitch_response: a buffered continuation turn prepends the
+        # accumulated partial text and resets the buffer.
+        def final_text(res, text)
+          cm = @deps.loop_instance.continuation_manager
+          return text if cm.continuation_buffer.empty?
+
+          cm.stitch_and_reset(res.text.to_s)
+        end
+
+        def track_usage(res) = @deps.budget_manager.track_token_usage!(res)
+
+        # Moved truncation/auto-continue flow (Plan 90): classify the
+        # truncation, append the partial thought/text rows plus the
+        # targeted nudge, or return the diagnostic terminal when
+        # auto-continue is disabled or the ceiling is exhausted.
+        def handle_truncation(res, _text_resp, tool_calls, finish_reason)
+          cm = @deps.loop_instance.continuation_manager
+          return nil unless cm.truncation?(finish_reason)
+
+          trunc_action = cm.handle_truncation(
+            finish_reason: finish_reason,
+            text_resp: res.text.to_s,
+            tool_calls: tool_calls,
+            res: res,
+            max_tokens: @deps.max_output_tokens || @deps.safe_config("llm.default_max_output_tokens", 4096)
+          )
+
+          if trunc_action[:continue]
+            nudge_policy.reset!
+            if trunc_action[:thought]
+              @deps.history << { role: "assistant", content: nil, thought: trunc_action[:thought] }
+            elsif trunc_action[:partial_text]
+              @deps.history << { role: "assistant", content: trunc_action[:partial_text] }
+            end
+            @deps.history << { role: "user", content: trunc_action[:nudge] }
+            @deps.on_step&.call(trunc_action[:step_event].merge(step: @deps.step_count, max_steps: @deps.max_steps)) if trunc_action[:step_event]
+            return :consumed
+          end
+          return nil unless trunc_action[:error]
+
+          @deps.on_step&.call(type: :error, content: trunc_action[:error], step: @deps.step_count, max_steps: @deps.max_steps)
+          @deps.loop_instance.turn_result(success: false, error: trunc_action[:error])
+        end
+
+        # ── nudge texts ──
+        # Plan 61 D-11 thought-aware variant: reasoning spent the budget
+        # without an action deserves a different sentence than a blank reply.
+        def empty_nudge_message(res)
+          if res.respond_to?(:thought) && res.thought && !res.thought.to_s.strip.empty?
+            "Your reasoning was completed, but no action or final response was provided. Please call a tool or provide your final output."
+          else
+            super
+          end
+        end
+
+        # ── announce ──
+        def announce_compaction(reason, layer)
+          @deps.on_step&.call(type: :emergency_compact, reason: reason, step: @deps.step_count,
+                              max_steps: @deps.max_steps, layer: layer)
+        end
+
+        def announce_llm_thought(text)
+          @deps.on_step&.call(type: :llm_thought, content: text, step: @deps.step_count, max_steps: @deps.max_steps)
+        end
+
+        # ── terminals & dispatch ──
+        def empty_response_failure
+          @deps.loop_instance.turn_result(success: false, error: "Empty response from model")
+        end
+
+        def final_text_result(final_text)
+          @deps.history << { role: "assistant", content: final_text }
+          @deps.on_step&.call(type: :message, content: final_text, step: @deps.step_count, max_steps: @deps.max_steps)
+          return goal_wait_yield(via: "text") if goal_guard_pending?
+
+          @deps.loop_instance.turn_result(success: true, output: final_text)
+        end
+
+        def append_tool_call_row(final_text, tool_calls)
+          @deps.history << { role: "assistant", content: final_text.empty? ? nil : final_text, tool_calls: tool_calls }
+        end
+
+        def on_finish(args, fallback_text)
+          @deps.loop_instance.step_executor.handle_finish_tool(args, fallback_text)
+        end
+
+        def execute_tool_call(tool_call, text)
+          # Guard BEFORE dispatch: a finish over live subagents must not
+          # reach handle_finish_tool (its auto-apply and :finish event
+          # would celebrate a completion the pipeline has not reached).
+          # The deferred call still gets its canonical result row — the
+          # loop continues, so the next provider request must see the
+          # tool_use paired (strict providers 400 on orphaned ids).
+          if TurnExecutor.finish_call?(@deps.tool_registry, tool_call) && goal_guard_pending?
+            ToolHistory.write(@deps.history,
+                              tool_call_id: tool_call["id"],
+                              tool_name: "finish",
+                              status: :ok,
+                              duration_ms: 0.0,
+                              content: "finish deferred: dispatched subagents still active — the goal stays open")
+            return goal_wait_yield(via: "finish")
+          end
+
+          @deps.loop_instance.step_executor.execute_single_tool_call(tool_call, text)
+        end
+
+        private
+
+        # Goal-mode premature-completion guard (GoalWait): in goal mode a
+        # success terminal while dispatched subagents are still live is a
+        # false "Goal Achieved" (field incident 2026-10-05) — route it
+        # through the implicit yield-and-wait, which returns nil so the
+        # step loop continues. Interactive/default mode never reaches it.
+        def goal_guard_pending?
+          @deps.goal_mode? && @deps.loop_instance.goal_wait.pending?
+        end
+
+        def goal_wait_yield(via:)
+          @deps.loop_instance.goal_wait.premature_yield!(via: via)
+        end
+      end
+    end
+  end
+end