Raxol.AgentClientProtocol.Schema.Version (Raxol Agent Client Protocol v0.1.0)

Protocol version identifier for ACP (protocolVersion on the wire).

Only bumped for breaking changes to the protocol surface. The wire value is a plain integer (1 is the current stable ACP v1 surface) — never a semver string.

Legacy date-string handshakes

Some ACP-adjacent clients (notably Zed, in older releases) sent a date-formatted protocolVersion inherited from MCP's "2024-11-05"-style versioning instead of ACP's integer scheme. from_json/1 is strict and rejects that shape; coerce/1 is the tolerant counterpart that accepts it (and any other legacy string) by mapping it to latest/0, so a handshake from an older/foreign client degrades gracefully instead of failing the connection outright. Callers doing the initial initialize handshake should prefer coerce/1; callers validating an already-negotiated, spec-conformant value should use the stricter from_json/1.

Summary

Types

t()

Functions

coerce(value)

Tolerant deserialize for protocolVersion, for handshakes with clients that may not speak the current integer scheme.

from_json(value)

Deserialize protocolVersion from an already-decoded JSON value.

latest()

The latest protocol version this library implements.

v0()

The initial (pre-stabilization) protocol version.

v1()

The current stable ACP v1 protocol version.

Types

t()

@type t() :: non_neg_integer()

Functions

coerce(value)

@spec coerce(term()) :: {:ok, t()} | {:error, :invalid_protocol_version}

Tolerant deserialize for protocolVersion, for handshakes with clients that may not speak the current integer scheme.

Non-negative integers pass through unchanged. Any string (including a legacy MCP-style date string such as "2024-11-05") is coerced to latest/0 rather than rejected. This is deliberately lenient: we don't attempt to parse or validate the string's shape, we simply treat "sent a string at all" as "speaks a version we don't recognize, negotiate down to what we know". Anything else is rejected. Never raises.

from_json(value)

@spec from_json(term()) :: {:ok, t()} | {:error, :invalid_protocol_version}

Deserialize protocolVersion from an already-decoded JSON value.

Strict: only non-negative integers are accepted. Never raises — always returns a result tuple, even for malformed input.

latest()

@spec latest() :: t()

The latest protocol version this library implements.

v0()

@spec v0() :: t()

The initial (pre-stabilization) protocol version.

v1()

@spec v1() :: t()

The current stable ACP v1 protocol version.