Pushes a server-initiated request to the client via SSE and blocks the caller until the client POSTs back a response — the server-request round trip behind Wymcp.Context.sample/3 and Wymcp.Context.elicit/4.

The payload is JSON-encoded here, in the caller's own process ({:error, :unencodable} on failure), then handed to the stream loop with an ack address. The push leg runs on its own clock — the session's private ack window (~5 s): a push ack of :ok arms the client-response timer with timeout, so an {:error, :timeout} arriving only after the full timeout means what it says — the request reached the client and no response came back in time — while a wedged stream answers the same tuple within the ack window instead. The push leg's other failures are immediate: {:error, :no_stream} (no stream registered), {:error, :disconnected} (the write failed, or the stream closed with the push still queued), {:error, :stream_down} (the stream died while the ack was pending). A dead session answers {:error, :no_session} instead of exiting. When deliver_response/3 arrives with the matching request_id, the caller receives the client's result or error verbatim.

request_id must be unique among the session's in-flight server requests (Wymcp.Context mints a random one per call). Reusing one that is still pending supersedes the earlier entry: the earlier caller stops being answered through the round trip and falls back to its own outer safety net, answering {:error, :timeout} once that expires — and because responses route by request_id, the client's answer to the earlier, already-delivered request is handed to the later caller.

Returns a specification to start this module under a supervisor.

See Supervisor.

Delivers a client response to a pending server-initiated request.

Called by Methods.DeliverResponse when the router receives a JSON-RPC response (has "id" + "result"/"error", no "method"). Matches the response's request_id against pending_server_requests and unblocks the waiting caller.

Silently ignores responses for unknown request_ids (the request may have already timed out).

Returns the session's full state struct. Accepts a pid or a session-id binary. Unlike the get_X/1 convention this raises on an unknown session id instead of returning an error tuple — every caller runs after session resolution, where a missing session is a bug.

Returns the merged list of compile-time and runtime tools. Runtime tools take precedence when a name collision occurs — compile-time tools with the same name are excluded from the result.

Returns the merged tool list and marks the dirty tool list clean in the same handler — the read tools/list is served from.

Separate from get_tools/1 because the clear is the point, and every site that clears must be findable by this name alone: serving the client the list is the only proof it is current, so clearing from a caller that never shows the client a list is a silent staleness bug. Callers that read the tool set without showing it — tools/call, the help tool — use get_tools/1, which does not clear. See the "Tool list notifications" section of this module.

Sends a JSON-RPC message to the client over the stream — a stream-answered push: the message is JSON-encoded here, in the caller's own process, handed to the stream loop together with this call's reply reference, and the loop answers the caller directly after the chunk write. The session itself never blocks on the write.

The reply vocabulary, in full: :ok — written; {:error, :unencodable} — the payload cannot be JSON-encoded (answered synchronously, with a Logger.warning naming the session); {:error, :no_stream} — no SSE stream is registered; {:error, :disconnected} — the chunk write failed and the stream is closing (pushes still queued at close get the same answer from the drain); {:error, :timeout} — no push ack within timeout, i.e. a wedged stream or one that crashed without draining; {:error, :no_session} — the session is dead. Under restart: :temporary a crashed session is a gone session, so every call exit except the caller's own {:timeout, _} reads as gone.

timeout defaults to GenServer.call/3's own 5 000 ms; only tests pass it.

Registers the SSE stream process for this session.

The stream calls this from its own GET request process (Wymcp.Transport.Stream.serve/3) before the 200 commits. The session monitors the stream pid — if the stream's process dies, the session clears the registration via the :DOWN handler; a stream that ends without its process dying (a disconnect discovered by a failed write) says so through unregister_stream/2. Registering a new pid while another stream is registered asks the old one to stop first, closing its connection: only one active SSE stream per session, so a reconnecting client does not leave a zombie stream behind.

Registers a tool module on the session at runtime.

Runtime tools are merged with compile-time tools (those passed via :tools in router opts) and take precedence on name collision. Registering the same tool twice replaces the previous registration.

The typical place to call this is inside your server's Wymcp.Server.init/2 callback, where assigns.session_pid is pre-seeded:

defmodule MyApp.McpServer do
  use Wymcp.Server

  @impl Wymcp.Server
  def init(_client_info, assigns) do
    user = assigns[:user]

    if :admin in user.roles do
      Wymcp.Session.register_tool(assigns.session_pid, MyApp.Tools.AdministerUsers)
    end

    {:ok, assigns}
  end
end

Tools can also be registered later in response to runtime events — for example, a tool that grants elevated access after a confirmation step.

Validates at registration, exactly as Wymcp.Router.init/1 validates compile-time tools at boot: raises ArgumentError if the module claims the reserved tool name help or if any action schema is malformed (Wymcp.Tool.validate_actions!/1) — a bad runtime tool fails here, in the registering code path, not at its first request.

The raise propagates to the caller. On the Wymcp.Server.init/2 path above, that means the session is refused: wymcp catches it at its own call site, logs it with the stacktrace, terminates the session, and answers notifications/initialized with a JSON-RPC internal_error — the same treatment init/2 returning {:error, reason} gets. Registering from anywhere else, the ArgumentError is yours to handle.

A registration that actually changes the tool list this session would serve marks the dirty tool list — see the "Tool list notifications" section of this module. Registering a module that is already serving under that name — whether it was registered here or passed in as a compile-time tool — takes effect as usual but leaves the served list identical, so it marks nothing and sends nothing.

Starts a session under the session supervisor and returns {:ok, pid, session_id} — a three-element tuple, not the usual {:ok, pid}: the generated session id is the value the transport layer must echo in the Mcp-Session-Id response header.

Clears the stream registration when the stream reports its own close.

Wymcp.Transport.Stream calls this when a chunk write fails: the client is gone, but the loop runs in the adapter's connection process, which outlives the stream (Bandit may reuse it for the connection's next request), so the session's stream monitor never fires. Without this the registration goes stale and every later plain push waits out its caller's full call timeout against a mailbox nobody drains.

A cast, never a call: the loop must never wait on the session — in the paths that reach this function the session's mailbox is by definition running behind. A pid that is no longer the registered one is ignored — a replacement that registered in the meantime keeps the registration it just took.

Removes a runtime-registered tool by name.

Has no effect on compile-time tools — those are always present. Only tools added via register_tool/2 can be removed. Returns :ok even if no tool with the given name was registered.

Removing a tool that was registered marks the dirty tool list — see the "Tool list notifications" section of this module. An unknown name changes nothing and marks nothing.

# Revoke admin access mid-session
Wymcp.Session.unregister_tool(session_pid, "administer_users")