hecks 3.10.0 → 3.11.0

data/lib/hecks/adapters/driving/mcp.rb

@@ -0,0 +1,159 @@
+require "json"
+require_relative "../.."
+require_relative "../../cli/mcp"
+require_relative "mcp/tool_definitions"
+require_relative "mcp/tool_calls"
+
+module Hecks
+  module Adapters
+    module Driving
+      # The MCP server onto the storehouse bus: hand-rolled JSON-RPC over stdio, one
+      # server per booted domain. All logic and the JSON shape answered with live in
+      # `Storehouse`; this is plumbing only. A `role:`/`actor_id:` a caller sends is
+      # asserted, not verified, unless Governance is attached.
+      #
+      # There is no authentication: `domain:` boots real Ruby confined to
+      # `Storehouse::BOOT_ROOT`, so this is a code execution surface for anyone who
+      # can write to stdin (ADR 0062). Spawning with `HECKS_SERVER_TOOLS=readers` and
+      # `HECKS_SERVER_DOMAINS=<dir>[:<dir>...]` narrows a server to read-only tools and
+      # named domains (`McpScope`); this limits what one agent can reach and is
+      # not itself authentication.
+      module Mcp
+        PROTOCOL_VERSION = "2024-11-05".freeze
+
+        TOOLS = ToolDefinitions::TOOLS
+
+        NOTES = [
+          "Identity is self-asserted: role:/actor_id: are claims made by the caller and are not verified.",
+          "state, events, history, follow, describe, catalog and query run with no role check at all.",
+          "domain: boots real Ruby under #{Storehouse::BOOT_ROOT}; anyone who can write to stdin can run it."
+        ].freeze
+
+        # The method that answers each JSON-RPC method that has a response.
+        REPLIES = {
+          "initialize" => :initialize_result,
+          "tools/list" => :tools_list,
+          "tools/call" => :tools_call,
+          "ping"       => :ping_result
+        }.freeze
+
+        module_function
+
+        # Read once, so a bad setting refuses to start the server before anything is
+        # written to stdout.
+        def scope
+          @scope ||= McpScope.start!(server: CLI::Mcp::SERVER)
+        end
+
+        # The standing notes, then what this server's scope says about `domain:`.
+        def warning_notes
+          NOTES[0, 2] + (scope.restricted? ? scope.notes : [NOTES[2]])
+        end
+
+        def serve
+          McpStdioGuard.warn!(server: CLI::Mcp::SERVER, notes: warning_notes)
+          $stdout.sync = true
+
+          $stdin.each_line { |line| answer_line(line.strip) }
+        end
+
+        # Answers one request line; a line that is not JSON is a parse error, not a crash.
+        def answer_line(line)
+          return if line.empty?
+
+          handle_safely(JSON.parse(line))
+        rescue JSON::ParserError => e
+          send_error(nil, -32_700, "Parse error: #{e.message}")
+        end
+
+        # Handles a request, answering an internal error rather than ending the server.
+        def handle_safely(request)
+          handle(request)
+        rescue StandardError => e
+          send_error(request["id"], -32_603, "Internal error: #{e.class}: #{e.message}")
+        end
+
+        # `domain:` is confined to `Storehouse::BOOT_ROOT`, and further to a restricted
+        # server's `HECKS_SERVER_DOMAINS`, before anything boots. An unrestricted server boots the
+        # domain afresh on every call; a restricted server lives for one spawner's session and
+        # keeps each named domain booted until the files of its directory change.
+        def boot(domain)
+          path = Storehouse.confine!(scope.admit_domain!(domain), "domain")
+          runtime = scope.restricted? ? resident_boot(path) : Hecks.boot(path, install_driving: false)
+          Admission.admit!(runtime.registry, "Mcp")
+          runtime
+        end
+
+        # The runtime a restricted server keeps for `path`, booted again once its files change.
+        def resident_boot(path)
+          resident    = (@resident ||= {})
+          fingerprint = Storehouse.fingerprint(path)
+          return resident[path][:runtime] if resident[path] && resident[path][:fingerprint] == fingerprint
+
+          resident[path] = { fingerprint: fingerprint, runtime: Hecks.boot(path, install_driving: false) }
+          resident[path][:runtime]
+        end
+
+        def answer_tool(name, args)
+          return scope.refusal(name) unless scope.permits_tool?(name)
+
+          ToolCalls.call(name, scope.with_default_domain(args))
+        end
+
+        # One line per allowed command: what it takes and the role it declares, read from the booted
+        # domain the server serves. Nil when the server serves no single domain or it will not boot,
+        # so
+        # `tools/list` still answers, with the commands as a bare list.
+        def command_guide
+          return unless scope.commands_mode? && scope.default_domain
+
+          McpGuideCache.remember(scope.default_domain, scope.allowed_commands) do
+            Storehouse.command_guide(boot(scope.default_domain), scope.allowed_commands)
+          end
+        rescue StandardError
+          nil
+        end
+
+        def tool_result(payload)
+          { content: [{ type: "text", text: JSON.pretty_generate(payload) }], isError: payload[:ok] == false }
+        end
+
+        def send_response(id, result)
+          puts JSON.generate({ jsonrpc: "2.0", id: id, result: result })
+        end
+
+        def send_error(id, code, message)
+          puts JSON.generate({ jsonrpc: "2.0", id: id, error: { code: code, message: message } })
+        end
+
+        # Answers one JSON-RPC request. A notification has no id and gets no response.
+        def handle(request)
+          id     = request["id"]
+          method = request["method"]
+          reply  = REPLIES[method]
+          return send_response(id, public_send(reply, request["params"] || {})) if reply
+
+          send_error(id, -32_601, "Method not found: #{method}") unless id.nil? || method == "notifications/initialized"
+        end
+
+        def initialize_result(_params)
+          { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} },
+            serverInfo: { name: CLI::Mcp::SERVER, version: "1.1.0" } }
+        end
+
+        # The tools this server's scope permits, each presented with the command guide.
+        def tools_list(_params)
+          served = TOOLS.select { |tool| scope.permits_tool?(tool[:name]) }
+          guide  = command_guide
+          { tools: served.map { |tool| scope.present(tool, guide) } }
+        end
+
+        def tools_call(params)
+          tool_result(answer_tool(params["name"], params["arguments"] || {}))
+        end
+
+        def ping_result(_params) = {}
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/mcp_guide_cache.rb

@@ -0,0 +1,78 @@
+require "digest"
+require "fileutils"
+require "json"
+require_relative "../../cache_dir"
+require_relative "../../storehouse"
+require_relative "../../bluebook/meta_validator/verdict_cache"
+
+module Hecks
+  module Adapters
+    module Driving
+      # Remembers the command guide a commands server builds for `tools/list`, so a server that
+      # starts
+      # again does not boot its domain to describe its commands. A client waits only a moment for a
+      # server's tools, and a boot at that point costs more than the wait.
+      #
+      # An entry is keyed by the domain directory's files, a digest of the hecks code, and the
+      # allowed commands, so a change to any of them builds a new guide. The file is JSON, read only
+      # from a directory and a file that only this user can write (the verdict cache's own check),
+      # and only when it is a list of strings: a guide is text an agent reads as instructions.
+      module McpGuideCache
+        module_function
+
+        # The guide for a domain and its allowed commands, from the cache or else from the block,
+        # which is then remembered. A cache that cannot be written is not an error: the next start
+        # builds the guide again.
+        #
+        # @param domain [String] the domain directory the guide describes
+        # @param commands [Array<String>] the allowed command names
+        # @yieldreturn [Array<String>, nil] the guide, built when none is remembered
+        # @return [Array<String>, nil] the guide
+        def remember(domain, commands)
+          file = File.join(dir, "#{key(domain, commands)}.json")
+          cached = read(file)
+          return cached if cached
+
+          guide = yield
+          write(file, guide) if guide.is_a?(Array) && guide.any?
+          guide
+        end
+
+        # @return [String] the directory entries live in
+        def dir = Hecks::CacheDir.path("mcp_guides")
+
+        # @param domain [String] the domain directory
+        # @param commands [Array<String>] the allowed command names
+        # @return [String] a hex SHA-256 over the domain's files, the hecks code and the commands
+        def key(domain, commands)
+          parts = [Storehouse.fingerprint(domain), Bluebook::MetaValidator::VerdictCache.code_digest,
+                   commands.sort.join(",")]
+          Digest::SHA256.hexdigest(parts.join("\0"))
+        end
+
+        # @param file [String] an entry's path
+        # @return [Array<String>, nil] the guide, or nil when absent, untrusted or malformed
+        def read(file)
+          return unless File.file?(file) && Bluebook::MetaValidator::VerdictCache.trusted?(file)
+
+          guide = JSON.parse(File.read(file))
+          guide if guide.is_a?(Array) && guide.all?(String)
+        rescue StandardError
+          nil
+        end
+
+        # @param file [String] an entry's path
+        # @param guide [Array<String>] the guide to remember
+        # @return [void]
+        def write(file, guide)
+          FileUtils.mkdir_p(dir, mode: 0o700)
+          temp = "#{file}.#{Process.pid}.tmp"
+          File.write(temp, JSON.generate(guide), perm: 0o600)
+          File.rename(temp, file)
+        rescue StandardError
+          FileUtils.rm_f(temp) if temp
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/mcp_scope/argument_policy.rb

@@ -0,0 +1,97 @@
+require_relative "../../../runtime/errors"
+
+module Hecks
+  module Adapters
+    module Driving
+      class McpScope
+        # What a restricted server lets an argument say: a denied name is refused, a path must
+        # resolve
+        # inside the root with symlinks followed, and a git ref must be a plain name.
+        module ArgumentPolicy
+          module_function
+
+          # Checks every argument in `args`, nested or not, and refuses the first one the policy
+          # forbids.
+          #
+          # @param args [Hash, Array, nil] the arguments as the caller gave them
+          # @param label [String] how the server describes its mode, for the refusal
+          # @raise [Runtime::TypeMismatch] on the first argument refused
+          def admit!(args, label)
+            each_argument(args) do |name, value|
+              if DENIED_ARGUMENTS.include?(name)
+                refuse!(name, label, "never passes it on: it names a host, a binary, an output or a change of state")
+              end
+              admit_path!(name, value, label) if PATH_ARGUMENTS.include?(name)
+              admit_ref!(name, value, label) if REF_ARGUMENTS.include?(name)
+            end
+          end
+
+          # Yields every argument name with its value, descending into nested objects and lists, so
+          # `{"file" => {"value" => "x"}}` is checked the way `{"file" => "x"}` is.
+          def each_argument(args, &visit)
+            case args
+            when Hash
+              args.each do |name, value|
+                yield(name.to_s, value)
+                each_argument(value, &visit)
+              end
+            when Array
+              args.each { |item| each_argument(item, &visit) }
+            end
+          end
+
+          # A value written as an object of one field (`{"value" => "x"}`) is that field's value.
+          def scalar(value)
+            return value unless value.is_a?(Hash)
+
+            value.fetch("value") { value.fetch(:value, value) }
+          end
+
+          def refuse!(name, label, why)
+            raise Runtime::TypeMismatch, "argument: #{name.inspect} is refused: this server runs in #{label} and #{why}"
+          end
+
+          def admit_path!(name, value, label)
+            Array(scalar(value)).flat_map { |item| item.to_s.split(",") }.reject(&:empty?).each do |path|
+              next if !path.include?(":") && inside_root?(path)
+
+              refuse!(name, label, "passes a path only when it resolves inside #{Storehouse::BOOT_ROOT} " \
+                                   "and holds no colon: #{path.inspect}")
+            end
+          end
+
+          def admit_ref!(name, value, label)
+            ref = scalar(value).to_s
+            return if ref.match?(PLAIN_REF) && !ref.include?("..")
+
+            refuse!(name, label, "passes only a plain git ref: #{ref.inspect}")
+          end
+
+          def inside_root?(path)
+            root = resolve_real(Storehouse::BOOT_ROOT)
+            resolved = resolve_real(File.expand_path(path, Storehouse::BOOT_ROOT))
+            resolved == root || resolved.start_with?("#{root}#{File::SEPARATOR}")
+          end
+
+          # The real path of `path`, symlinks followed: of the whole path when it exists, else of
+          # its
+          # deepest existing parent with the missing names put back, so a link above a file that
+          # does
+          # not exist yet still shows where the file would land.
+          def resolve_real(path)
+            missing = []
+            current = File.expand_path(path)
+            until File.exist?(current)
+              parent = File.dirname(current)
+              break if parent == current
+
+              missing.unshift(File.basename(current))
+              current = parent
+            end
+            File.join(File.realpath(current), *missing)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/mcp_scope/env_problems.rb

@@ -0,0 +1,69 @@
+module Hecks
+  module Adapters
+    module Driving
+      class McpScope
+        # What is wrong with the `HECKS_SERVER_*` variables a server was spawned with, as the
+        # sentences that refuse to start it.
+        module EnvProblems
+          module_function
+
+          # Variables under this prefix are retired spellings of the `HECKS_SERVER_*` ones.
+          RETIRED_PREFIX = "HECKS_DOOR_".freeze
+
+          # Every problem in `env`: a variable the server does not take, then those of the mode.
+          def setting_problems(env)
+            known = [TOOLS_VARIABLE, DOMAINS_VARIABLE, COMMANDS_VARIABLE]
+            problems = retired_problems(env) + (env.keys.select { |name| name.start_with?(ENV_PREFIX) } - known).map do |name|
+              "environment #{name} is not accepted; the server takes only #{known.join(", ")}"
+            end
+            problems + mode_problems(env[TOOLS_VARIABLE], env[DOMAINS_VARIABLE], env[COMMANDS_VARIABLE])
+          end
+
+          # A variable under the retired prefix is refused, never ignored: ignoring
+          # `HECKS_DOOR_TOOLS`
+          # would start an unrestricted server where the spawner asked for a narrow one.
+          def retired_problems(env)
+            env.keys.select { |name| name.start_with?(RETIRED_PREFIX) }.map do |name|
+              "environment #{name} is retired; the server reads #{name.sub(RETIRED_PREFIX, ENV_PREFIX)}"
+            end
+          end
+
+          def mode_problems(tools, domains, commands)
+            return stray_problems(domains, commands) if tools.nil?
+            unless MODES.include?(tools)
+              return ["#{TOOLS_VARIABLE}=#{tools.inspect} is not accepted; the values are #{MODES.map(&:inspect).join(" and ")}"]
+            end
+
+            problems = []
+            if split_paths(domains.to_s).empty?
+              problems << "#{TOOLS_VARIABLE}=#{tools} needs #{DOMAINS_VARIABLE}, the domains this server may read"
+            end
+            problems + command_problems(tools, commands)
+          end
+
+          def stray_problems(domains, commands)
+            stray = { DOMAINS_VARIABLE => domains, COMMANDS_VARIABLE => commands }.compact.keys
+            return [] if stray.empty?
+
+            ["#{stray.join(" and ")} set without #{TOOLS_VARIABLE}=#{READERS} or #{TOOLS_VARIABLE}=#{COMMANDS}; " \
+             "they only narrow a restricted server"]
+          end
+
+          def command_problems(tools, commands)
+            if tools == COMMANDS && split_names(commands).empty?
+              ["#{TOOLS_VARIABLE}=#{COMMANDS} needs #{COMMANDS_VARIABLE}, the commands this server may dispatch"]
+            elsif tools == READERS && !commands.nil?
+              ["#{COMMANDS_VARIABLE} is set in reader mode; it only narrows a commands server"]
+            else
+              []
+            end
+          end
+
+          def split_paths(value) = value.to_s.split(File::PATH_SEPARATOR).reject(&:empty?)
+
+          def split_names(value) = value.to_s.split(",").map(&:strip).reject(&:empty?).uniq
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/mcp_scope/presenter.rb

@@ -0,0 +1,83 @@
+module Hecks
+  module Adapters
+    module Driving
+      class McpScope
+        # A tool definition as `tools/list` shows it to one server, and the notes the server starts
+        # with.
+        module Presenter
+          module_function
+
+          # The tool as `tools/list` shows it. A server that serves one domain makes `domain:`
+          # optional.
+          # On a commands server, `dispatch` also names the commands it serves as an enum, so a
+          # caller
+          # sees them as typed choices instead of finding out by being refused, and says what each
+          # takes and which role it declares.
+          #
+          # @param scope [McpScope] the server's scope
+          # @param tool [Hash] a tool definition from `Mcp::TOOLS`
+          # @param guide [Array<String>, nil] one line per allowed command
+          #   (`Storehouse.command_guide`)
+          # @return [Hash] the definition, narrowed for this server
+          def present(scope, tool, guide)
+            tool = domain_optional(tool, scope.default_domain) if scope.default_domain
+            return tool unless scope.commands_mode? && tool[:name] == "dispatch"
+
+            narrow_dispatch(tool, guide, scope.allowed_commands)
+          end
+
+          # `dispatch`, with the commands the server serves as typed choices.
+          def narrow_dispatch(tool, guide, commands)
+            properties = tool[:inputSchema][:properties]
+            steps      = properties[:steps]
+            narrowed   = properties.merge(command: with_enum(properties[:command], commands),
+                                          steps:   steps.merge(items: step_items(steps[:items], commands)))
+            tool.merge(description: dispatch_description(tool[:description], guide, commands),
+                       inputSchema: tool[:inputSchema].merge(properties: narrowed))
+          end
+
+          def domain_optional(tool, default)
+            schema = tool[:inputSchema]
+            return tool unless schema[:properties].key?(:domain)
+
+            note = "Optional: this server serves one domain, #{default}, and uses it when you leave this out."
+            properties = schema[:properties].merge(domain: schema[:properties][:domain].merge(description: note))
+            tool.merge(inputSchema: schema.merge(properties: properties, required: schema[:required] - ["domain"]))
+          end
+
+          def dispatch_description(base, guide, commands)
+            intro = "#{base} This server dispatches only the commands below, each with the role it declares: pass " \
+                    "that role as `role`. A command that takes `run` takes a key you choose, and the call answers " \
+                    "the record as it stands once its reactions have run; an argument marked * is required."
+            entries = Array(guide).empty? ? commands : guide
+            ([intro] + entries.map { |entry| "- #{entry}" }).join("\n")
+          end
+
+          def with_enum(property, commands)
+            property.merge(enum: commands)
+          end
+
+          def step_items(items, commands)
+            items.merge(properties: items[:properties].merge(command: with_enum(items[:properties][:command], commands)))
+          end
+
+          # What a reader server says about itself when it starts.
+          def reader_notes(domains)
+            ["Reader mode (#{TOOLS_VARIABLE}=#{READERS}): serves #{READER_TOOLS.join(", ")}; " \
+             "refuses dispatch (with dry_run and steps), behaviors and every other tool.",
+             "domain: boots only #{DOMAINS_VARIABLE}: #{domains.join(", ")}.",
+             "Reader mode limits reach and identifies no one; it is not authentication."]
+          end
+
+          # What a commands server says about itself when it starts.
+          def commands_notes(domains, commands)
+            ["Commands mode (#{TOOLS_VARIABLE}=#{COMMANDS}): serves #{READER_TOOLS.join(", ")} and dispatch of only " \
+             "#{COMMANDS_VARIABLE}: #{commands.join(", ")}; refuses behaviors and every other tool.",
+             "domain: boots only #{DOMAINS_VARIABLE}: #{domains.join(", ")}.",
+             "Commands mode limits reach and identifies no one; role: stays self-asserted and it is not authentication."]
+          end
+        end
+      end
+    end
+  end
+end