Module envelope 

JSON-RPC 2.0 envelope types for KLP (SPEC §2.12.3).

Three message shapes flow over the framed transport (Named Pipe on Windows, Unix Domain Socket on Linux/macOS):

• RpcRequest — {jsonrpc, id, method, params}. Carries an id so the recipient can correlate the matching response.
• RpcNotification — {jsonrpc, method, params}. No id, no response. Used for server push (notifications.new, jobs.progress, state.changed).
• RpcResponse — {jsonrpc, id, result|error}. Exactly one of result or error is present.

RpcMessage is an untagged enum over the three for the read side of the connection (one decoder, three possible shapes). The write side picks the concrete type directly.

id is modelled as a String to match SPEC §2.12.3’s “UUID v7 推奨” guidance — JSON-RPC 2.0 allows numbers and null too, but KLP is a closed two-party protocol where both ends are ours, so we narrow to the form we actually use. Inbound non-string ids fail decode and the agent returns InvalidRequest.

params and result are typed as serde_json::Value at the envelope layer so the dispatcher can route on method BEFORE committing to a payload schema. Each per-method module (handshake, system, jobs, …) then serde_json::from_values into its strongly-typed params/result struct. This is a deliberate trade — one extra (de)serialise hop in exchange for the envelope staying method-agnostic, which is what makes the dispatcher implementable as a match method.as_str() block.

Structs

RpcNotification

Server-push or fire-and-forget message with no response (no id).

RpcRequest

Client → Agent request that expects a response (correlated by id).

RpcResponse

Response to a RpcRequest. Exactly one of result or error is populated — see RpcResponsePayload.

Enums

RpcMessage

Top-level decoded message for the agent’s read loop. Inbound bytes are parsed into this enum once; the dispatcher then matches on the variant to route.

RpcResponsePayload

Either-or payload for RpcResponse. serde(untagged) means each variant is recognised purely by which key (result or error) is present on the wire.

Constants

JSONRPC_VERSION

The version string every KLP message carries in the jsonrpc field. Pinned to "2.0" per the JSON-RPC spec; KLP doesn’t negotiate a different RPC version — protocol evolution happens through the handshake’s protocol field (SPEC §2.12.6).

Functions

decode_params

Decode a method’s params payload from the envelope’s serde_json::Value slot, treating Value::Null (the wire shape for an omitted params field, per SPEC §2.12.3) as equivalent to P::default().