v0.5.0

What's New

Version Upgrade Mechanism

Adds formal compatibility checking and upgrade notification between the agent SDK and platform adapters.

Protocol Version Gate (breaking)

• Adapter interface now requires ProtocolVersion() int — existing adapter implementations must add this method
• SDK validates the adapter's protocol version at startup; incompatible adapters are rejected before Connect()
• Constants MinSupportedProtocol / MaxSupportedProtocol define the supported range (currently both 1)

Heartbeat Version Advisory

• HeartbeatResponse now includes an optional VersionAdvisory field
• After registration, the agent sends a background heartbeat; if the server reports a newer SDK, a warning is logged once
• Old agents ignore the new field (backward compatible)

Optional Versioned Interface

• Adapters may implement PluginVersion() and SDKCompatRange() for soft plugin↔SDK compat checks
• OpenClaw adapter implements this; others can adopt incrementally
• SDK logs a warning if it falls outside the adapter's declared range

Registration Metadata

• ClaimRegister() now auto-injects sdk_version (was already done for Register())
• Both registration paths inject platform_name and platform_protocol when a platform adapter is configured

Startup Log

• On successful adapter connect, a structured log line shows platform name, protocol version, SDK version, and plugin version (if available)

Breaking Changes

• platform.Adapter interface gains ProtocolVersion() int — all implementations must add this one-liner

Compatibility

Scenario	Result
Old agent + new server	version_advisory in heartbeat → old agent ignores it
New agent + old server	version_advisory absent → decoded as nil
Old adapter + new SDK	Missing ProtocolVersion() → compile error (trivial fix)
Non-Go plugins (TS/Rust/Python)	Not affected — they use the bridge protocol