mistri 0.0.3 → 0.2.0

data/lib/mistri/event.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Mistri
+  # One event in a streamed assistant turn. A stream is one :start, then a
+  # start/delta/end trio per content block (text, thinking, or toolcall), then
+  # exactly one terminal event: :done on success or :error on failure, carrying
+  # the complete message and its stop reason.
+  #
+  # `partial` is an immutable snapshot of the assistant message so far, safe to
+  # hold across events. `content_index` is the block's position in that
+  # message's content list.
+  # origin names the sub-agent an event came from: nil for this agent's own
+  # turns, and nesting joins names left to right ("researcher>writer").
+  # duration is the tool's execution time in seconds on :tool_result
+  # events; nil where nothing ran (denials, interruptions).
+  class Event < Data.define(:type, :content_index, :delta, :content, :tool_call,
+                            :reason, :message, :error_message, :partial, :origin,
+                            :duration)
+    # The stream types come from a provider mid-turn; the loop adds
+    # :tool_result after it runs each tool, :approval_needed when a gated
+    # call parks for a human, and :compacting/:compaction around a context
+    # compaction, so one subscription sees the whole exchange.
+    TYPES = %i[
+      start
+      text_start text_delta text_end
+      thinking_start thinking_delta thinking_end
+      toolcall_start toolcall_delta toolcall_end
+      done error
+      tool_result approval_needed
+      compacting compaction
+      retry
+    ].freeze
+
+    def initialize(type:, content_index: nil, delta: nil, content: nil, tool_call: nil,
+                   reason: nil, message: nil, error_message: nil, partial: nil, origin: nil,
+                   duration: nil)
+      raise ArgumentError, "unknown event type #{type.inspect}" unless TYPES.include?(type)
+
+      super
+    end
+
+    def done? = type == :done
+
+    def error? = type == :error
+
+    def terminal? = done? || error?
+
+    # Partials are ephemeral streaming state and stay out of serialization.
+    def to_h
+      { type:, content_index:, delta:, content:, tool_call: tool_call&.to_h,
+        reason:, message: message&.to_h, error_message:, origin:, duration: }.compact
+    end
+  end
+end

data/lib/mistri/mcp/client.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Mistri
+  module MCP
+    # A Model Context Protocol client: the initialize handshake, tools/list
+    # with pagination, and tools/call, over one of two wires. url: speaks
+    # Streamable HTTP on the same persistent transport the providers use;
+    # command: spawns a local stdio server with credentials in its
+    # environment.
+    #
+    #   Mistri::MCP::Client.new(url: "https://mcp.linear.app/mcp",
+    #                           token: -> { connection.bearer_token })
+    #   Mistri::MCP::Client.new(command: ["npx", "-y", "some-mcp-server"],
+    #                           env: { "API_KEY" => key })
+    #
+    # HTTP auth is a headers hash or token: a string or a callable. A
+    # callable resolves per request, and a 401 retries once after
+    # re-resolving, so a host's refresh logic lives in one lambda. A session
+    # the server expires (404 with a session attached) transparently
+    # re-initializes, per spec.
+    #
+    # One client serializes its calls; parallel tool calls against one
+    # server queue rather than interleave.
+    class Client
+      PROTOCOL_VERSION = "2025-06-18"
+      SUPPORTED_VERSIONS = %w[2025-11-25 2025-06-18 2025-03-26 2024-11-05].freeze
+      LOOPBACK = %w[localhost 127.0.0.1 ::1].freeze
+
+      attr_reader :server_info
+
+      def initialize(url: nil, command: nil, env: {}, token: nil, headers: {},
+                     client_name: "mistri", open_timeout: 15, read_timeout: 120)
+        if [url, command].compact.length != 1
+          raise ConfigurationError, "pass exactly one of url: or command:"
+        end
+
+        if url && token && URI(url).scheme == "http" && !LOOPBACK.include?(URI(url).host)
+          raise ConfigurationError,
+                "refusing to send a bearer token over plain HTTP to #{URI(url).host}"
+        end
+
+        @wire = if url
+                  Wires::Http.new(url: url, token: token, headers: headers,
+                                  open_timeout: open_timeout, read_timeout: read_timeout)
+                else
+                  Wires::Stdio.new(command: command, env: env, read_timeout: read_timeout)
+                end
+        @client_name = client_name
+        @mutex = Mutex.new
+        @serial = 0
+        @connected = false
+      end
+
+      # The server's tools as it describes them: hashes with "name",
+      # "description", and "inputSchema". Cached; refresh: true re-lists.
+      def tools(refresh: false)
+        @mutex.synchronize do
+          @tools = nil if refresh
+          @tools ||= list_tools
+        end
+      end
+
+      def call_tool(name, arguments = {})
+        @mutex.synchronize { request("tools/call", { name: name, arguments: arguments }) }
+      end
+
+      def connect
+        @mutex.synchronize { ensure_connected }
+        self
+      end
+
+      def close
+        @wire.close
+        @connected = false
+        nil
+      end
+
+      private
+
+      def ensure_connected
+        return if @connected
+
+        result = rpc("initialize", {
+                       protocolVersion: PROTOCOL_VERSION,
+                       capabilities: {},
+                       clientInfo: { name: @client_name, version: Mistri::VERSION }
+                     })
+        version = result["protocolVersion"].to_s
+        unless SUPPORTED_VERSIONS.include?(version)
+          raise Error, "server negotiated unsupported protocol version #{version.inspect}"
+        end
+
+        @wire.protocol_version = version
+        @server_info = result["serverInfo"]
+        @wire.notify({ jsonrpc: "2.0", method: "notifications/initialized" })
+        @connected = true
+      end
+
+      def request(method, params, reconnected: false, refreshed: false)
+        ensure_connected
+        rpc(method, params)
+      rescue AuthenticationError
+        raise if refreshed || !@wire.refreshable?
+
+        # The token callable resolves fresh on retry; hosts refresh there.
+        request(method, params, reconnected: reconnected, refreshed: true)
+      rescue SessionExpired
+        raise Error, "the server expired the session twice in a row" if reconnected
+
+        @connected = false
+        @wire.reset_session
+        request(method, params, reconnected: true, refreshed: refreshed)
+      end
+
+      def rpc(method, params)
+        id = (@serial += 1)
+        payload = { jsonrpc: "2.0", id: id, method: method, params: params }
+        result = nil
+        responded = false
+        @wire.call(payload) do |record|
+          next unless record.is_a?(Hash) && record["id"] == id
+
+          responded = true
+          raise rpc_error(record["error"]) if record["error"]
+
+          result = record["result"]
+        end
+        raise Error, "the server sent no response to #{method}" unless responded
+
+        result
+      rescue ProviderError => e
+        raise SessionExpired if e.status == 404 && @wire.session?
+
+        raise
+      end
+
+      def list_tools
+        collected = []
+        cursor = nil
+        loop do
+          result = request("tools/list", cursor ? { cursor: cursor } : {})
+          collected.concat(Array(result["tools"]))
+          cursor = result["nextCursor"]
+          break unless cursor
+        end
+        collected
+      end
+
+      def rpc_error(error)
+        Error.new(error["message"] || "MCP request failed", code: error["code"])
+      end
+    end
+  end
+end

data/lib/mistri/mcp/oauth.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "net/http"
+require "securerandom"
+require "uri"
+
+module Mistri
+  module MCP
+    # The OAuth 2.1 subset the MCP spec requires of clients, as three
+    # storage-agnostic services a host calls from anywhere: a controller, a
+    # GraphQL mutation, a job. Each returns a string-keyed hash ready to
+    # persist on the host's own connection record.
+    #
+    #   flow = Mistri::MCP::OAuth.start(url: params[:url],
+    #                                   client_name: "Sendoso",
+    #                                   redirect_uri: mcp_callback_url)
+    #   # persist flow, redirect the user to flow["authorize_url"]
+    #
+    #   tokens = Mistri::MCP::OAuth.complete(code: params[:code], **persisted)
+    #   tokens = Mistri::MCP::OAuth.refresh(**persisted)
+    #
+    # Registration happens as the APPLICATION, never as the harness:
+    # client_name has no default because that identity is the host's call.
+    # Servers without dynamic registration take client_id:/client_secret:
+    # directly and skip it.
+    module OAuth
+      module_function
+
+      # Discover the server's authorization setup, register the application,
+      # and build the authorize URL. Returns everything the callback and
+      # refresh need: authorize_url, state, code_verifier, client_id,
+      # client_secret, token_auth_method, token_endpoint, resource,
+      # redirect_uri.
+      #
+      # With no scope given, the server's advertised scopes_supported are
+      # requested, and offline_access rides along when the authorization
+      # server supports it, which is what earns a refresh token from
+      # providers that require it.
+      def start(url:, client_name:, redirect_uri:, scope: nil,
+                client_id: nil, client_secret: nil)
+        resource = canonical(url)
+        resource_metadata = resource_metadata_for(url)
+        metadata = server_metadata(Array(resource_metadata["authorization_servers"]).first)
+        validate_endpoints(metadata)
+        registration = register(metadata, client_name, redirect_uri, client_id, client_secret)
+        verifier = SecureRandom.urlsafe_base64(48)
+        state = SecureRandom.urlsafe_base64(32)
+        grant = { client_id: registration["client_id"], redirect_uri: redirect_uri,
+                  verifier: verifier, state: state, resource: resource,
+                  scope: resolve_scope(scope, resource_metadata, metadata) }
+        {
+          "authorize_url" => authorize_url(metadata, grant),
+          "state" => state, "code_verifier" => verifier,
+          "client_id" => registration["client_id"],
+          "client_secret" => registration["client_secret"],
+          "token_auth_method" => registration["token_endpoint_auth_method"],
+          "token_endpoint" => metadata.fetch("token_endpoint"),
+          "resource" => resource, "redirect_uri" => redirect_uri
+        }
+      end
+
+      # Exchange the callback's code for tokens.
+      def complete(code:, code_verifier:, client_id:, token_endpoint:, resource:,
+                   redirect_uri:, client_secret: nil, token_auth_method: nil, **)
+        form = { "grant_type" => "authorization_code", "code" => code,
+                 "code_verifier" => code_verifier, "client_id" => client_id,
+                 "redirect_uri" => redirect_uri, "resource" => resource }
+        token_request(token_endpoint, form, client_secret, token_auth_method)
+      end
+
+      # Trade a refresh token for a fresh set; OAuth 2.1 rotates refresh
+      # tokens, so persist the returned one.
+      def refresh(refresh_token:, client_id:, token_endpoint:, resource:,
+                  client_secret: nil, token_auth_method: nil, **)
+        form = { "grant_type" => "refresh_token", "refresh_token" => refresh_token,
+                 "client_id" => client_id, "resource" => resource }
+        token_request(token_endpoint, form, client_secret, token_auth_method)
+      end
+
+      # -- discovery ---------------------------------------------------------
+
+      # RFC 9728: a 401's WWW-Authenticate names the resource metadata URL;
+      # servers that skip the header serve the well-known path.
+      def resource_metadata_for(url)
+        metadata_url = challenge_metadata_url(url) || well_known_resource_url(url)
+        document = get_json(metadata_url)
+        if Array(document["authorization_servers"]).empty?
+          raise Error, "#{metadata_url} names no authorization servers"
+        end
+
+        document
+      end
+
+      def challenge_metadata_url(url)
+        uri = URI(url)
+        response = http(uri) do |connection|
+          request = Net::HTTP::Post.new(uri)
+          request["Accept"] = "application/json, text/event-stream"
+          request["Content-Type"] = "application/json"
+          request.body = JSON.generate({ jsonrpc: "2.0", id: 0, method: "ping" })
+          connection.request(request)
+        end
+        challenge = response["WWW-Authenticate"].to_s
+        challenge[/resource_metadata="([^"]+)"/i, 1]
+      end
+
+      def well_known_resource_url(url)
+        uri = URI(url)
+        path = uri.path.chomp("/")
+        origin = "#{uri.scheme}://#{uri.host}:#{uri.port}"
+        "#{origin}/.well-known/oauth-protected-resource#{path unless path.empty?}"
+      end
+
+      # RFC 8414 metadata, with the OpenID Connect path as a fallback since
+      # large providers often serve only that document.
+      def server_metadata(authority)
+        uri = URI(authority)
+        origin = "#{uri.scheme}://#{uri.host}:#{uri.port}"
+        path = uri.path.chomp("/")
+        candidates = ["#{origin}/.well-known/oauth-authorization-server#{path unless path.empty?}",
+                      "#{origin}#{path}/.well-known/openid-configuration"]
+        candidates.each do |candidate|
+          document = try_json(candidate)
+          return document if document&.key?("token_endpoint")
+        end
+        raise Error, "no authorization server metadata at #{authority}"
+      end
+
+      # RFC 7591 dynamic registration, as the application. Servers without a
+      # registration endpoint require a pre-registered client id. The
+      # returned hash keeps the token endpoint auth method the server
+      # granted, so token requests authenticate the way it expects.
+      def register(metadata, client_name, redirect_uri, client_id, client_secret)
+        return { "client_id" => client_id, "client_secret" => client_secret } if client_id
+
+        endpoint = metadata["registration_endpoint"]
+        unless endpoint
+          raise Error, "the server does not offer dynamic client registration; " \
+                       "pass client_id:/client_secret: from a manual registration"
+        end
+
+        registration = post_json(endpoint, {
+                                   "client_name" => client_name,
+                                   "redirect_uris" => [redirect_uri],
+                                   "grant_types" => %w[authorization_code refresh_token],
+                                   "response_types" => ["code"],
+                                   "token_endpoint_auth_method" => "client_secret_post"
+                                 })
+        {
+          "client_id" => presence(registration["client_id"]) ||
+            raise(Error, "registration returned no client_id"),
+          "client_secret" => presence(registration["client_secret"]),
+          "token_endpoint_auth_method" => presence(registration["token_endpoint_auth_method"])
+        }
+      end
+
+      # No scope given: request what the resource advertises, and add
+      # offline_access when the authorization server supports it (that is
+      # what earns a refresh token from providers that require it). An
+      # unsupported offline_access is stripped rather than sent blind.
+      def resolve_scope(scope, resource_metadata, metadata)
+        scopes = scope.to_s.split
+        scopes = Array(resource_metadata["scopes_supported"]) if scopes.empty?
+        supported = Array(metadata["scopes_supported"])
+        if supported.include?("offline_access")
+          scopes |= ["offline_access"]
+        else
+          scopes -= ["offline_access"]
+        end
+        scopes.empty? ? nil : scopes.join(" ")
+      end
+
+      # The spec requires authorization server endpoints over HTTPS;
+      # loopback stays allowed for development.
+      def validate_endpoints(metadata)
+        %w[authorization_endpoint token_endpoint registration_endpoint].each do |key|
+          value = metadata[key] or next
+          uri = URI(value)
+          next if uri.scheme == "https" || %w[localhost 127.0.0.1 ::1].include?(uri.host)
+
+          raise Error, "#{key} #{value} is not HTTPS"
+        end
+      end
+
+      def presence(value)
+        value.to_s.strip.empty? ? nil : value
+      end
+
+      def authorize_url(metadata, grant)
+        challenge = Digest::SHA256.base64digest(grant[:verifier]).tr("+/", "-_").delete("=")
+        params = { "response_type" => "code", "client_id" => grant[:client_id],
+                   "redirect_uri" => grant[:redirect_uri], "state" => grant[:state],
+                   "code_challenge" => challenge, "code_challenge_method" => "S256",
+                   "resource" => grant[:resource] }
+        params["scope"] = grant[:scope] if grant[:scope]
+        endpoint = URI(metadata.fetch("authorization_endpoint"))
+        endpoint.query = [endpoint.query, URI.encode_www_form(params)].compact.join("&")
+        endpoint.to_s
+      end
+
+      # -- plumbing ----------------------------------------------------------
+
+      # RFC 8707 canonical form: lowercase scheme and host, no fragment.
+      def canonical(url)
+        uri = URI(url)
+        uri.fragment = nil
+        uri.scheme = uri.scheme.downcase
+        uri.host = uri.host.downcase if uri.host
+        uri.to_s
+      end
+
+      def token_request(endpoint, form, client_secret, auth_method = nil)
+        basic = client_secret && auth_method == "client_secret_basic"
+        form = form.merge("client_secret" => client_secret) if client_secret && !basic
+        credentials = basic ? [form["client_id"], client_secret] : nil
+        payload = post_form(endpoint, form, basic_auth: credentials)
+        expires_in = payload["expires_in"]
+        {
+          "access_token" => payload.fetch("access_token"),
+          "refresh_token" => payload["refresh_token"],
+          "scope" => payload["scope"],
+          "expires_at" => expires_in ? Time.now.utc + expires_in.to_i : nil
+        }
+      end
+
+      def get_json(url)
+        uri = URI(url)
+        response = http(uri) { |connection| connection.request(Net::HTTP::Get.new(uri)) }
+        raise Error, "GET #{url} answered #{response.code}" unless response.code.to_i == 200
+
+        JSON.parse(response.body)
+      end
+
+      def try_json(url)
+        get_json(url)
+      rescue Error, JSON::ParserError
+        nil
+      end
+
+      def post_json(url, body)
+        uri = URI(url)
+        response = http(uri) do |connection|
+          request = Net::HTTP::Post.new(uri)
+          request["Content-Type"] = "application/json"
+          request.body = JSON.generate(body)
+          connection.request(request)
+        end
+        unless %w[200 201].include?(response.code)
+          raise Error, "POST #{url} answered #{response.code}: #{response.body.to_s[0, 200]}"
+        end
+
+        JSON.parse(response.body)
+      end
+
+      def post_form(url, form, basic_auth: nil)
+        uri = URI(url)
+        response = http(uri) do |connection|
+          request = Net::HTTP::Post.new(uri)
+          request["Content-Type"] = "application/x-www-form-urlencoded"
+          request["Accept"] = "application/json"
+          request.basic_auth(*basic_auth) if basic_auth
+          request.body = URI.encode_www_form(form)
+          connection.request(request)
+        end
+        payload = begin
+          JSON.parse(response.body)
+        rescue StandardError
+          {}
+        end
+        unless response.code.to_i == 200
+          reason = payload["error_description"] || payload["error"] || response.body.to_s[0, 200]
+          raise Error, "token request failed (#{response.code}): #{reason}"
+        end
+
+        payload
+      end
+
+      def http(uri, &)
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                            open_timeout: 15, read_timeout: 30, &)
+      end
+    end
+  end
+end

data/lib/mistri/mcp/wires.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "io/wait"
+require "json"
+
+module Mistri
+  module MCP
+    # The two ways an MCP conversation travels. A wire takes one JSON-RPC
+    # payload, yields every decoded message the server sends back until the
+    # payload's own response arrives, and knows nothing about MCP semantics;
+    # the Client owns those.
+    module Wires
+      # Streamable HTTP: requests POST to one endpoint, responses arrive as
+      # JSON or an SSE stream. Sessions and bearer auth live here.
+      class Http
+        def initialize(url:, token:, headers:, open_timeout:, read_timeout:)
+          uri = URI(url)
+          @path = uri.path.empty? ? "/" : uri.path
+          @path = "#{@path}?#{uri.query}" if uri.query
+          @transport = Transport.new(origin: "#{uri.scheme}://#{uri.host}:#{uri.port}",
+                                     open_timeout: open_timeout, read_timeout: read_timeout)
+          @token = token
+          @headers = headers
+          @session_id = nil
+          @protocol_version = nil
+        end
+
+        attr_writer :protocol_version
+
+        def call(payload, &)
+          meta = @transport.post_either(@path, body: payload, headers: request_headers, &)
+          capture_session(meta)
+          nil
+        end
+
+        def notify(payload)
+          discard = ->(_record) {}
+          @transport.post_either(@path, body: payload, headers: request_headers, &discard)
+          nil
+        end
+
+        def session? = !@session_id.nil?
+
+        def refreshable? = @token.respond_to?(:call)
+
+        def reset_session = @session_id = nil
+
+        def close = @transport.close
+
+        private
+
+        def request_headers
+          headers = { "Accept" => "application/json, text/event-stream" }
+          headers.merge!(@headers)
+          headers["Authorization"] = "Bearer #{resolve_token}" if @token
+          headers["Mcp-Session-Id"] = @session_id if @session_id
+          headers["MCP-Protocol-Version"] = @protocol_version if @protocol_version
+          headers
+        end
+
+        def resolve_token
+          @token.respond_to?(:call) ? @token.call : @token
+        end
+
+        def capture_session(meta)
+          session = meta && meta["mcp-session-id"]
+          @session_id = session if session
+        end
+      end
+
+      # Stdio: a spawned child process, one JSON-RPC message per line, with
+      # credentials in its environment, as the spec prescribes for local
+      # servers. Its stderr stays attached for honest local debugging.
+      class Stdio
+        def initialize(command:, env: {}, read_timeout: 120)
+          @command = Array(command).map(&:to_s)
+          @env = env.transform_keys(&:to_s).transform_values(&:to_s)
+          @read_timeout = read_timeout
+          @pid = nil
+        end
+
+        def call(payload)
+          spawn_server unless @pid
+          write(payload)
+          loop do
+            record = read_record
+            yield record
+            break if record.is_a?(Hash) && record["id"] == payload[:id]
+          end
+          nil
+        end
+
+        def notify(payload)
+          spawn_server unless @pid
+          write(payload)
+          nil
+        end
+
+        def session? = false
+
+        def refreshable? = false
+
+        def reset_session = nil
+
+        def protocol_version=(_version); end
+
+        def close
+          return unless @pid
+
+          [@stdin, @stdout].each { |io| io.close unless io.closed? }
+          terminate
+          @pid = nil
+        end
+
+        private
+
+        def spawn_server
+          child_in, @stdin = IO.pipe
+          @stdout, child_out = IO.pipe
+          @pid = Process.spawn(@env, *@command, in: child_in, out: child_out)
+          child_in.close
+          child_out.close
+        end
+
+        def write(payload)
+          @stdin.write("#{JSON.generate(payload)}\n")
+          @stdin.flush
+        rescue Errno::EPIPE
+          raise Error, "the MCP server closed its input"
+        end
+
+        # The spec requires stdout to carry only protocol messages, so a
+        # line that is not one is corruption worth failing loudly on.
+        def read_record
+          loop do
+            ready = @stdout.wait_readable(@read_timeout)
+            raise Error, "timed out waiting for the MCP server" unless ready
+
+            line = @stdout.gets
+            raise Error, "the MCP server exited" if line.nil?
+            next if line.strip.empty?
+
+            return JSON.parse(line)
+          end
+        rescue JSON::ParserError
+          raise Error, "the MCP server wrote non-protocol output on stdout"
+        end
+
+        def terminate
+          Process.kill("TERM", @pid)
+          20.times do
+            return if Process.waitpid(@pid, Process::WNOHANG)
+
+            sleep(0.05)
+          end
+          Process.kill("KILL", @pid)
+          Process.waitpid(@pid)
+        rescue Errno::ESRCH, Errno::ECHILD
+          nil
+        end
+      end
+    end
+  end
+end