rubik 0.1.0

data/lib/rubik/tools/builtins/pruner.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+require_relative "../output"
+require_relative "../../coeffects"
+
+module Rubik
+  module Tools
+    # Talep düzlemi (context-pruner planı 2026-10-09): maestro'nun pencere
+    # budayıcı masası. İki eylem de Pruner::Harness'e delege olur — 'prune'
+    # asenkron kuyruklanır ve deterministik makbuz döner (maestro turn'ü
+    # asla LLM bekletilmez; plan turn sınırında uygulanır), 'status' tamamen
+    # deterministiktir. Görünürlük: REQUIRES memnuniyetsizse (knob kapalı)
+    # araç model yüzünde görünmez; ROOT_ONLY_TOOLS subagent düzlemlerine
+    # (self dahil) asla kopyalanmaz — kök penceresini yalnız kök budar.
+    # Mimari sınır: tools çekirdeği repl/'e require edemez — harness sınıfı
+    # ana yükleme ağacından (repl.rb → repl/pruner) gelir, burada yalnız
+    # duck-typed çağrılır.
+    class PruneContextTool < BaseTool
+      REQUIRES = [Rubik::Coeffects::PRUNER].freeze
+
+      DECLARATION = Declaration.new(
+        name: "prune_context", aliases: ["pruner"],
+        description: "Clean the ROOT conversation window (semi-deterministic: an LLM proposes a " \
+                     "keep/drop/summarize plan; the harness validates it deterministically and applies " \
+                     "it at the next turn boundary — goal/task turns and recent context are always " \
+                     "preserved): 'prune' (queue a forced prune now; returns a deterministic receipt, " \
+                     "never blocks on the LLM), 'status' (window estimate vs ceiling, staged plan " \
+                     "state, last receipt).",
+        risk: :write, archetypes: [], write_grant: false,
+        maestro_blocked: false, # vakanüvis emsali: budayıcı düzlemi kökte doğrudan
+        params_schema: {
+          type: "object",
+          properties: {
+            action: {
+              type: "string", enum: ["prune", "status"],
+              description: "Operation (default: 'status')."
+            },
+            reason: { type: "string", description: "prune: optional one-line motive recorded in dmesg." }
+          }
+        }
+      )
+
+      def initialize(harness = nil, runtime_context: nil)
+        super(DECLARATION)
+        @harness = harness
+        @runtime_context = runtime_context
+      end
+
+      def execute(args = {})
+        action = (args["action"] || args[:action] || "status").to_s
+        harness = Rubik::Coeffects.resolve(@runtime_context, Rubik::Coeffects::PRUNER, @harness)
+        unless harness
+          return ToolOutput.error("Context pruner is not available: disabled by config " \
+                                  "(subagents.pruner.enabled=false) or the harness is not wired " \
+                                  "(the startup warning / dmesg has the cause).")
+        end
+
+        begin
+          case action
+          when "prune" then harness.prune(reason: arg(args, "reason") || "maestro")
+          when "status" then harness.status_text
+          else ToolOutput.error("Unknown prune_context action '#{action}' (valid: prune, status).")
+          end
+        rescue ArgumentError => e
+          ToolOutput.error("prune_context #{action}: #{e.message}")
+        rescue StandardError => e
+          # Duck-typed dmesg halkası (tools çekirdeği repl/pruner'ı require
+          # edemez — mimari sınır): ring varsa oraya, yoksa Log'a.
+          dmesg = harness.respond_to?(:dmesg) ? harness.dmesg : nil
+          if dmesg.respond_to?(:log)
+            dmesg.log(:repl, :warn, "prune_context #{action} failed: #{e.class}: #{e.message}")
+          else
+            Rubik::Log.warn(:repl, "prune_context #{action} failed: #{e.class}: #{e.message}")
+          end
+          ToolOutput.error("prune_context #{action} failed: #{e.class}: #{e.message} — retry the call " \
+                           "or inspect dmesg(subsystem: 'repl').")
+        end
+      end
+
+      private
+
+      def arg(args, key, default = nil)
+        args[key] || args[key.to_sym] || default
+      end
+    end
+  end
+end

data/lib/rubik/tools/builtins/runtime.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+require_relative "../output"
+require_relative "../../coeffects"
+
+module Rubik
+  module Tools
+    class InspectRuntimeTool < BaseTool
+      DECLARATION = Declaration.new(
+        name: "inspect_runtime", aliases: ["runtime_status", "inspect_fibers"],
+        description: "Inspect the Spatiotemporal Composability runtime state: active/pending fibers, coeffects, registered services, tools, and commands",
+        risk: :read,
+        params_schema: {
+          type: "object",
+          properties: {
+            target: { type: "string", enum: ["all", "fibers", "services", "tools", "commands", "tasks"], description: "Component to inspect (default: all)" }
+          }
+        }
+      )
+      def initialize(runtime_manager = nil, tool_registry = nil, shell = nil)
+        super(DECLARATION)
+        @runtime_manager = runtime_manager
+        @tool_registry = tool_registry
+        @shell = shell
+      end
+
+      def execute(args = {})
+        target = (args["target"] || args[:target] || "all").to_s.downcase
+
+        lines = ["=== Rubik Spatiotemporal Runtime Diagnostics ==="]
+
+        if ["all", "services"].include?(target) && @runtime_manager
+          root_ctx = @runtime_manager.context
+          services = root_ctx.services
+          lines << "\n[Services / Coeffects Active (#{services.size})]:"
+          services.each { |k, v| lines << "  • #{k.to_s.ljust(12)} -> #{v.class}" }
+          lines << "  (LIFO Accumulator Depth: #{root_ctx.disposable_count} inverse disposables)"
+        end
+
+        if ["all", "fibers"].include?(target) && @runtime_manager
+          active = @runtime_manager.active_fibers
+          pending = @runtime_manager.pending_fibers
+          failed = @runtime_manager.fibers.values.select { |f| f.state == :failed }
+          lines << "\n[Fibers (#{active.size} Active, #{pending.size} Pending, #{failed.size} Failed)]:"
+          active.each { |f| lines << "  🟢 ACTIVE : #{f.name} (injects: #{f.inject.join(', ')})" }
+          pending.each do |f|
+            missing = f.inject.reject { |dep| @runtime_manager.context.has?(dep) }
+            lines << "  ⏳ PENDING: #{f.name} (waiting on: #{missing.join(', ')})"
+          end
+          failed.each { |f| lines << "  🔴 FAILED : #{f.name} (error: #{f.last_error&.message})" }
+        end
+
+        if ["all", "tools"].include?(target) && @tool_registry
+          tools = @tool_registry.list
+          lines << "\n[Tool Registry (#{tools.size} Registered Tools)]:"
+          tools.each { |t| lines << "  ⚙ #{t.name.ljust(22)} [#{t.risk}] - #{t.description[0..60]}" }
+        end
+
+        if ["all", "commands"].include?(target) && @shell
+          cmds = @shell.commands
+          lines << "\n[REPL Bang Commands (#{cmds.size} Registered)]:"
+          cmds.sort.each { |name, meta| lines << "  !#{name.ljust(16)} : #{meta[:description]}" }
+        end
+
+        task_mgr = (Rubik::Coeffects.get(@runtime_manager.context, Rubik::Coeffects::TASK_MANAGER) if @runtime_manager&.context.respond_to?(:get))
+        task_mgr ||= @shell.task_manager if @shell.respond_to?(:task_manager)
+
+        if ["all", "tasks"].include?(target) && task_mgr
+          tasks = task_mgr.list
+          lines << "\n[Background Tasks (#{tasks.size} Tracked)]:"
+          if tasks.empty?
+            lines << "  (none)"
+          else
+            tasks.each do |t|
+              dur = t.running? ? "up #{t.uptime.round(1)}s" : "#{t.status} (exit #{t.exit_code})"
+              lines << "  • [#{t.id}] #{t.status.to_s.upcase} (PID #{t.pid}, #{dur}): #{t.command}"
+            end
+          end
+        end
+
+        lines.join("\n")
+      end
+    end
+
+    class ProvideServiceTool < BaseTool
+      DECLARATION = Declaration.new(
+        name: "provide_service", aliases: ["register_service", "add_service"],
+        description: "Provide a runtime service/coeffect into the root context, " \
+                     "triggering reactive state transitions (Pending -> Active) for dependent fibers",
+        risk: :execute, maestro_blocked: false, # root runtime self-evolution plane (TOOLS.md maestro policy)
+        params_schema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Service/coeffect name (e.g. 'database', 'lsp_client', 'mock_api')" },
+            value: { type: "string", description: "Service description or initialization payload" }
+          },
+          required: ["name"]
+        }
+      )
+      def initialize(runtime_manager = nil)
+        super(DECLARATION)
+        @runtime_manager = runtime_manager
+      end
+
+      def execute(args = {})
+        name = (args["name"] || args[:name]).to_s.strip.downcase
+        val = args["value"] || args[:value] || true
+        return ToolOutput.error("Service name cannot be empty.") if name.empty?
+        return ToolOutput.error("Runtime manager is not available.") unless @runtime_manager
+
+        @runtime_manager.provide(name, val)
+        active_count = @runtime_manager.active_fibers.size
+        pending_count = @runtime_manager.pending_fibers.size
+
+        "Service '#{name}' provided to runtime context. Reconciled fibers: #{active_count} Active, #{pending_count} Pending."
+      end
+    end
+  end
+end

data/lib/rubik/tools/builtins/send_message.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+require_relative "../output"
+require_relative "subagent" # SubagentToolHelpers (supervisor resolution)
+require_relative "../../coeffects"
+require_relative "../../orchestrator/subagent/conversation_id"
+
+module Rubik
+  module Tools
+    # Tool for inter-agent messaging between supervisor and subagents (Plan 94).
+    # The subagent plane rebinds this tool to the child ctx (ScopedRegistry),
+    # so a subagent messaging the maestro carries its REAL sender id; the root
+    # plane keeps the machine default sender (agent-0).
+    class SendMessageTool < BaseTool
+      include SubagentToolHelpers
+
+      DECLARATION = Declaration.new(
+        name: "send_message", aliases: ["msg_agent", "tell_subagent"],
+        description: "Send a message or instruction to another agent or subagent by its conversation ID.",
+        risk: :execute, maestro_blocked: false, # steering plane — pointing the orchestrator's workers is orchestration
+        params_schema: {
+          type: "object",
+          properties: {
+            recipient: { type: "string", description: "The recipient subagent conversation ID (e.g. 'subagent-1')" },
+            message: { type: "string", description: "The message content to deliver" },
+            steps: { type: "integer", description: "Optional additional step budget to grant alongside message" }
+          },
+          required: ["recipient", "message"]
+        }
+      )
+      def initialize(supervisor: nil, runtime_context: nil)
+        super(DECLARATION)
+        @supervisor = supervisor
+        @runtime_context = runtime_context
+      end
+
+      def execute(args = {})
+        sup = resolve_supervisor(@supervisor, @runtime_context)
+        return ToolOutput.error("SubagentSupervisor is not available in runtime context.") unless sup
+
+        # Same model-output surface as manage_subagents: the recipient id
+        # goes through the shared dialect normalizer (B5). A multi-id list
+        # is an explicit error — a messaging tool must never silently drop
+        # recipients.
+        list = Rubik::Orchestrator::Subagent::ConversationId.normalize_list(args["recipient"] || args[:recipient])
+        return ToolOutput.error("Missing required parameter 'recipient'.") if list.empty?
+        if list.size > 1
+          return ToolOutput.error(
+            "send_message takes ONE recipient; got #{list.size} (#{list.join(', ')}). " \
+            "Send one message per recipient, or use manage_subagents for roster actions."
+          )
+        end
+
+        recipient = list.first
+        msg = (args["message"] || args[:message]).to_s.strip
+        return ToolOutput.error("Missing required parameter 'message'.") if msg.empty?
+
+        steps = args["steps"] || args[:steps]
+        sender = subagent_sender_id
+        delivered = if sender
+                      sup.send_message(recipient, msg, additional_steps: steps, _sender_id: sender)
+                    else
+                      sup.send_message(recipient, msg, additional_steps: steps)
+                    end
+        return delivery_text(recipient) if delivered == true
+        return queued_text(recipient, steps) if delivered == :queued
+
+        ToolOutput.error(
+          "Subagent '#{recipient}' not found or no longer active. If it recently finished, redeploy it with its " \
+          "context intact: manage_subagents(action: 'redeploy', conversation_id: '#{recipient}', prompt: '<task>') " \
+          "(if the runtime reports it is still settling, retry shortly); a fresh spawn is needed only after it was reaped."
+        )
+      end
+
+      private
+
+      # Subagent düzlemi (rebound araç): gönderen coeffect'i GERÇEK subagent
+      # id'sidir. Kök düzleminde sağlanmaz → Supervisor default'u kalır.
+      def subagent_sender_id
+        return nil unless @runtime_context.respond_to?(:get)
+
+        Rubik::Coeffects.get(@runtime_context, Rubik::Coeffects::SUBAGENT_SENDER_ID)
+      end
+
+      # Kök alias'ına giden mesajın yanıtı kök kişisiyle konuşur ("the
+      # maestro supervisor"), alıcıyı "subagent" diye adlandırmaz.
+      def delivery_text(recipient)
+        root_alias = Rubik::Orchestrator::Subagent::ConversationId.root_alias?(recipient)
+        return "Message successfully delivered to the maestro supervisor." if root_alias
+
+        "Message successfully delivered to subagent '#{recipient}'."
+      end
+
+      # Bitmiş ama henüz reap edilmemiş alıcı: mesaj inbox'ta bekler,
+      # redeploy history'ye boşaltır (Supervisor#send_message :queued).
+      def queued_text(recipient, steps)
+        note = if steps.to_i.positive?
+                 " The requested #{steps}-step grant is NOT applied to a queued message — redeploy mints a fresh budget."
+               else
+                 ""
+               end
+        "Subagent '#{recipient}' has finished; message QUEUED in its inbox and will be delivered when it is " \
+          "redeployed (manage_subagents action: 'redeploy', conversation_id: '#{recipient}'). It is lost if the " \
+          "subagent is reaped first.#{note}"
+      end
+    end
+  end
+end

data/lib/rubik/tools/builtins/show_file.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+require_relative "../output"
+require_relative "../../coeffects"
+require_relative "../../uris"
+
+module Rubik
+  module Tools
+    # Kalıcı depo varlığını OKUMA aracı — iki düzlemli semantik (kullanıcı
+    # kararı 2026-09-30: subagent'ların içeriği kendi bağlamlarına
+    # yüklemesi engellenmemeli):
+    #   • Kök ajan (StepExecutor): tam içerik :user_output event'iyle
+    #     doğrudan KULLANICININ terminaline akar; modele yalnız kısa stub
+    #     döner — "raporu göster" isteklerinde read_file + yeniden yazma
+    #     iki-hop maliyetini (token ×2, yeniden biçimlendirme riski) ortadan
+    #     kaldırır.
+    #   • Subagent düzlemi (dispatch_subagent_tool): display kancası orada
+    #     olmadığından tam içerik ajanın KENDİ bağlamına döner (read_file
+    #     gibi); ekrana basım kök ajana aittir.
+    #
+    # Yalnız rubik://storage URI'leri — gerçek FS yolları read_file'ın
+    # (sandbox'lı) işi. REQUIRES sayesinde storage bağlanmamışken araç
+    # reklam edilmez (StorageTool ile aynı fail-closed gizlenme).
+    class ShowFileTool < BaseTool
+      REQUIRES = [Rubik::Coeffects::STORAGE_STORE].freeze
+
+      # Terminali sflamak yerine dürüst düşüş: büyük varlık pagine edilmeli.
+      # Satır kapısı tek başına yetmez — tek-dev-satırlık gövde (örn. depoya
+      # yazılmış minified JSON) 400 satırın altında kalır; byte kapısı eşlik
+      # eder (review-round 2 bulgusu).
+      MAX_DISPLAY_LINES = 400
+      MAX_DISPLAY_BYTES = 64 * 1024
+
+      DECLARATION = Declaration.new(
+        name: "show_file", aliases: ["show"],
+        description: "Read a stored entity (review report, plan, goal snapshot, note...) from the central " \
+                     "storage database. As the ROOT agent, the full content renders DIRECTLY to the user's " \
+                     "terminal and you only get a one-line stub — use it for 'show/göster' requests instead of " \
+                     "read_file + re-echoing. In a subagent context the full content loads into YOUR context " \
+                     "like read_file (terminal rendering is the root agent's job). Accepts rubik://storage " \
+                     "URIs only, including refs form 'rubik://storage/<project>/refs/<alias>'.",
+        risk: :read,
+        params_schema: {
+          type: "object",
+          properties: {
+            path: { type: "string", description: "Storage URI: 'rubik://storage/<project>/<type>/<id>' or " \
+                                                 "'rubik://storage/<project>/refs/<alias>'; browse via 'rubik://storage/index'" }
+          },
+          required: ["path"]
+        }
+      )
+      def initialize(runtime_context: nil)
+        super(DECLARATION)
+        @runtime_context = runtime_context
+      end
+
+      def execute(args = {})
+        path = (args["path"] || args[:path]).to_s.strip
+        # Yalnız storage şeması: only: kapısı storage dışı her girdiyi
+        # (storagefoo, goal, düz yol...) nil düşürür — ret mesajı bugünküyle
+        # bayt-bayt aynı.
+        out = UriResolver.resolve(path, ctx: @runtime_context, only: Rubik::Uris::STORAGE)
+        if out.nil?
+          return ToolOutput.error("show_file renders rubik://storage URIs only (got '#{path[0, 80]}'). " \
+                                  "For filesystem paths use read_file; browse entities via 'rubik://storage/index'.")
+        end
+
+        return out if out.is_a?(ToolOutput) && out.error?
+
+        content = out.to_s
+        lines = content.lines.size
+        if lines > MAX_DISPLAY_LINES || content.bytesize > MAX_DISPLAY_BYTES
+          return ToolOutput.error("Entity too large to render inline (#{lines} lines / #{content.bytesize} B; " \
+                                  "caps: #{MAX_DISPLAY_LINES} lines / #{MAX_DISPLAY_BYTES} B). " \
+                                  "Use read_file with offset/limit and summarize instead.")
+        end
+
+        ToolOutput.display(content, stub: "Rendered #{lines} lines to the user's terminal: #{Rubik::Uris.storage_relative(path)} " \
+                                          "(you are not expected to know the content; ask read_file only if you must reason about it)")
+      end
+    end
+  end
+end

data/lib/rubik/tools/builtins/skill.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+require_relative "../output"
+require_relative "../../coeffects"
+
+module Rubik
+  module Tools
+    # Level-2 progressive disclosure (agentskills.io): returns the full
+    # SKILL.md body of one skill. Read-only — skills are data and are never
+    # executed here; auxiliary scripts run through run_command like any file.
+    #
+    # Coeffect contract (AGENTS.md §2): declared via REQUIRES as
+    # defense-in-depth — production registers this tool through
+    # Skills::Manager#open_epoch!, which only runs after the skill_manager
+    # coeffect is provided, but a direct/static registration (tests, future
+    # hosts) stays PENDING (hidden from Registry#schemas) until the coeffect
+    # is satisfied — the same gate ListFilesTool uses for context_index.
+    class SkillTool < BaseTool
+      NAME = "skill"
+      REQUIRES = [Rubik::Coeffects::SKILL_MANAGER].freeze
+
+      # Not in Catalog::BUILTINS — Skills::Manager#open_epoch! registers this
+      # tool dynamically with its own ctx inverse; the declaration is real
+      # wherever the tool is registered.
+      DECLARATION = Declaration.new(
+        name: NAME,
+        description: "Load the full instructions of an agent skill by name. Available skills are listed in " \
+                     "the <skills> system-prompt section. Call this before following a skill's guidance; " \
+                     "files under its scripts/, references/ or assets/ directories are read with read_file " \
+                     "relative to the returned skill directory.",
+        risk: :read, maestro_blocked: false,
+        params_schema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Skill name exactly as listed in the <skills> section" }
+          },
+          required: ["name"]
+        }
+      )
+      def initialize(manager = nil, runtime_context: nil)
+        super(DECLARATION)
+        @manager = manager
+        @runtime_context = runtime_context
+      end
+
+      def execute(args = {})
+        manager = Rubik::Coeffects.resolve(@runtime_context, Rubik::Coeffects::SKILL_MANAGER, @manager)
+        return ToolOutput.error("Error: skills manager is not available.") unless manager
+        return ToolOutput.error("Error: skills are disabled (skills.enabled = false).") unless manager.enabled?
+
+        name = (args["name"] || args[:name]).to_s.strip
+        available = manager.all.map(&:name)
+        available_list = available.empty? ? "none" : available.join(", ")
+        return ToolOutput.error("Error: `name` is required. Available skills: #{available_list}.") if name.empty?
+
+        skill = manager.find(name)
+        return ToolOutput.error("Error: unknown skill '#{name}'. Available skills: #{available_list}.") unless skill
+
+        body = manager.body(name)
+        return ToolOutput.error("Error: SKILL.md of '#{name}' could not be read (#{skill.path}).") if body.nil?
+
+        ToolOutput.ok(<<~OUTPUT.strip)
+          Skill '#{skill.name}' (scope: #{skill.scope}, directory: #{skill.root})
+          Files referenced below (scripts/, references/, assets/) are read with read_file / run_command relative to that directory.
+          ---
+          #{body}
+        OUTPUT
+      end
+    end
+  end
+end