feat: server-side sampling capability (#173)

This pull request introduces significant enhancements to the Hermes
server and its client interactions, focusing on adding sampling request
capabilities, improving error handling, and extending interactivity in
the Mix commands. Below is a categorized summary of the most important
changes:

### Sampling Request Support
* Added a new callback `handle_sampling_response/3` to process responses
from sampling requests, including detailed documentation and examples
(`lib/hermes/server.ex`).
* Implemented `send_sampling_request/3` for asynchronously sending
sampling requests to clients, supporting options like `system_prompt`
and `max_tokens` (`lib/hermes/server.ex`).
* Introduced helper functions in `Hermes.Server.Base` to manage sampling
requests, including timeout handling, validation of client capabilities,
and response/error processing (`lib/hermes/server/base.ex`).
[[1]](diffhunk://#diff-1146a134b004c3f80ca5063ac01c480f7a3364c39d4ce152f102e24db0f18673R867-R1026)
[[2]](diffhunk://#diff-1146a134b004c3f80ca5063ac01c480f7a3364c39d4ce152f102e24db0f18673R229-R248)
[[3]](diffhunk://#diff-1146a134b004c3f80ca5063ac01c480f7a3364c39d4ce152f102e24db0f18673R317-R325)

### Server State and Error Handling
* Updated the server state structure to include `server_requests` for
tracking active sampling requests (`lib/hermes/server/base.ex`).
[[1]](diffhunk://#diff-1146a134b004c3f80ca5063ac01c480f7a3364c39d4ce152f102e24db0f18673L34-R43)
[[2]](diffhunk://#diff-1146a134b004c3f80ca5063ac01c480f7a3364c39d4ce152f102e24db0f18673L124-R134)
* Added robust error handling for invalid requests and unexpected
responses, improving server resilience (`lib/hermes/server/base.ex`).
[[1]](diffhunk://#diff-1146a134b004c3f80ca5063ac01c480f7a3364c39d4ce152f102e24db0f18673R397-R405)
[[2]](diffhunk://#diff-1146a134b004c3f80ca5063ac01c480f7a3364c39d4ce152f102e24db0f18673R229-R248)

### Mix Command Enhancements
* Enhanced `call_tool` and `get_prompt` commands to accept arguments in
JSON or file paths, providing greater flexibility
(`lib/mix/interactive/commands.ex`).
[[1]](diffhunk://#diff-f3574853ac8b62e805132df55e7d657b6617d3faa4443a69f8aadf584e4667faL96-R128)
[[2]](diffhunk://#diff-f3574853ac8b62e805132df55e7d657b6617d3faa4443a69f8aadf584e4667faL146-R190)
* Introduced support for custom timeouts in all server-interacting
commands, improving usability for long-running operations
(`lib/mix/interactive/commands.ex`).
[[1]](diffhunk://#diff-f3574853ac8b62e805132df55e7d657b6617d3faa4443a69f8aadf584e4667faR74-R90)
[[2]](diffhunk://#diff-f3574853ac8b62e805132df55e7d657b6617d3faa4443a69f8aadf584e4667faR143-R145)

### Workflow Adjustment
* Simplified the test execution command in the CI workflow by removing
the `--trace` flag, potentially improving test performance
(`.github/workflows/ci.yml`).

### Miscellaneous Improvements
* Added a new alias `Hermes.MCP.ID` in `Hermes.Server.Base` for
generating request IDs, streamlining request tracking
(`lib/hermes/server/base.ex`).
* Updated the transport layer to support routing responses and errors to
the appropriate server handlers
(`lib/hermes/server/transport/streamable_http.ex`).

Author: zoey

.github/workflows/ci.yml

@@ -182,4 +182,4 @@ jobs:
         run: mix clean
 
       - name: Run tests
-        run: mix test --trace --warnings-as-errors
+        run: mix test --warnings-as-errors

lib/hermes/server.ex

@@ -325,6 +325,43 @@ defmodule Hermes.Server do
   """
   @callback terminate(reason :: term, Frame.t()) :: term
 
+  @doc """
+  Handles the response from a sampling/createMessage request sent to the client.
+
+  This callback is invoked when the client responds to a sampling request initiated
+  by the server. The response contains the generated message from the client's LLM.
+
+  ## Parameters
+
+    * `response` - The response from the client containing:
+      * `"role"` - The role of the generated message (typically "assistant")
+      * `"content"` - The content object with type and data
+      * `"model"` - The model used for generation
+      * `"stopReason"` - Why generation stopped (e.g., "endTurn")
+    * `request_id` - The ID of the original request for correlation
+    * `frame` - The current server frame
+
+  ## Returns
+
+    * `{:noreply, frame}` - Continue processing
+    * `{:stop, reason, frame}` - Stop the server
+
+  ## Examples
+
+      def handle_sampling_response(response, request_id, frame) do
+        %{"content" => %{"text" => text}} = response
+        # Process the generated text...
+        {:noreply, frame}
+      end
+  """
+  @callback handle_sampling_response(
+              response :: map(),
+              request_id :: String.t(),
+              Frame.t()
+            ) ::
+              {:noreply, Frame.t()}
+              | {:stop, reason :: term(), Frame.t()}
+
   @optional_callbacks handle_notification: 2,
                       handle_info: 2,
                       handle_call: 3,
@@ -334,7 +371,8 @@ defmodule Hermes.Server do
                       handle_resource_read: 2,
                       handle_prompt_get: 3,
                       handle_request: 2,
-                      init: 2
+                      init: 2,
+                      handle_sampling_response: 3
 
   @doc """
   Checks if the MCP session has been initialized.
@@ -743,4 +781,60 @@ defmodule Hermes.Server do
     send(server, {:send_notification, method, params})
     :ok
   end
+
+  # Sampling Request Functions
+
+  @doc """
+  Sends a sampling/createMessage request to the client.
+
+  This function is used when the server needs the client to generate a message
+  using its language model. The client must have declared the sampling capability
+  during initialization.
+
+  Note: This is an asynchronous operation. The response will be delivered to your
+  `handle_sampling_response/3` callback.
+
+  ## Parameters
+
+    * `server` - The server process
+    * `messages` - List of message objects with role and content
+    * `opts` - Optional parameters:
+      * `:model_preferences` - Hints about model selection
+      * `:system_prompt` - System prompt to guide generation
+      * `:max_tokens` - Maximum tokens to generate
+      * `:metadata` - Any metadata to attach for correlation in the callback
+
+  ## Returns
+
+    * `:ok` - Request queued for sending
+
+  ## Examples
+
+      messages = [
+        %{"role" => "user", "content" => %{"type" => "text", "text" => "Hello"}}
+      ]
+      
+      :ok = Hermes.Server.send_sampling_request(self(), messages,
+        system_prompt: "You are a helpful assistant",
+        max_tokens: 100,
+        metadata: %{request_type: :greeting}
+      )
+  """
+  @spec send_sampling_request(GenServer.server(), list(map()), keyword()) :: :ok
+  def send_sampling_request(server, messages, opts \\ []) when is_list(messages) do
+    params = %{"messages" => messages}
+
+    params =
+      opts
+      |> Keyword.take([:model_preferences, :system_prompt, :max_tokens])
+      |> Enum.reduce(params, fn
+        {:model_preferences, prefs}, acc -> Map.put(acc, "modelPreferences", prefs)
+        {:system_prompt, prompt}, acc -> Map.put(acc, "systemPrompt", prompt)
+        {:max_tokens, max}, acc -> Map.put(acc, "maxTokens", max)
+      end)
+
+    metadata = Keyword.get(opts, :metadata, %{})
+    send(server, {:send_sampling_request, params, metadata})
+    :ok
+  end
 end