rubik 0.1.0

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

@@ -0,0 +1,359 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+require_relative "../output"
+require_relative "../../runtime"
+
+module Rubik
+  module Tools
+    class ApplyBufferTool < BaseTool
+      # maestro_blocked: false is DECLARED policy, not drift (TOOLS.md maestro
+      # paragraph): apply_buffer is the manual-mode flush of a coder branch's
+      # merge — the root orchestrator persists it directly, and with the gate
+      # off the root edits-and-flushes itself.
+      DECLARATION = Declaration.new(
+        name: "apply_buffer", aliases: ["save_buffer", "commit_changes", "save"],
+        description: "Persist all pending in-memory file buffer modifications to disk immediately (skips files with external conflicts unless force: true)",
+        risk: :write, archetypes: [:coder], write_grant: true, maestro_blocked: false,
+        params_schema: {
+          type: "object",
+          properties: {
+            reason: { type: "string", description: "Optional explanation of why buffer is being applied (e.g. 'prior to running tests')" },
+            force: { type: "boolean",
+                     description: "If true, overwrites disk files even if modified externally by formatters (resolves [CONFLICT])" }
+          }
+        }
+      )
+      def initialize(buffer_manager = nil, shell = nil)
+        super(DECLARATION)
+        @buffer_manager = buffer_manager
+        @shell = shell
+      end
+
+      def execute(args = {})
+        return ToolOutput.error("Buffer manager is not connected.") unless @buffer_manager
+
+        if @shell&.config && @shell.config.fetch("buffer.model_can_apply", true) == false
+          return ToolOutput.error("Model buffer application is disabled by configuration " \
+                                  "(buffer.model_can_apply: false). The human operator will review and apply changes.")
+        end
+
+        force = [true, "true"].include?(args["force"]) || [true, "true"].include?(args[:force]) ||
+                [true, "true"].include?(args["overwrite"]) || [true, "true"].include?(args[:overwrite])
+        policy = force ? "overwrite" : nil
+
+        if @buffer_manager.dirty?
+          applied = @buffer_manager.apply!(policy: policy)
+          conflicts = @buffer_manager.last_conflicts || []
+          @shell&.sync_context_and_ast(applied) unless applied.empty?
+
+          messages = []
+          messages << "Successfully applied #{applied.size} modified file(s) to disk: #{applied.join(', ')}" unless applied.empty?
+          conflicts.each do |c|
+            messages << "[CONFLICT] #{c}: disk content changed since last read — skipped to prevent data loss.\n" \
+                        "To force overwrite with your buffer changes, call: apply_buffer(force: true)\n" \
+                        "Call read_file(path: \"#{c}\", reload: true) to inspect external changes or resolve."
+          end
+
+          if applied.empty? && !conflicts.empty?
+            ToolOutput.error(messages.join("\n"))
+          elsif applied.empty?
+            # Inside the dirty? branch with zero applies and zero conflicts,
+            # every buffered entry was discarded as an invalid path
+            # (apply!'s garbage-skip) — the edits are NOT on disk, and citing
+            # an earlier apply here would be a lie.
+            "No unapplied buffer changes to write: the buffered entries were discarded as invalid paths and are NOT on disk. " \
+              "Re-check the target paths and buffer them again."
+          else
+            messages.join("\n")
+          end
+        else
+          clean_buffer_message
+        end
+      end
+
+      private
+
+      # "Buffer is clean" alone reads as "nothing happened" when an earlier
+      # apply (apply_buffer itself or the auto-apply policy) already flushed
+      # the edits to disk. Surface the last successful apply so the model can
+      # verify against reality instead of re-editing or force-applying
+      # (issue #97 finding 6). When the mode cannot be read, the origin stays
+      # deliberately two-sided rather than inventing a specific cause.
+      def clean_buffer_message
+        last = @buffer_manager.last_applied
+        return "No unapplied buffer changes to write (buffer is clean)." unless last.is_a?(Hash) && Array(last[:paths]).any?
+
+        mode = @shell.respond_to?(:config) && @shell.config.respond_to?(:fetch) ? @shell.config.fetch("buffer.auto_apply", "manual") : nil
+        origin = if !mode.nil? && !mode.to_s.strip.empty? && mode.to_s.downcase != "manual"
+                   "the auto-apply policy (buffer.auto_apply: #{mode})"
+                 else
+                   "an earlier apply_buffer call or the auto-apply policy"
+                 end
+        "No unapplied buffer changes to write (buffer is clean): #{last[:paths].size} file(s) were already written to disk " \
+          "at #{last[:at].utc.iso8601} by #{origin}: #{last[:paths].join(', ')}."
+      end
+    end
+
+    class RepairRuntimeTool < BaseTool
+      DECLARATION = Declaration.new(
+        name: "repair_runtime_service", aliases: ["fix_service", "repair_lsp", "repair_runner", "repair_runtime"],
+        description: "Diagnose, adapt, or synthesize a replacement command/adapter for a failing runtime component " \
+                     "(LSP, test runner, linter, or shell command) with pre-flight verification in an isolated sub-context",
+        risk: :execute, maestro_blocked: false, # runtime self-healing plane (TOOLS.md maestro policy)
+        params_schema: {
+          type: "object",
+          properties: {
+            target: {
+              type: "string",
+              enum: ["lsp", "test_runner", "linter", "command"],
+              description: "Runtime component type to repair or adapt"
+            },
+            language_or_type: {
+              type: "string",
+              description: "Language or service identifier (e.g., 'ruby', 'python', 'rust', 'go', 'zig', 'c', 'bash')"
+            },
+            proposed_command: {
+              type: "string",
+              description: "Replacement or custom command string (optional, probed automatically if auto_probe: true)"
+            },
+            auto_probe: {
+              type: "boolean",
+              description: "Whether to automatically probe system binaries and candidate commands (default: true)"
+            }
+          },
+          required: ["target", "language_or_type"]
+        }
+      )
+      def initialize(runtime_manager: nil, lsp_manager: nil, adapter_registry: nil, overlay_storage: nil, config: nil, root_dir: Dir.pwd,
+                     guard: nil)
+        super(DECLARATION)
+        @runtime_manager = runtime_manager
+        @lsp_manager = lsp_manager
+        @adapter_registry = adapter_registry
+        @overlay_storage = overlay_storage
+        @config = config
+        @root_dir = File.expand_path(root_dir)
+        @guard = guard
+      end
+
+      def execute(args = {})
+        target = (args["target"] || args[:target]).to_s.downcase.strip
+        lang = (args["language_or_type"] || args[:language_or_type]).to_s.downcase.strip
+        proposed_cmd = (args["proposed_command"] || args[:proposed_command]).to_s.strip
+        auto_probe = if args["auto_probe"].nil?
+                       args[:auto_probe].nil? || args[:auto_probe]
+                     else
+                       args["auto_probe"]
+                     end
+
+        return ToolOutput.error("Target and language_or_type must be provided.") if target.empty? || lang.empty?
+
+        # 1. Automatic Probing if proposed_cmd is not specified or auto_probe is requested
+        if proposed_cmd.empty? && auto_probe
+          candidate = case target
+                      when "lsp"
+                        Rubik::Runtime::Discovery.probe_lsp(lang, root_dir: @root_dir)
+                      when "test_runner"
+                        Rubik::Runtime::Discovery.discover_test_runners(root_dir: @root_dir, lang: lang).first
+                      when "linter"
+                        Rubik::Runtime::Discovery.discover_formatters(root_dir: @root_dir, lang: lang).first
+                      when "command"
+                        Rubik::Runtime::Discovery.binary_available?(lang) ? lang : nil
+                      end
+
+          if candidate
+            proposed_cmd = candidate
+          else
+            candidates = case target
+                         when "lsp" then Rubik::Runtime::Discovery.lsp_candidates(lang)
+                         when "test_runner" then Rubik::Runtime::Discovery.test_runner_candidates(lang, root_dir: @root_dir)
+                         when "linter" then Rubik::Runtime::Discovery::FORMATTER_CANDIDATES[lang] || []
+                         else []
+                         end
+            cand_str = candidates.empty? ? "none" : candidates.join(", ")
+            return ToolOutput.error("Auto-probe failed to discover any installed candidate for #{target} (#{lang}). " \
+                                    "Candidates checked: [#{cand_str}]. Please provide a specific `proposed_command`.")
+          end
+        end
+
+        return ToolOutput.error("No command provided or discovered for #{target} (#{lang}).") if proposed_cmd.empty?
+
+        # 2. Pre-flight Verification in Isolated Sub-Context (ctx.extend())
+        root_ctx = @runtime_manager&.context || Rubik::Runtime::Context.new
+        sub_ctx = root_ctx.extend
+
+        verified = false
+        error_diagnostic = nil
+
+        begin
+          verified, error_diagnostic = verify_binary(target, lang, proposed_cmd, sub_ctx)
+        rescue StandardError => e
+          error_diagnostic = Rubik::Runtime::DiagnosticEngine.diagnose(
+            cmd: proposed_cmd,
+            exit_code: 1,
+            stderr: "Exception during pre-flight sandbox check: #{e.message}"
+          )
+        ensure
+          sub_ctx.dispose
+        end
+
+        return ToolOutput.error("Verification failed for #{target} (#{lang}):\n#{error_diagnostic&.format_for_llm}") unless verified
+
+        # 3. Live Context Promotion & Subsystem Configuration (Zero-Downtime Hot Swapping)
+        case target
+        when "lsp"
+          cfg_key = "lsp.servers.#{lang}"
+          prev_cmd = @config&.fetch(cfg_key)
+          had_client = @lsp_manager ? !@lsp_manager.client_for(lang).nil? : false
+          @config&.set(cfg_key, proposed_cmd)
+          if @lsp_manager
+            @lsp_manager.stop_client(lang)
+            start_res = @lsp_manager.start_client(lang)
+            unless start_res.is_a?(Hash) && start_res[:ok] == true
+              # Failure Reversibility (AGENTS.md §1.A): roll back the in-memory
+              # state; disk stays clean because persist happens only after a
+              # verified start (atomic promotion).
+              @lsp_manager.stop_client(lang)
+              @config&.set(cfg_key, prev_cmd)
+              @lsp_manager.start_client(lang) if had_client
+              cause = start_res.is_a?(Hash) ? start_res[:error] : "unexpected start_client response"
+              return ToolOutput.error("Failed to start LSP server for #{lang} ('#{proposed_cmd}'); " \
+                                      "previous configuration restored. Cause: #{cause}")
+            end
+            active_client = @lsp_manager.client_for(lang)
+            root_ctx.provide("lsp:#{lang}", active_client || proposed_cmd)
+          else
+            root_ctx.provide("lsp:#{lang}", proposed_cmd)
+          end
+          # Persist to project config only after the live promotion succeeded.
+          persist_res = @config&.set(cfg_key, proposed_cmd, persist: :project)
+        when "test_runner"
+          persist_res = @config&.set("test.runners.#{lang}", proposed_cmd, persist: :project)
+          if @adapter_registry
+            adapter = @adapter_registry.get(lang)
+            if adapter
+              adapter.config ||= @config
+              adapter.custom_test_cmd = proposed_cmd
+            else
+              require_relative "../../adapter/generic" unless defined?(Rubik::Adapter::GenericAdapter)
+              new_adapter = Rubik::Adapter::GenericAdapter.new(lang, test_cmd: proposed_cmd, guard: @guard)
+              new_adapter.config = @config
+              @adapter_registry.register(lang, new_adapter, ctx: root_ctx)
+            end
+          end
+          root_ctx.provide("runner:#{lang}", proposed_cmd)
+        when "linter"
+          persist_res = @config&.set("linter.commands.#{lang}", proposed_cmd, persist: :project)
+          if @adapter_registry
+            adapter = @adapter_registry.get(lang)
+            if adapter
+              adapter.config ||= @config
+              adapter.custom_format_cmd = proposed_cmd
+            else
+              require_relative "../../adapter/generic" unless defined?(Rubik::Adapter::GenericAdapter)
+              new_adapter = Rubik::Adapter::GenericAdapter.new(lang, format_cmd: proposed_cmd, guard: @guard)
+              new_adapter.config = @config
+              @adapter_registry.register(lang, new_adapter, ctx: root_ctx)
+            end
+          end
+          root_ctx.provide("linter:#{lang}", proposed_cmd)
+        when "command"
+          root_ctx.provide("command:#{lang}", proposed_cmd)
+        end
+
+        if @config.nil? && ["lsp", "test_runner", "linter"].include?(target)
+          return "⚠️ Promoted '#{proposed_cmd}' for #{target} (#{lang}) — no config is attached, " \
+                 "so the command is active for this session only and was not saved."
+        end
+
+        if persist_res.is_a?(Hash) && !persist_res[:ok]
+          return "⚠️ Promoted '#{proposed_cmd}' for #{target} (#{lang}) — active in this session, " \
+                 "but saving to the project config failed: #{persist_res[:error]}"
+        end
+
+        "✨ Successfully verified and promoted runtime service for #{target} (#{lang}): '#{proposed_cmd}'. " \
+          "Service is now active and hot-swapped in the live context with zero downtime."
+      end
+
+      private
+
+      def verify_binary(target, lang, proposed_cmd, sub_ctx)
+        case target
+        when "lsp"
+          client = Rubik::LSP::Client.new(lang, root_dir: @root_dir, server_cmd: proposed_cmd)
+          if client.available?
+            sub_ctx.provide("lsp_probe:#{lang}", client)
+            [true, nil]
+          else
+            [false, Rubik::Runtime::DiagnosticEngine.diagnose(
+              cmd: proposed_cmd,
+              exit_code: 127,
+              stderr: "Pre-flight check failed: LSP binary '#{client.binary_name}' not available on system"
+            )]
+          end
+        when "test_runner"
+          if Rubik::Runtime::Discovery.binary_available?(proposed_cmd)
+            sub_ctx.provide("runner_probe:#{lang}", proposed_cmd)
+            [true, nil]
+          else
+            [false, Rubik::Runtime::DiagnosticEngine.diagnose(
+              cmd: proposed_cmd,
+              exit_code: 127,
+              stderr: "Pre-flight check failed: Test runner executable not found in PATH"
+            )]
+          end
+        when "linter"
+          if Rubik::Runtime::Discovery.binary_available?(proposed_cmd)
+            sub_ctx.provide("linter_probe:#{lang}", proposed_cmd)
+            [true, nil]
+          else
+            [false, Rubik::Runtime::DiagnosticEngine.diagnose(
+              cmd: proposed_cmd,
+              exit_code: 127,
+              stderr: "Pre-flight check failed: Linter/formatter executable not found in PATH"
+            )]
+          end
+        when "command"
+          if Rubik::Runtime::Discovery.binary_available?(proposed_cmd)
+            sub_ctx.provide("command_probe:#{lang}", proposed_cmd)
+            [true, nil]
+          else
+            [false, Rubik::Runtime::DiagnosticEngine.diagnose(
+              cmd: proposed_cmd,
+              exit_code: 127,
+              stderr: "Pre-flight check failed: Command executable not found in PATH"
+            )]
+          end
+        else
+          [false, Rubik::Runtime::DiagnosticEngine.diagnose(
+            cmd: proposed_cmd,
+            exit_code: 1,
+            stderr: "Unknown target component type: #{target}"
+          )]
+        end
+      end
+    end
+
+    class FinishTool < BaseTool
+      DECLARATION = Declaration.new(
+        name: "finish", aliases: ["complete", "done", "task_complete", "exit"],
+        description: "Signal task completion with final message. Before finishing, re-verify headline claims " \
+                     "(file lists, counts, command outcomes) against your raw command output — context " \
+                     "compaction can blur report details, and the final report must match observed evidence.",
+        risk: :execute, maestro_blocked: false, # the completion signal — handled before the gate; must stay direct
+        params_schema: { type: "object",
+                         properties: { message: { type: "string",
+                                                  description: "Final summary message for the user describing what was accomplished (optional)" } } }
+      )
+
+      def initialize
+        super(DECLARATION)
+      end
+
+      def execute(args = {})
+        args["message"] || args[:message] || "Task finished"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+require_relative "../../coeffects"
+require_relative "../output"
+
+module Rubik
+  module Tools
+    class LSPDiagnosticsTool < BaseTool
+      attr_reader :lsp_manager, :buffer_manager
+
+      DECLARATION = Declaration.new(
+        name: "lsp_diagnostics", aliases: ["get_diagnostics", "diagnostics"],
+        description: "Get real-time compiler and linter diagnostics (errors, warnings) for a file or all active project files via LSP",
+        risk: :read, archetypes: [:research, :coder],
+        params_schema: {
+          type: "object",
+          properties: {
+            file_path: { type: "string", description: "Optional specific file path to query diagnostics for" }
+          }
+        }
+      )
+      def initialize(lsp_manager = nil, buffer_mgr = nil, buffer_manager: nil)
+        super(DECLARATION)
+        @lsp_manager = lsp_manager
+        @buffer_manager = buffer_manager || buffer_mgr
+      end
+
+      def effective_buffer_manager
+        @buffer_manager || @lsp_manager&.context&.get(Rubik::Coeffects::BUFFER_MANAGER)
+      end
+
+      def execute(args = {})
+        return ToolOutput.error("LSP manager is not connected.") unless @lsp_manager
+        return ToolOutput.error("LSP is currently disabled in configuration (enable via '!lsp on').") unless @lsp_manager.enabled?
+
+        path = (args["file_path"] || args[:file_path] || "").to_s.strip
+        bm = effective_buffer_manager
+        @lsp_manager.sync_buffer_file_if_needed(path, bm) if bm && @lsp_manager.respond_to?(:sync_buffer_file_if_needed)
+
+        if path.empty?
+          all = @lsp_manager.all_diagnostics
+          total_issues = all.values.flatten.size
+          if total_issues.zero?
+            "No active LSP diagnostics across workspace (all clean)."
+          else
+            lines = ["=== Active Workspace LSP Diagnostics (#{total_issues} issue(s)) ==="]
+            all.each do |fpath, diags|
+              next if diags.empty?
+
+              lines << "\nFile: #{fpath} (#{diags.size}):"
+              diags.each do |d|
+                sev = d["severity"] == 1 ? "ERROR" : "WARN"
+                start_line = (d.dig("range", "start", "line") || 0) + 1
+                lines << "  • [#{sev}] Line #{start_line}: #{d['message']}"
+              end
+            end
+            lines.join("\n")
+          end
+        else
+          diags = @lsp_manager.diagnostics_for(path)
+          if diags.empty?
+            append_buffer_tip("No LSP diagnostics or errors for '#{path}'.", path)
+          else
+            lines = ["=== LSP Diagnostics for #{path} (#{diags.size} issue(s)) ==="]
+            diags.each do |d|
+              sev = case d["severity"]
+                    when 1 then "ERROR"
+                    when 2 then "WARN"
+                    when 3 then "INFO"
+                    else "HINT"
+                    end
+              range = d["range"] || {}
+              start_line = (range.dig("start", "line") || 0) + 1
+              start_char = (range.dig("start", "character") || 0) + 1
+              lines << "  • [#{sev}] Line #{start_line}:#{start_char} - #{d['message']}"
+            end
+            lines.join("\n")
+          end
+        end
+      end
+
+      private
+
+      def buffer_dirty?(path)
+        bm = effective_buffer_manager
+        return false unless bm && !path.to_s.empty?
+
+        if bm.respond_to?(:dirty?)
+          begin
+            bm.method(:dirty?).arity.zero? ? bm.dirty? : bm.dirty?(path)
+          rescue ArgumentError
+            bm.dirty?
+          end
+        else
+          false
+        end
+      end
+
+      def append_buffer_tip(msg, path)
+        return msg unless buffer_dirty?(path)
+
+        tip = "\n\n💡 Tip: '#{path}' has unapplied in-memory buffer modifications. " \
+              "Call 'apply_buffer' to persist changes to disk for language servers requiring disk-based indexing."
+        "#{msg}#{tip}"
+      end
+    end
+
+    class LSPHoverTool < BaseTool
+      attr_reader :lsp_manager, :buffer_manager
+
+      DECLARATION = Declaration.new(
+        name: "lsp_hover", aliases: ["get_hover", "hover"],
+        description: "Get compiler-level type signature, docstring, and symbol details at a specific line and character position via LSP",
+        risk: :read, archetypes: [:research],
+        params_schema: {
+          type: "object",
+          properties: {
+            file_path: { type: "string", description: "Path to source file" },
+            line: { type: "integer", description: "1-based line number" },
+            character: { type: "integer", description: "1-based character position" }
+          },
+          required: ["file_path", "line", "character"]
+        }
+      )
+      def initialize(lsp_manager = nil, buffer_mgr = nil, buffer_manager: nil)
+        super(DECLARATION)
+        @lsp_manager = lsp_manager
+        @buffer_manager = buffer_manager || buffer_mgr
+      end
+
+      def effective_buffer_manager
+        @buffer_manager || @lsp_manager&.context&.get(Rubik::Coeffects::BUFFER_MANAGER)
+      end
+
+      def execute(args = {})
+        return ToolOutput.error("LSP manager is not connected.") unless @lsp_manager
+        return ToolOutput.error("LSP is currently disabled in configuration (enable via '!lsp on').") unless @lsp_manager.enabled?
+
+        path = (args["file_path"] || args[:file_path]).to_s.strip
+        line = (args["line"] || args[:line]).to_i
+        char = (args["character"] || args[:character] || args["col"] || args[:col]).to_i
+
+        return ToolOutput.error("File path is required.") if path.empty?
+        return ToolOutput.error("Line number must be >= 1.") if line < 1
+
+        bm = effective_buffer_manager
+        @lsp_manager.sync_buffer_file_if_needed(path, bm) if bm && @lsp_manager.respond_to?(:sync_buffer_file_if_needed)
+
+        res = @lsp_manager.hover(path, [line - 1, 0].max, [char - 1, 0].max)
+        if res[:ok]
+          contents = res.dig(:result, "contents")
+          if contents.nil? || contents.empty?
+            append_buffer_tip("No hover information available at #{path}:#{line}:#{char}", path)
+          elsif contents.is_a?(Hash) && contents["value"]
+            contents["value"]
+          elsif contents.is_a?(Array)
+            contents.map { |c| c.is_a?(Hash) ? c["value"] : c.to_s }.join("\n")
+          else
+            contents.to_s
+          end
+        else
+          ToolOutput.error("LSP Hover failed: #{res[:error]}")
+        end
+      end
+
+      private
+
+      def buffer_dirty?(path)
+        bm = effective_buffer_manager
+        return false unless bm && !path.to_s.empty?
+
+        if bm.respond_to?(:dirty?)
+          begin
+            bm.method(:dirty?).arity.zero? ? bm.dirty? : bm.dirty?(path)
+          rescue ArgumentError
+            bm.dirty?
+          end
+        else
+          false
+        end
+      end
+
+      def append_buffer_tip(msg, path)
+        return msg unless buffer_dirty?(path)
+
+        tip = "\n\n💡 Tip: '#{path}' has unapplied in-memory buffer modifications. " \
+              "Call 'apply_buffer' to persist changes to disk for language servers requiring disk-based indexing."
+        "#{msg}#{tip}"
+      end
+    end
+
+    class LSPDefinitionTool < BaseTool
+      attr_reader :lsp_manager, :buffer_manager
+
+      DECLARATION = Declaration.new(
+        name: "lsp_definition", aliases: ["goto_definition", "definition"],
+        description: "Jump to exact type-safe declaration and definition location of a symbol at line/character position via LSP",
+        risk: :read, archetypes: [:research],
+        params_schema: {
+          type: "object",
+          properties: {
+            file_path: { type: "string", description: "Path to source file" },
+            line: { type: "integer", description: "1-based line number" },
+            character: { type: "integer", description: "1-based character position" }
+          },
+          required: ["file_path", "line", "character"]
+        }
+      )
+      def initialize(lsp_manager = nil, buffer_mgr = nil, buffer_manager: nil)
+        super(DECLARATION)
+        @lsp_manager = lsp_manager
+        @buffer_manager = buffer_manager || buffer_mgr
+      end
+
+      def effective_buffer_manager
+        @buffer_manager || @lsp_manager&.context&.get(Rubik::Coeffects::BUFFER_MANAGER)
+      end
+
+      def execute(args = {})
+        return ToolOutput.error("LSP manager is not connected.") unless @lsp_manager
+        return ToolOutput.error("LSP is currently disabled in configuration (enable via '!lsp on').") unless @lsp_manager.enabled?
+
+        path = (args["file_path"] || args[:file_path]).to_s.strip
+        line = (args["line"] || args[:line]).to_i
+        char = (args["character"] || args[:character] || args["col"] || args[:col]).to_i
+
+        return ToolOutput.error("File path is required.") if path.empty?
+        return ToolOutput.error("Line number must be >= 1.") if line < 1
+
+        bm = effective_buffer_manager
+        @lsp_manager.sync_buffer_file_if_needed(path, bm) if bm && @lsp_manager.respond_to?(:sync_buffer_file_if_needed)
+
+        res = @lsp_manager.definition(path, [line - 1, 0].max, [char - 1, 0].max)
+        if res[:ok]
+          result = res[:result]
+          if result.nil? || (result.is_a?(Array) && result.empty?)
+            append_buffer_tip("No definition found for symbol at #{path}:#{line}:#{char}", path)
+          else
+            locs = result.is_a?(Array) ? result : [result]
+            lines = ["Found #{locs.size} definition location(s):"]
+            locs.each do |loc|
+              uri = loc["uri"] || loc["targetUri"]
+              clean_file = uri.to_s.sub(%r{^file://}, "")
+              range = loc["range"] || loc["targetSelectionRange"] || {}
+              s_line = (range.dig("start", "line") || 0) + 1
+              s_char = (range.dig("start", "character") || 0) + 1
+              lines << "  • #{clean_file}:#{s_line}:#{s_char}"
+            end
+            lines.join("\n")
+          end
+        else
+          ToolOutput.error("LSP Definition failed: #{res[:error]}")
+        end
+      end
+
+      private
+
+      def buffer_dirty?(path)
+        bm = effective_buffer_manager
+        return false unless bm && !path.to_s.empty?
+
+        if bm.respond_to?(:dirty?)
+          begin
+            bm.method(:dirty?).arity.zero? ? bm.dirty? : bm.dirty?(path)
+          rescue ArgumentError
+            bm.dirty?
+          end
+        else
+          false
+        end
+      end
+
+      def append_buffer_tip(msg, path)
+        return msg unless buffer_dirty?(path)
+
+        tip = "\n\n💡 Tip: '#{path}' has unapplied in-memory buffer modifications. " \
+              "Call 'apply_buffer' to persist changes to disk for language servers requiring disk-based indexing."
+        "#{msg}#{tip}"
+      end
+    end
+  end
+end