solid_loop 0.0.4

data/lib/solid_loop/mcp/toolset.rb

@@ -0,0 +1,347 @@
+module SolidLoop
+  module Mcp
+    # In-process MCP server: a toolset IS both the server and its transport.
+    # `deliver` dispatches initialize / tools/list / tools/call without HTTP,
+    # preserving the JSON boundary (string keys) so local and remote behavior
+    # cannot drift. See docs/guides/mcp_transports.md.
+    #
+    #   class SearchTools < SolidLoop::Mcp::Toolset
+    #     server_name "search"
+    #
+    #     tool "fetch_url",
+    #          description: "Fetch a URL and return a text summary",
+    #          input_schema: { type: "object", properties: {} } do |args, ctx|
+    #       Search::Fetch.call(loop: ctx.loop).to_json
+    #     end
+    #   end
+    class Toolset
+      include Transport
+
+      # Raised inside a tool handler to return an intentional, user-facing
+      # message to the caller (passed through verbatim in the isError result).
+      # Any OTHER StandardError is treated as an internal fault: it is logged
+      # server-side and the caller gets an opaque message, so SQL/paths/tenant
+      # detail never leak across the public boundary. See handle_tools_call.
+      class PublicToolError < StandardError; end
+
+      # Opaque text returned for an unexpected internal exception.
+      OPAQUE_TOOL_ERROR = "Internal error executing tool".freeze
+
+      ToolDefinition   = Struct.new(:name, :description, :input_schema, :handler, keyword_init: true)
+      PromptDefinition = Struct.new(:name, :description, :arguments, :handler, keyword_init: true)
+
+      # A focused, dependency-free validator for the subset of JSON Schema the
+      # DSL actually uses: object `required` and top-level `properties` types
+      # (plus `additionalProperties: false` to reject unknown fields). It is not
+      # a full JSON-Schema implementation — the aim is to keep obviously wrong
+      # calls out of handlers, not to validate deep structures.
+      module SchemaValidator
+        # JSON Schema type name => a predicate on the (string-keyed, JSON-parsed)
+        # argument value.
+        TYPE_CHECKS = {
+          "string"  => ->(v) { v.is_a?(String) },
+          "integer" => ->(v) { v.is_a?(Integer) },
+          "number"  => ->(v) { v.is_a?(Numeric) && !v.is_a?(TrueClass) && !v.is_a?(FalseClass) },
+          "boolean" => ->(v) { v == true || v == false },
+          "array"   => ->(v) { v.is_a?(Array) },
+          "object"  => ->(v) { v.is_a?(Hash) },
+          "null"    => ->(v) { v.nil? }
+        }.freeze
+
+        # Returns a human-readable violation string, or nil when arguments
+        # satisfy the schema. A non-object schema (or a schema whose type is not
+        # "object") is treated as "no constraints" — validation is best-effort.
+        def self.violation(input_schema, arguments)
+          schema = normalize(input_schema)
+          return nil unless schema.is_a?(Hash)
+
+          type = schema["type"]
+          return nil if type && type != "object"
+          return "arguments must be an object" unless arguments.is_a?(Hash)
+
+          required_violation(schema, arguments) ||
+            additional_violation(schema, arguments) ||
+            property_type_violation(schema, arguments)
+        end
+
+        def self.required_violation(schema, arguments)
+          missing = Array(schema["required"]).reject { |name| arguments.key?(name.to_s) }
+          "missing required argument(s): #{missing.join(', ')}" if missing.any?
+        end
+
+        def self.additional_violation(schema, arguments)
+          return nil unless schema["additionalProperties"] == false
+
+          allowed = (schema["properties"] || {}).keys
+          extra   = arguments.keys - allowed
+          "unexpected argument(s): #{extra.join(', ')}" if extra.any?
+        end
+
+        def self.property_type_violation(schema, arguments)
+          properties = schema["properties"]
+          return nil unless properties.is_a?(Hash)
+
+          properties.each do |name, spec|
+            next unless arguments.key?(name)
+
+            expected = spec.is_a?(Hash) ? spec["type"] : nil
+            next unless expected
+
+            checks = Array(expected).map { |t| TYPE_CHECKS[t] }
+            # If any declared type is unknown to us, don't enforce this property
+            # (best-effort — we can't judge what we don't understand).
+            next if checks.any?(&:nil?)
+
+            ok = checks.any? { |check| check.call(arguments[name]) }
+            return "argument '#{name}' must be #{Array(expected).join(' or ')}" unless ok
+          end
+          nil
+        end
+
+        # Schemas are declared with symbol keys in the DSL but arrive JSON-parsed
+        # (string keys) over the wire; normalize to string keys so both match.
+        def self.normalize(value)
+          return value unless value.is_a?(Hash) || value.is_a?(Array)
+
+          JSON.parse(JSON.generate(value))
+        end
+      end
+
+      class << self
+        def server_name(value = nil)
+          @server_name = value.to_s if value
+
+          klass = self
+          while klass.respond_to?(:own_tools)
+            explicit = klass.instance_variable_get(:@server_name)
+            return explicit if explicit
+            klass = klass.superclass
+          end
+
+          name.to_s.demodulize.underscore
+        end
+
+        def tool(tool_name, description:, input_schema:, &block)
+          raise ArgumentError, "tool '#{tool_name}' requires a block" unless block
+
+          own_tools[tool_name.to_s] = ToolDefinition.new(
+            name:         tool_name.to_s,
+            description:  description,
+            input_schema: input_schema,
+            handler:      block
+          )
+        end
+
+        # A reusable, parameterized message template served via prompts/get.
+        # The block returns a String (wrapped into a single user message) or a
+        # ready-made messages array.
+        #
+        #   prompt "audit_report",
+        #          description: "Skeleton for a period audit",
+        #          arguments: [ { name: "period", description: "e.g. 2026-Q1", required: true } ] do |args, ctx|
+        #     "Audit the #{args['period']} period and list anomalies."
+        #   end
+        def prompt(prompt_name, description:, arguments: [], &block)
+          raise ArgumentError, "prompt '#{prompt_name}' requires a block" unless block
+
+          own_prompts[prompt_name.to_s] = PromptDefinition.new(
+            name:        prompt_name.to_s,
+            description: description,
+            arguments:   arguments,
+            handler:     block
+          )
+        end
+
+        # Declared tools, including those inherited from parent toolsets.
+        def tools
+          parent = superclass.respond_to?(:tools) ? superclass.tools : {}
+          parent.merge(own_tools)
+        end
+
+        def own_tools
+          @own_tools ||= {}
+        end
+
+        def prompts
+          parent = superclass.respond_to?(:prompts) ? superclass.prompts : {}
+          parent.merge(own_prompts)
+        end
+
+        def own_prompts
+          @own_prompts ||= {}
+        end
+      end
+
+      def deliver(payload, session_id: nil, context: nil)
+        request = json_boundary(payload)
+
+        body =
+          case request["method"]
+          when "initialize"   then handle_initialize(request, context) { |sid| session_id = sid }
+          when "tools/list"   then success_envelope(request, "tools" => tool_specs)
+          when "tools/call"   then handle_tools_call(request, context)
+          when "prompts/list" then success_envelope(request, "prompts" => prompt_specs)
+          when "prompts/get"  then handle_prompts_get(request, context)
+          else error_envelope(request, -32601, "Method not found: #{request['method']}")
+          end
+
+        Result.new(
+          body:         body,
+          session_id:   session_id,
+          raw_request:  payload,
+          raw_response: body,
+          status:       200
+        )
+      end
+
+      # Toolsets are stateless by default (nil => SolidLoop synthesizes a
+      # session id). Override to mint a real session id and receive it back
+      # on subsequent calls.
+      def on_initialize(_params, _context)
+        nil
+      end
+
+      private
+
+      def handle_initialize(request, context)
+        yield on_initialize(request["params"] || {}, context)
+
+        success_envelope(request,
+          "protocolVersion" => "2024-11-05",
+          "capabilities"    => capabilities,
+          "serverInfo"      => { "name" => self.class.server_name, "version" => SolidLoop::VERSION })
+      end
+
+      # prompts is advertised only when prompts are actually declared.
+      def capabilities
+        caps = { "tools" => {} }
+        caps["prompts"] = {} if self.class.prompts.any?
+        caps
+      end
+
+      def handle_tools_call(request, context)
+        params     = request["params"] || {}
+        definition = self.class.tools[params["name"].to_s]
+        return error_envelope(request, -32602, "Unknown tool: #{params['name']}") unless definition
+
+        arguments = params["arguments"] || {}
+
+        # Enforce the advertised inputSchema before dispatch: missing/wrong-typed
+        # arguments are a caller error (-32602), not something the handler should
+        # ever see. Returned as a protocol error, distinct from an isError result.
+        violation = SchemaValidator.violation(definition.input_schema, arguments)
+        return error_envelope(request, -32602, "Invalid params: #{violation}") if violation
+
+        # Surface the wire-level idempotency key uniformly: handlers reached
+        # through Mcp::Server (external client) get it from `_meta` just like
+        # in-process handlers get it from McpToolExecutionService.
+        if context && context.idempotency_key.nil?
+          context.idempotency_key = params.dig("_meta", "solidloop/idempotencyKey")
+        end
+
+        value = definition.handler.call(arguments, context)
+        success_envelope(request, tool_result(value))
+      rescue PublicToolError => e
+        # Intentional, user-facing message — passed through verbatim.
+        success_envelope(request,
+          "content" => [ { "type" => "text", "text" => e.message } ],
+          "isError" => true)
+      rescue StandardError => e
+        # Unexpected internal fault: log the detail, return an opaque message so
+        # SQL/paths/tenant/credential detail never leak to the public boundary.
+        log_tool_error(definition.name, e)
+        success_envelope(request,
+          "content" => [ { "type" => "text", "text" => OPAQUE_TOOL_ERROR } ],
+          "isError" => true)
+      end
+
+      def log_tool_error(tool_name, error)
+        return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+        Rails.logger.error(
+          "SolidLoop::Mcp::Toolset tool '#{tool_name}' raised " \
+          "#{error.class}: #{error.message}\n#{Array(error.backtrace).take(10).join("\n")}"
+        )
+      end
+
+      # Unlike tools/call there is no isError shape for prompts, so handler
+      # exceptions become a -32603 protocol error instead of propagating.
+      def handle_prompts_get(request, context)
+        params     = request["params"] || {}
+        definition = self.class.prompts[params["name"].to_s]
+        return error_envelope(request, -32602, "Unknown prompt: #{params['name']}") unless definition
+
+        arguments = params["arguments"] || {}
+        required  = json_boundary(definition.arguments).select { |a| a["required"] }.map { |a| a["name"] }
+        missing   = required.reject { |name| arguments.key?(name) }
+        if missing.any?
+          return error_envelope(request, -32602, "Missing required prompt arguments: #{missing.join(', ')}")
+        end
+
+        value = definition.handler.call(arguments, context)
+        success_envelope(request,
+          "description" => definition.description,
+          "messages"    => prompt_messages(value))
+      rescue PublicToolError => e
+        # Intentional, user-facing message — passed through verbatim.
+        error_envelope(request, -32603, e.message)
+      rescue StandardError => e
+        # Prompts have no isError shape, so an internal fault becomes a -32603
+        # protocol error — but with an OPAQUE message (same leak boundary as
+        # tools/call), logging the detail server-side.
+        log_tool_error("prompt:#{params['name']}", e)
+        error_envelope(request, -32603, OPAQUE_TOOL_ERROR)
+      end
+
+      def prompt_messages(value)
+        case value
+        when Array then json_boundary(value)
+        else [ { "role" => "user", "content" => { "type" => "text", "text" => value.to_s } } ]
+        end
+      end
+
+      def prompt_specs
+        self.class.prompts.values.map do |p|
+          spec = { "name" => p.name, "description" => p.description }
+          spec["arguments"] = json_boundary(p.arguments) if p.arguments.any?
+          spec
+        end
+      end
+
+      def tool_specs
+        self.class.tools.values.map do |t|
+          {
+            "name"        => t.name,
+            "description" => t.description,
+            "inputSchema" => json_boundary(t.input_schema)
+          }
+        end
+      end
+
+      def tool_result(value)
+        case value
+        when Hash
+          structured = json_boundary(value)
+          {
+            "content"           => [ { "type" => "text", "text" => JSON.generate(structured) } ],
+            "structuredContent" => structured
+          }
+        else
+          { "content" => [ { "type" => "text", "text" => value.to_s } ] }
+        end
+      end
+
+      def success_envelope(request, result)
+        { "jsonrpc" => "2.0", "id" => request["id"], "result" => result }
+      end
+
+      def error_envelope(request, code, message)
+        { "jsonrpc" => "2.0", "id" => request["id"], "error" => { "code" => code, "message" => message } }
+      end
+
+      def json_boundary(value)
+        JSON.parse(JSON.generate(value))
+      end
+    end
+  end
+end

data/lib/solid_loop/mcp/transport.rb

@@ -0,0 +1,20 @@
+module SolidLoop
+  module Mcp
+    # The transport port: any object that can deliver a JSON-RPC envelope to an
+    # MCP server and return the response. See docs/guides/mcp_transports.md for
+    # the full contract (session identity, error semantics, thread-safety,
+    # mandatory raw request/response for wire logs).
+    module Transport
+      # payload    — raw JSON-RPC request Hash ({jsonrpc:, id:, method:, params:})
+      # session_id — nil for `initialize`; afterwards whatever initialize returned
+      # context    — SolidLoop::Mcp::CallContext (agent:, loop:), may be nil.
+      #              HTTP transports typically ignore it (auth travels in
+      #              headers); in-process transports may use it to reach
+      #              domain state without a network hop.
+      # returns    — SolidLoop::Mcp::Result
+      def deliver(payload, session_id: nil, context: nil)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/solid_loop/mcp.rb

@@ -0,0 +1,25 @@
+require "solid_loop/mcp/transport"
+require "solid_loop/mcp/result"
+require "solid_loop/mcp/call_context"
+require "solid_loop/mcp/principal"
+require "solid_loop/mcp/http_transport"
+require "solid_loop/mcp/stdio_transport"
+require "solid_loop/mcp/toolset"
+require "solid_loop/mcp/client_factory"
+require "solid_loop/mcp/server"
+
+module SolidLoop
+  # MCP transport port and built-in adapters. See docs/guides/mcp_transports.md.
+  module Mcp
+    # Builds a mountable Rack endpoint serving one toolset to external MCP
+    # clients. See Mcp::Server and docs/decisions/mcp-server.md.
+    #
+    # mount: a stable identity for THIS mount point. `server_name` comes from
+    # the toolset class, so two mounts of the same class would share one session
+    # namespace; pass a distinct `mount:` to keep them isolated. Defaults to the
+    # toolset's server_name.
+    def self.server(toolset, auth:, mount: nil)
+      Server.new(toolset, auth: auth, mount: mount)
+    end
+  end
+end

data/lib/solid_loop/mcp_client.rb

@@ -0,0 +1,176 @@
+require "solid_loop/mcp"
+
+module SolidLoop
+  class McpError < StandardError; end
+  class McpSessionInvalidError < McpError; end
+  class McpToolError < McpError; end
+
+  # Thin MCP protocol layer: builds JSON-RPC envelopes and delegates I/O to a
+  # transport implementing SolidLoop::Mcp::Transport. Defaults to
+  # Mcp::HttpTransport built from the url/token/headers keywords.
+  class McpClient
+    attr_reader :last_result, :transport
+
+    def initialize(url = nil, token: nil, timeout: 60, headers: {}, initialize_params: {}, stateless: false, transport: nil, context: nil)
+      @initialize_params = initialize_params
+      @stateless = stateless
+      @transport = transport || Mcp::HttpTransport.new(url: url, token: token, timeout: timeout, headers: headers)
+      @context = context
+      @last_result = nil
+    end
+
+    def wire_log
+      return "No response captured" unless last_result
+
+      lines = [
+        "request: #{pretty_json(last_result.raw_request)}",
+        "status: #{last_result.status}",
+        "response: #{pretty_json(last_result.raw_response)}"
+      ]
+      lines << "stderr: #{last_result.stderr}" if last_result.stderr.present?
+      lines.join("\n")
+    end
+
+    def initialize_session
+      base_params = {
+        protocolVersion: "2024-11-05",
+        capabilities:    {},
+        clientInfo:      { name: "solid_loop", version: SolidLoop::VERSION }
+      }
+
+      deliver(envelope("initialize", base_params.deep_merge(@initialize_params)))
+
+      unless success?
+        raise McpError, "Failed to initialize MCP session: #{last_result.status} #{body_string}"
+      end
+      if (error = protocol_error)
+        raise McpError, "Failed to initialize MCP session: #{error.to_json}"
+      end
+
+      last_result.session_id || stateless_session_id
+    end
+
+    def list_tools(session_id)
+      deliver(envelope("tools/list", {}), session_id: session_id)
+      validate_result!(session_id)
+
+      body_hash.dig("result", "tools") || []
+    end
+
+    # meta: optional MCP `_meta` hash for the tools/call params (e.g. the
+    # per-ToolCall idempotency key under "solidloop/idempotencyKey").
+    def call_tool(session_id, name, arguments, meta: nil)
+      params = { name: name, arguments: arguments }
+      params[:_meta] = meta if meta.present?
+
+      deliver(envelope("tools/call", params), session_id: session_id)
+      validate_result!(session_id)
+
+      process_tool_result(last_result.body)
+    end
+
+    # Capabilities advertised by the server in the last initialize response.
+    # Meaningful right after initialize_session.
+    def server_capabilities
+      body_hash.dig("result", "capabilities") || {}
+    end
+
+    def last_tool_error?
+      body_hash.dig("result", "isError") == true
+    end
+
+    def list_prompts(session_id)
+      deliver(envelope("prompts/list", {}), session_id: session_id)
+      validate_result!(session_id)
+
+      body_hash.dig("result", "prompts") || []
+    end
+
+    # Returns the MCP prompt result: { "description" => ..., "messages" => [...] }.
+    def get_prompt(session_id, name, arguments = {})
+      deliver(envelope("prompts/get", { name: name, arguments: arguments }), session_id: session_id)
+      validate_result!(session_id)
+
+      body_hash["result"] || {}
+    end
+
+    def list_resources(session_id)
+      deliver(envelope("resources/list", {}), session_id: session_id)
+      validate_result!(session_id)
+
+      body_hash.dig("result", "resources") || []
+    end
+
+    # Returns the MCP resource contents array (text and/or blob entries).
+    def read_resource(session_id, uri)
+      deliver(envelope("resources/read", { uri: uri }), session_id: session_id)
+      validate_result!(session_id)
+
+      body_hash.dig("result", "contents") || []
+    end
+
+    private
+
+    # Resets last_result first so a transport-level raise never leaves the
+    # previous call's result behind — Events would record the wrong envelope.
+    def deliver(payload, session_id: nil)
+      @last_result = nil
+      @last_result = transport.deliver(payload, session_id: session_id, context: @context)
+    end
+
+    def envelope(method, params)
+      { jsonrpc: "2.0", id: SecureRandom.uuid, method: method, params: params }
+    end
+
+    def success?
+      (200..299).cover?(last_result.status)
+    end
+
+    def validate_result!(session_id)
+      unless success?
+        if [ 401, 404 ].include?(last_result.status)
+          raise McpSessionInvalidError, "Session #{session_id} is invalid"
+        end
+
+        raise McpError, "MCP Error (HTTP #{last_result.status}): #{body_string}"
+      end
+
+      if (error = protocol_error)
+        raise McpError, "MCP protocol error #{error['code']}: #{error['message']}"
+      end
+    end
+
+    def protocol_error
+      error = body_hash["error"]
+      error.is_a?(Hash) ? error : nil
+    end
+
+    def body_hash
+      last_result.body.is_a?(Hash) ? last_result.body : {}
+    end
+
+    def body_string
+      body = last_result.body
+      body.is_a?(Hash) ? body.to_json : body.to_s
+    end
+
+    def stateless_session_id
+      raise McpError, "Mcp-Session-Id header missing in response" unless @stateless
+      SecureRandom.uuid
+    end
+
+    def pretty_json(payload)
+      payload.is_a?(String) ? payload : JSON.pretty_generate(payload)
+    end
+
+    def process_tool_result(body)
+      content = body.is_a?(Hash) ? body.dig("result", "content") : nil
+      if content.is_a?(Array)
+        texts = content.select { |item| item["type"] == "text" }.map { |item| item["text"] }
+        texts.join("\n")
+      else
+        body.is_a?(Hash) ? JSON.pretty_generate(body) : body.to_s
+      end
+    end
+  end
+end

data/lib/solid_loop/pipeline/builder.rb

@@ -0,0 +1,38 @@
+module SolidLoop
+  class Pipeline
+    class Builder
+      attr_reader :middlewares
+
+      def initialize(middlewares = [])
+        @middlewares = middlewares.dup
+      end
+
+      def use(middleware)
+        @middlewares << middleware
+      end
+
+      def insert_before(target, middleware)
+        index = @middlewares.index(target) || 0
+        @middlewares.insert(index, middleware)
+      end
+
+      def insert_after(target, middleware)
+        index = @middlewares.index(target) || @middlewares.size - 1
+        @middlewares.insert(index + 1, middleware)
+      end
+
+      def replace(target, middleware)
+        index = @middlewares.index(target)
+        if index
+          @middlewares[index] = middleware
+        else
+          @middlewares << middleware
+        end
+      end
+
+      def delete(target)
+        @middlewares.delete(target)
+      end
+    end
+  end
+end

data/lib/solid_loop/pipeline/context.rb

@@ -0,0 +1,61 @@
+module SolidLoop
+  class Pipeline
+    class Context
+      # Inputs
+      attr_accessor :loop, :agent, :model_config
+      attr_accessor :messages # ActiveRecord relation
+      attr_accessor :payload  # The hash that will be sent to the LLM (messages, tools, model, etc)
+      attr_accessor :triggering_message
+
+      # Working state
+      attr_accessor :messages_text_for_token_estimation
+      attr_accessor :event
+      attr_accessor :assistant_message
+      attr_accessor :request_started_at, :first_token_at, :content_started_at, :last_ui_update_at
+      attr_accessor :aggregator
+      attr_accessor :log_buffer, :debug_output
+      attr_accessor :timings
+
+      # Results
+      attr_accessor :duration
+      attr_accessor :request_url
+      attr_accessor :response # Faraday response object
+      # Captured (non-2xx) failing-response envelope so the wire-log Event can
+      # persist status/headers/body even when the streaming adapter has already
+      # drained response.body via on_data.
+      attr_accessor :error_status, :error_headers, :error_body
+      attr_accessor :normalized_data # Data normalized by the dialect
+      attr_accessor :exception
+      attr_accessor :detected_reasoning_field
+      attr_accessor :metadata # Hash for middlewares to share custom state
+      attr_accessor :execution_token
+      # The background lease renewer for THIS turn. ResponseParsing
+      # (and any other canonical-write site) calls `heartbeat&.check!` before
+      # committing, so a worker whose lease was lost mid-stream raises
+      # SolidLoop::LostLease instead of writing a turn it no longer owns.
+      attr_accessor :heartbeat
+
+      def initialize(loop_id:, execution_token: nil)
+        @loop = SolidLoop::Loop.find(loop_id)
+        @execution_token = execution_token
+        @metadata = {}
+        @payload = {}
+      end
+
+      def loop_active?
+        # Fail closed: a context without a generation token never owns the loop.
+        @loop.running? && @execution_token.present? && @loop.execution_token == @execution_token
+      end
+
+      def loop_active_fresh?
+        @loop.reload
+        loop_active?
+      end
+
+      # Used by inner layers to record timing precisely
+      def mark_request_started!
+        @request_started_at = Time.current
+      end
+    end
+  end
+end