-spec decode(binary()) -> {ok, map() | list()} | {error, term()}.

Decode a JSON-RPC request body. The spec includes list() in the success type so the HTTP transport can detect (and reject) JSON-RPC batches.

-spec decode_envelope(map()) ->
                         {request, Id :: term(), Method :: binary(), Params :: map()} |
                         {notification, Method :: binary(), Params :: map()} |
                         {response, Id :: term(), Result :: term()} |
                         {error, Id :: term(), Code :: integer(), Message :: binary(), Data :: term()} |
                         {invalid, term()}.

Classify a decoded JSON-RPC envelope.

Returns the kind so client and server agree on routing without each having to peek at the same keys.

-spec drive_async_plan(map(), timeout()) -> map().

Drive an {async, AsyncPlan} from handle/2 to completion on the calling process and return a JSON-RPC response map.

Used by transports that don't have their own request/wait machinery (stdio, legacy HTTP). The Streamable HTTP transport drives async plans itself because it needs to record per-session in-flight entries for cancellation routing.

-spec encode(map()) -> binary().

Encode a JSON-RPC response.

-spec encode_error(term(), integer(), binary()) -> map().

Build a JSON-RPC error response. Alias of error_response/3.

-spec encode_notification(binary(), map()) -> map().

Build a JSON-RPC notification envelope (no id).

-spec encode_request(term(), binary(), map()) -> map().

Build a JSON-RPC request envelope.

-spec encode_response(term(), term()) -> map().

Build a JSON-RPC success response.

-spec error_response(term(), integer(), binary()) -> map().

Create an error response.

-spec format_tool_result_external(term()) -> [map()].

Format a tool handler's plain return value into the MCP content-block list shape. Public so transports driving async tool calls (HTTP / stdio) can produce identical envelopes.

-spec handle(map() | list()) -> map() | no_response | {async, map()}.

Handle a JSON-RPC request with default state.

-spec handle(map() | list(), map()) -> map() | no_response | {async, map()}.

Handle a JSON-RPC request with state.

Returns one of:

• map() — a JSON-RPC response envelope ready to encode.
• no_response — for inbound notifications.
• {async, AsyncPlan} — for tools/call. The transport spawns the worker via (maps:get(spawn, AsyncPlan))(Ctx) and waits on its mailbox for a tool_result / tool_error / tool_failed / tool_validation_failed / cancelled message.

MCP forbids JSON-RPC batches (a top-level JSON array) — they are rejected here with Invalid Request so non-HTTP callers see the same error as the HTTP transport.

-spec notification_response() -> no_response.

Return a marker for no response (notifications).