Module protocol 

M2M Protocol negotiation and session management.

Implements the M2M Protocol v3.0 handshake for agent-to-agent communication with capability negotiation, version checks, and session lifecycle management.

Protocol Overview

The M2M Protocol uses a session-based model where agents establish connections through a capability handshake before exchanging compressed data.

Message Flow

Client                            Server
   |                                |
   |-------- HELLO (caps) -------->|  Initiate with capabilities
   |                                |
   |<----- ACCEPT (caps) ----------|  Session established
   |     or REJECT (reason)        |  or rejected with code
   |                                |
   |======= DATA (compressed) =====>|  Exchange payloads
   |<===== DATA (compressed) =======|
   |                                |
   |-------- PING ---------------->|  Keep-alive
   |<------- PONG -----------------|
   |                                |
   |-------- CLOSE --------------->|  Terminate session

State Machine

Sessions transition through these states:

State	Description	Valid Transitions
Initial	New session, no handshake yet	→ HelloSent, Established
HelloSent	HELLO sent, awaiting response	→ Established, Closed
Established	Ready for data exchange	→ Closing
Closing	Graceful shutdown initiated	→ Closed
Closed	Session terminated	(terminal)

Capabilities

During handshake, agents advertise their capabilities:

• Compression: Supported algorithms (Token, Brotli, Dictionary)
• Security: Threat detection, blocking mode, confidence threshold
• Extensions: Custom key-value pairs for future features

Rejection Codes

Code	Meaning
VersionMismatch	Protocol version incompatible
NoCommonAlgorithm	No mutually supported algorithm
SecurityPolicy	Security policy violation
RateLimited	Too many requests
Unknown	Other/unspecified error

Usage

Client Side

use m2m_core::protocol::{Session, Capabilities};

// Create session with default capabilities
let mut client = Session::new(Capabilities::default());

// Initiate handshake
let hello = client.create_hello();
// Send hello to server, receive response...

Server Side

use m2m_core::protocol::{Session, Capabilities, MessageType};

let mut server = Session::new(Capabilities::default());

// Process incoming HELLO
let response = server.process_hello(&incoming_hello)?;
match response.msg_type {
    MessageType::Accept => { /* session established */ }
    MessageType::Reject => { /* negotiation failed */ }
    _ => unreachable!(),
}

Data Exchange

// After session established
let data_msg = session.compress(r#"{"model":"gpt-4o"}"#)?;
let content = session.decompress(&incoming_data)?;

Structs

Capabilities

Full agent capabilities

CompressionCaps

Compression-related capabilities

Message

Protocol message envelope

NegotiatedCaps

Result of capability negotiation

RejectionInfo

Rejection information

SecurityCaps

Security-related capabilities

Session

M2M protocol session

SessionStats

Session statistics

Enums

MessageType

Message types in the M2M protocol

RejectionCode

Rejection reason codes

SessionState

Session state machine

Constants

PROTOCOL_VERSION

Protocol version

SESSION_TIMEOUT_SECS

Maximum session idle time (5 minutes)