solid_loop 0.0.4

data/lib/solid_loop/mcp/client_factory.rb

@@ -0,0 +1,61 @@
+module SolidLoop
+  module Mcp
+    # Resolves an agent `mcps` entry into a transport and a protocol client.
+    # Three entry forms (name: is required in all):
+    #   { name:, url:, api_token:, ... }  — HTTP sugar   -> Mcp::HttpTransport
+    #   { name:, toolset: SearchTools }   — in-process    -> the toolset itself
+    #   { name:, transport: object }      — general form  -> any Mcp::Transport
+    module ClientFactory
+      module_function
+
+      def client_for(mcp_config, context: nil)
+        validate_session_recovery!(mcp_config)
+
+        SolidLoop::McpClient.new(
+          transport:         transport_for(mcp_config),
+          context:           context,
+          initialize_params: mcp_config[:initialize_params] || {},
+          stateless:         mcp_config.fetch(:stateless, transport_kind(mcp_config) != "http")
+        )
+      end
+
+      def transport_for(mcp_config)
+        if (toolset = mcp_config[:toolset])
+          toolset.is_a?(Class) ? toolset.new : toolset
+        elsif mcp_config[:transport]
+          mcp_config[:transport]
+        elsif mcp_config[:url]
+          HttpTransport.new(
+            url:     mcp_config[:url],
+            token:   mcp_config[:api_token] || ENV["MCP_API_TOKEN"],
+            timeout: mcp_config[:timeout] || 60,
+            headers: mcp_config[:custom_headers] || {}
+          )
+        else
+          raise SolidLoop::McpError,
+                "MCP config '#{mcp_config[:name]}' must provide url:, toolset:, or transport:"
+        end
+      end
+
+      # Validated eagerly — a typo must surface at session init, not months
+      # later when a session actually expires.
+      def validate_session_recovery!(mcp_config)
+        value = mcp_config.fetch(:session_recovery, :auto).to_sym
+        return if %i[auto fail].include?(value)
+
+        raise SolidLoop::McpError,
+              "Invalid session_recovery #{value.inspect} for '#{mcp_config[:name]}' (use :auto or :fail)"
+      end
+
+      def transport_kind(mcp_config)
+        return "local" if mcp_config[:toolset]
+
+        if (transport = mcp_config[:transport])
+          return transport.is_a?(StdioTransport) ? "stdio" : "custom"
+        end
+
+        "http"
+      end
+    end
+  end
+end

data/lib/solid_loop/mcp/http_transport.rb

@@ -0,0 +1,52 @@
+require "faraday"
+
+module SolidLoop
+  module Mcp
+    # Reference adapter: Streamable-HTTP MCP over Faraday. JSON request/response,
+    # `Authorization: Bearer`, `Mcp-Session-Id` header mapped to the port's
+    # session_id, custom headers, timeout.
+    class HttpTransport
+      include Transport
+
+      def initialize(url:, token: nil, timeout: 60, headers: {})
+        @url = url
+        @token = token
+        @timeout = timeout
+        @extra_headers = headers
+      end
+
+      def deliver(payload, session_id: nil, context: nil)
+        response = connection(session_id).post("", payload)
+
+        Result.new(
+          body:         response.body,
+          session_id:   response.headers["Mcp-Session-Id"],
+          raw_request:  payload,
+          raw_response: response.body,
+          status:       response.status
+        )
+      rescue Faraday::Error => e
+        raise SolidLoop::McpError, "MCP transport error: #{e.class}: #{e.message}"
+      end
+
+      private
+
+      def connection(session_id = nil)
+        Faraday.new(url: @url) do |f|
+          f.request :json
+          f.response :json
+          f.options.timeout = @timeout
+          f.headers = default_headers(session_id)
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      def default_headers(session_id = nil)
+        h = { "Content-Type" => "application/json" }
+        h["Authorization"] = "Bearer #{@token}" if @token.present?
+        h["Mcp-Session-Id"] = session_id if session_id
+        h.merge(@extra_headers)
+      end
+    end
+  end
+end

data/lib/solid_loop/mcp/principal.rb

@@ -0,0 +1,82 @@
+module SolidLoop
+  module Mcp
+    # The authenticated caller identity returned by an Mcp::Server authorizer.
+    #
+    # An authorizer responds to `call(token, request) -> principal | nil`. To
+    # bind sessions to the caller (so principal B cannot ride principal A's
+    # session_id) the server needs a STABLE identity key, not just a display
+    # label. This value object carries both:
+    #
+    #   key   — stable, opaque identity used for session ownership + audit. Two
+    #           requests are the same principal iff their keys are equal.
+    #   label — human-readable name for the admin UI (may collide / change).
+    #
+    # Authorizer contract: `key` MUST be stable across a principal's requests and
+    # unique per principal. Two callers whose keys collide (e.g. an authorizer
+    # returning "" or two records that stringify identically) would share a
+    # session namespace — the same trust boundary the authorizer already owns.
+    #
+    # Backward compatibility: authorizers may still return a bare value (String,
+    # Symbol, or any object) and `Principal.wrap` derives a STABLE key from it:
+    #
+    #   * a Principal          — used as-is
+    #   * an object with        #key AND #label — those are the key/label
+    #   * an ActiveRecord-ish   object (responds to #to_global_id) — the GID URI
+    #                           is the stable key; #to_s (or the GID) the label
+    #   * anything else         — `to_s` is BOTH key and label
+    #
+    # The GID branch matters because a bare object's default #to_s embeds the
+    # memory address (unstable per request); using it as the session key would
+    # mean a caller could never reuse their own session. `to_context` always
+    # returns the ORIGINAL value, so tool handlers keep receiving what the
+    # authorizer returned (a String, a User record, …) unchanged.
+    class Principal
+      attr_reader :key, :label
+
+      def self.wrap(value)
+        return value if value.is_a?(Principal)
+
+        if value.respond_to?(:key) && value.respond_to?(:label)
+          new(key: value.key.to_s, label: value.label.to_s, principal: value)
+        elsif (gid = stable_gid(value))
+          new(key: gid, label: label_for(value, gid), principal: value)
+        else
+          new(key: value.to_s, label: value.to_s, principal: value)
+        end
+      end
+
+      # The GlobalID URI for a persisted record, or nil (unpersisted records
+      # raise; non-GID objects don't respond) — the caller then falls back to
+      # the bare to_s key.
+      def self.stable_gid(value)
+        return nil unless value.respond_to?(:to_global_id)
+
+        value.to_global_id.to_s
+      rescue StandardError
+        nil
+      end
+
+      # Prefer a human-readable #to_s when the object overrides it (not the
+      # default "#<Klass:0x...>"); otherwise fall back to the GID.
+      def self.label_for(value, gid)
+        str = value.to_s
+        str.start_with?("#<") ? gid : str
+      end
+
+      # `principal` is the raw object the authorizer returned — handlers receive
+      # THIS via CallContext#principal, so existing handlers that expect the raw
+      # value (a String, a User, …) keep working unchanged.
+      def initialize(key:, label:, principal:)
+        @key       = key
+        @label     = label
+        @principal = principal
+      end
+
+      # What tool handlers see as ctx.principal. For a bare-value authorizer this
+      # is the original value (backward compatible); otherwise the wrapped object.
+      def to_context
+        @principal
+      end
+    end
+  end
+end

data/lib/solid_loop/mcp/result.rb

@@ -0,0 +1,13 @@
+module SolidLoop
+  module Mcp
+    Result = Struct.new(
+      :body,         # JSON-RPC response Hash (result or error envelope)
+      :session_id,   # set by `initialize`; echoed back otherwise; nil => stateless
+      :raw_request,  # exact envelope sent   — recorded to wire logs / Events
+      :raw_response, # exact envelope received — recorded to wire logs / Events
+      :status,       # transport status code (HTTP status or synthetic 200/500)
+      :stderr,       # optional transport diagnostics for the wire log (stdio stderr)
+      keyword_init: true
+    )
+  end
+end

data/lib/solid_loop/mcp/server.rb

@@ -0,0 +1,246 @@
+module SolidLoop
+  module Mcp
+    # Mountable Rack endpoint serving ONE toolset to external MCP clients over
+    # Streamable HTTP — the mirror image of HttpTransport over the same port.
+    # The POST body goes straight into Toolset#deliver, the exact method the
+    # in-process agent path calls, so local and remote behavior cannot drift.
+    # See docs/decisions/mcp-server.md.
+    #
+    #   # config/routes.rb (host app)
+    #   mount SolidLoop::Mcp.server(RpcTools, auth: McpAuth.new) => "/rpc"
+    #
+    # Fail-closed: auth: is required at construction. The authorizer is any
+    # object responding to call(token, request) -> principal | nil; nil means
+    # 401 with an empty body. The returned principal is normalized via
+    # Mcp::Principal.wrap (a bare value becomes both key and label; an object
+    # with #key/#label separates identity from display) and the raw value
+    # becomes CallContext#principal for every tool handler.
+    #
+    # Principal binding: the session row records the principal's stable KEY and
+    # every in-session POST/DELETE lookup is scoped to (mount, session_id,
+    # principal_key). A different valid principal who obtains another caller's
+    # session_id therefore cannot use or terminate it (404, as for any unknown
+    # session). Two mounts of the same toolset class are separated by mount:.
+    #
+    # Sessions: every initialize creates a McpInboundSession row (honoring the
+    # toolset's on_initialize minting, else a UUID) returned in Mcp-Session-Id.
+    # Every other request must carry that header — 400 without it, 404 for an
+    # unknown or terminated session. DELETE terminates the session but keeps
+    # the row: a client must not be able to erase its own audit trail. Every
+    # request that reaches a session writes a SolidLoop::Event (loop-less,
+    # eventable = the session) with the JSON-RPC envelopes and a wire log.
+    #
+    # Protocol scope is deliberately narrow (see the decision doc): single
+    # JSON-RPC request per POST, notifications -> 202, no SSE (GET -> 405),
+    # no batching (-32600). Errors raised inside tool handlers become isError
+    # results in Toolset#deliver; anything else propagates — internal bugs
+    # must surface, not dissolve into JSON-RPC envelopes.
+    class Server
+      ALLOWED_METHODS = %w[POST DELETE].freeze
+
+      def initialize(toolset, auth:, mount: nil)
+        unless auth.respond_to?(:call)
+          raise ArgumentError,
+                "SolidLoop::Mcp.server requires auth: responding to " \
+                "call(token, request) -> principal | nil (see docs/decisions/mcp-server.md)"
+        end
+
+        @toolset = toolset.is_a?(Class) ? toolset.new : toolset
+        @auth    = auth
+        @mount   = mount&.to_s
+      end
+
+      def call(env)
+        request = ActionDispatch::Request.new(env)
+
+        # 405 before auth: it reveals nothing and keeps method probes away
+        # from the authorizer. Everything else authenticates first.
+        return method_not_allowed unless ALLOWED_METHODS.include?(request.request_method)
+
+        authorized = @auth.call(bearer_token(request), request)
+        # Deny on any falsey return, not just nil: the contract is truthy principal
+        # => allow. A contract-violating `false` must never authenticate (it would
+        # otherwise mint a "false"-keyed session shared by every such caller).
+        return unauthorized unless authorized
+        principal = Principal.wrap(authorized)
+
+        if request.request_method == "DELETE"
+          handle_delete(request, principal)
+        else
+          handle_post(request, principal)
+        end
+      end
+
+      private
+
+      def handle_post(request, principal)
+        payload = JSON.parse(request.body.read)
+
+        return rpc_error(-32600, "Batch requests are not supported") if payload.is_a?(Array)
+        return rpc_error(-32600, "Invalid JSON-RPC request") unless valid_jsonrpc?(payload)
+        return serve_initialize(request, payload, principal) if payload["method"] == "initialize"
+
+        session = resolve_session(request, principal)
+        return session unless session.is_a?(McpInboundSession)
+
+        serve_in_session(request, payload, principal, session)
+      rescue JSON::ParserError
+        rpc_error(-32700, "Parse error")
+      end
+
+      def serve_initialize(request, payload, principal)
+        started_at = Time.current
+        result     = @toolset.deliver(payload, context: call_context(principal))
+
+        session = McpInboundSession.create!(
+          server_name:   server_name,
+          mount_key:     mount_key,
+          session_id:    result.session_id || SecureRandom.uuid,
+          principal:     principal.label,
+          principal_key: principal.key,
+          last_used_at:  Time.current
+        )
+        record_event(session, request, payload, result, started_at, principal)
+
+        respond(result, session_id: session.session_id)
+      end
+
+      def serve_in_session(request, payload, principal, session)
+        started_at = Time.current
+        session.touch(:last_used_at)
+
+        # Notifications are acknowledged, logged, and not dispatched — the
+        # toolset protocol surface is request/response only.
+        unless payload.key?("id")
+          record_event(session, request, payload, nil, started_at, principal)
+          return accepted
+        end
+
+        result = @toolset.deliver(payload, session_id: session.session_id,
+                                           context:    call_context(principal))
+        record_event(session, request, payload, result, started_at, principal)
+
+        respond(result)
+      end
+
+      def handle_delete(request, principal)
+        session = resolve_session(request, principal)
+        return session unless session.is_a?(McpInboundSession)
+
+        started_at = Time.current
+        session.update!(terminated_at: Time.current, last_used_at: Time.current)
+        record_event(session, request, {}, nil, started_at, principal)
+
+        no_content
+      end
+
+      # McpInboundSession, or a Rack error response: 400 without the header,
+      # 404 for an unknown or terminated session (the client's signal to
+      # re-initialize).
+      #
+      # Lookup is scoped to (mount_key, session_id, principal_key): a valid
+      # principal B who obtains principal A's session_id cannot use or delete it
+      # — B's principal_key does not match A's row, so the row is invisible and
+      # B gets a 404 exactly as for any unknown session. The `principal` scope
+      # ALSO closes the mismatch where B's key differs from the session owner's.
+      def resolve_session(request, principal)
+        header = request.headers["Mcp-Session-Id"]
+        return bad_request if header.blank?
+
+        McpInboundSession.active
+          .where(mount_key: mount_key, session_id: header, principal_key: principal.key)
+          .first || not_found
+      end
+
+      def call_context(principal)
+        CallContext.new(agent: nil, loop: nil, principal: principal.to_context)
+      end
+
+      def server_name
+        @toolset.class.server_name
+      end
+
+      # Stable identity for this mount: the explicit mount: option, else the
+      # toolset's server_name (so a single mount keeps its historical namespace).
+      def mount_key
+        @mount || server_name
+      end
+
+      def record_event(session, request, payload, result, started_at, principal)
+        SolidLoop::Event.create!(
+          eventable:     session,
+          name:          event_name(request, payload),
+          http_method:   request.request_method,
+          url:           request.path,
+          principal_key: principal&.key,
+          request_data:  payload,
+          response_data: result ? result.raw_response || {} : {},
+          duration:      Time.current - started_at,
+          log:           wire_log(payload, result)
+        )
+      end
+
+      def event_name(request, payload)
+        return "mcp_inbound_terminate" if request.request_method == "DELETE"
+
+        "mcp_inbound_#{payload['method'].to_s.tr('/', '_')}"
+      end
+
+      def wire_log(payload, result)
+        lines = [ "request: #{JSON.pretty_generate(payload)}" ]
+        if result
+          lines << "status: #{result.status}"
+          lines << "response: #{JSON.pretty_generate(result.raw_response || {})}"
+        end
+        lines.join("\n")
+      end
+
+      def valid_jsonrpc?(payload)
+        payload.is_a?(Hash) && payload["jsonrpc"] == "2.0" && payload["method"].is_a?(String)
+      end
+
+      def bearer_token(request)
+        scheme, token = request.authorization.to_s.split(" ", 2)
+        token if scheme&.casecmp?("bearer")
+      end
+
+      def respond(result, session_id: nil)
+        headers = { "content-type" => "application/json" }
+        sid = session_id || result.session_id
+        headers["mcp-session-id"] = sid if sid
+        [result.status || 200, headers, [JSON.generate(result.body)]]
+      end
+
+      # Protocol errors ride HTTP 200 with a JSON-RPC error object; HTTP
+      # status codes are reserved for transport-level outcomes.
+      def rpc_error(code, message, id = nil)
+        body = { "jsonrpc" => "2.0", "id" => id, "error" => { "code" => code, "message" => message } }
+        [200, { "content-type" => "application/json" }, [JSON.generate(body)]]
+      end
+
+      def unauthorized
+        [401, {}, []]
+      end
+
+      def bad_request
+        [400, {}, []]
+      end
+
+      def not_found
+        [404, {}, []]
+      end
+
+      def accepted
+        [202, {}, []]
+      end
+
+      def no_content
+        [204, {}, []]
+      end
+
+      def method_not_allowed
+        [405, { "allow" => ALLOWED_METHODS.join(", ") }, []]
+      end
+    end
+  end
+end

data/lib/solid_loop/mcp/stdio_transport.rb

@@ -0,0 +1,224 @@
+require "open3"
+require "io/wait"
+
+module SolidLoop
+  module Mcp
+    # Child-process MCP server over stdin/stdout — restricted contract.
+    #
+    # SolidLoop executes each tool call in an independent job (any worker, any
+    # machine), so no process could own a long-lived child across rounds.
+    # Therefore the lifecycle is spawn-per-call: spawn -> `initialize`
+    # handshake -> request -> graceful shutdown (kill on timeout), all inside
+    # one `deliver`. Stateless servers only: the session id is synthetic and
+    # implies no server-side continuity; stateful stdio servers (a running
+    # shell, a browser session, a REPL sandbox) are unsupported — their
+    # in-memory state would be lost at every job boundary. This is a deliberate
+    # consequence of the durable-async core, not a transport bug.
+    #
+    # Options: command: (argv array, never a shell string), env:, cwd:,
+    # timeout: (per call, includes spawn+handshake). stderr is captured into
+    # the wire log. Spawn+handshake is typically 50-500 ms for Node/Python
+    # servers — prefer HTTP or a toolset for hot paths.
+    class StdioTransport
+      include Transport
+
+      # Mutex-guarded string buffer: the stderr drain thread and the stdout
+      # reader append concurrently (safe under the GVL, undefined elsewhere).
+      class Diagnostics
+        def initialize
+          @mutex = Mutex.new
+          @buffer = +""
+        end
+
+        def <<(text)
+          @mutex.synchronize { @buffer << text }
+          self
+        end
+
+        def to_s
+          @mutex.synchronize { @buffer.dup }
+        end
+      end
+
+      def initialize(command:, env: {}, cwd: nil, timeout: 30)
+        unless command.is_a?(Array) && command.any? && command.all?(String)
+          raise ArgumentError, "command: must be a non-empty argv Array of Strings (never a shell string)"
+        end
+
+        @command = command
+        @env = env.transform_keys(&:to_s).transform_values(&:to_s)
+        @cwd = cwd
+        @timeout = timeout
+      end
+
+      def deliver(payload, session_id: nil, context: nil)
+        request     = JSON.parse(JSON.generate(payload))
+        deadline    = now + @timeout
+        diagnostics = Diagnostics.new
+
+        body = with_server(deadline, diagnostics) do |stdin, stdout|
+          handshake(stdin, stdout, deadline, diagnostics) unless request["method"] == "initialize"
+          write_message(stdin, request, deadline, diagnostics)
+          read_response(stdout, request["id"], deadline, diagnostics)
+        end
+
+        Result.new(
+          body:         body,
+          session_id:   nil, # stateless-only: no server-side continuity between calls
+          raw_request:  payload,
+          raw_response: body,
+          status:       200,
+          stderr:       diagnostics.to_s.strip.presence
+        )
+      end
+
+      private
+
+      def with_server(deadline, diagnostics)
+        stdin, stdout, stderr, wait_thr = spawn_server
+
+        drain = Thread.new do
+          stderr.each_line { |line| diagnostics << line }
+        rescue IOError
+          nil
+        end
+
+        begin
+          result = yield(stdin, stdout)
+          safe_close(stdin)
+          wait_thr.join(remaining(deadline).clamp(0, 0.5))
+          result
+        ensure
+          terminate(wait_thr)
+          drain.join(0.5)
+          [ stdin, stdout, stderr ].each { |io| safe_close(io) }
+        end
+      end
+
+      def spawn_server
+        options = @cwd ? { chdir: @cwd } : {}
+        Open3.popen3(@env, *@command, **options)
+      rescue SystemCallError => e
+        raise SolidLoop::McpError, "MCP stdio transport failed to spawn #{@command.first.inspect}: #{e.message}"
+      end
+
+      def handshake(stdin, stdout, deadline, diagnostics)
+        init = {
+          "jsonrpc" => "2.0",
+          "id"      => "init-#{SecureRandom.uuid}",
+          "method"  => "initialize",
+          "params"  => {
+            "protocolVersion" => "2024-11-05",
+            "capabilities"    => {},
+            "clientInfo"      => { "name" => "solid_loop", "version" => SolidLoop::VERSION }
+          }
+        }
+
+        write_message(stdin, init, deadline, diagnostics)
+        response = read_response(stdout, init["id"], deadline, diagnostics)
+        if response["error"]
+          raise transport_error("MCP stdio initialize handshake failed: #{response['error']}", diagnostics)
+        end
+
+        write_message(stdin, { "jsonrpc" => "2.0", "method" => "notifications/initialized" }, deadline, diagnostics)
+      end
+
+      # Non-blocking writes under the same per-call deadline as reads: a child
+      # that never drains its stdin must not hang the job past `timeout:`.
+      def write_message(stdin, message, deadline, diagnostics)
+        data = JSON.generate(message) + "\n"
+
+        until data.empty?
+          wait = remaining(deadline)
+          raise timeout_error(diagnostics) if wait <= 0 || !stdin.wait_writable(wait)
+
+          begin
+            written = stdin.write_nonblock(data)
+            data = data.byteslice(written..)
+          rescue IO::WaitWritable
+            next
+          rescue Errno::EPIPE, IOError
+            raise transport_error("MCP stdio server closed its stdin before the request could be written", diagnostics)
+          end
+        end
+      end
+
+      def read_response(stdout, id, deadline, diagnostics)
+        buffer = +""
+
+        loop do
+          while (line = buffer.slice!(/\A[^\n]*\n/))
+            message = parse_line(line, diagnostics)
+            next unless message
+            return message if message["id"] == id
+            # Notifications and non-matching messages are skipped: the
+            # restricted contract serves exactly one request per process.
+          end
+
+          wait = remaining(deadline)
+          raise timeout_error(diagnostics) if wait <= 0 || !stdout.wait_readable(wait)
+
+          begin
+            buffer << stdout.readpartial(64 * 1024)
+          rescue EOFError
+            raise transport_error("MCP stdio server exited before responding", diagnostics)
+          end
+        end
+      end
+
+      # stdout is protocol-only per the MCP spec; anything that is not a
+      # JSON-RPC message object is kept as a diagnostic instead of failing
+      # the call.
+      def parse_line(line, diagnostics)
+        message = JSON.parse(line)
+        return message if message.is_a?(Hash)
+
+        diagnostics << "[stdout] #{line}"
+        nil
+      rescue JSON::ParserError
+        diagnostics << "[stdout] #{line}"
+        nil
+      end
+
+      def terminate(wait_thr)
+        return unless wait_thr.alive?
+
+        kill("TERM", wait_thr)
+        return if wait_thr.join(0.5)
+
+        kill("KILL", wait_thr)
+        wait_thr.join(0.5)
+      end
+
+      def kill(signal, wait_thr)
+        Process.kill(signal, wait_thr.pid)
+      rescue Errno::ESRCH
+        nil
+      end
+
+      def safe_close(io)
+        io.close unless io.closed?
+      rescue IOError
+        nil
+      end
+
+      def timeout_error(diagnostics)
+        transport_error("MCP stdio call timed out after #{@timeout}s", diagnostics)
+      end
+
+      def transport_error(message, diagnostics)
+        excerpt = diagnostics.to_s.strip
+        message += " (stderr: #{excerpt.byteslice(0, 2000)})" if excerpt.present?
+        SolidLoop::McpError.new(message)
+      end
+
+      def remaining(deadline)
+        deadline - now
+      end
+
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end