feat: add version upgrade mechanism with protocol compat checks and heartbeat advisory

- Add ProtocolVersion() to Adapter interface with hard compatibility gate
- Fix ClaimRegister() missing sdk_version auto-injection
- Inject platform_name/platform_protocol metadata into registration
- Expand HeartbeatResponse with VersionAdvisory for SDK update notifications
- Add optional Versioned interface for plugin ↔ SDK compat range checks
- Log platform adapter compatibility summary on successful connect
- Background checkForUpdates via heartbeat after registration

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: gcmsg

agent.go

@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"log/slog"
+	"strconv"
 	"sync"
 	"time"
 
@@ -15,6 +16,7 @@ import (
 	"github.com/peerclaw/peerclaw-agent/filetransfer"
 	"github.com/peerclaw/peerclaw-agent/peer"
 	"github.com/peerclaw/peerclaw-agent/platform"
+	"github.com/peerclaw/peerclaw-agent/sdkversion"
 	"github.com/peerclaw/peerclaw-agent/security"
 	pcsignaling "github.com/peerclaw/peerclaw-agent/signaling"
 	"github.com/peerclaw/peerclaw-agent/transport"
@@ -165,6 +167,7 @@ type Agent struct {
 	logger             *slog.Logger
 	mu                 sync.RWMutex
 	running            bool
+	versionWarned      sync.Once
 	stopNonceCleaner   context.CancelFunc
 }
 
@@ -306,6 +309,15 @@ func (a *Agent) Start(ctx context.Context) error {
 		// Derive agent ID from public key without server registration.
 		a.agentID = a.keypair.PublicKeyString()
 	} else {
+		// Build platform metadata for registration.
+		var regMeta map[string]string
+		if a.opts.Platform != nil {
+			regMeta = map[string]string{
+				"platform_name":     a.opts.Platform.Name(),
+				"platform_protocol": strconv.Itoa(a.opts.Platform.ProtocolVersion()),
+			}
+		}
+
 		// Register with the platform.
 		var regErr error
 		if a.opts.ClaimToken != "" {
@@ -326,6 +338,7 @@ func (a *Agent) Start(ctx context.Context) error {
 				Protocols:    a.opts.Protocols,
 				Endpoint:     discovery.EndpointReq{URL: "p2p://" + a.keypair.PublicKeyString()},
 				Signature:    sig,
+				Metadata:     regMeta,
 			})
 			if err != nil {
 				regErr = fmt.Errorf("claim register: %w", err)
@@ -340,6 +353,7 @@ func (a *Agent) Start(ctx context.Context) error {
 				Capabilities: a.Capabilities(),
 				Endpoint:     discovery.EndpointReq{URL: "p2p://" + a.keypair.PublicKeyString()},
 				Protocols:    a.opts.Protocols,
+				Metadata:     regMeta,
 			})
 			if err != nil {
 				regErr = fmt.Errorf("register with platform: %w", err)
@@ -538,6 +552,18 @@ func (a *Agent) Start(ctx context.Context) error {
 	// Initialize platform adapter integration.
 	if a.opts.Platform != nil {
 		pa := a.opts.Platform
+
+		// Verify adapter protocol compatibility before connecting.
+		if err := platform.CheckProtocolVersion(pa); err != nil {
+			a.mu.Lock()
+			a.running = false
+			a.mu.Unlock()
+			return fmt.Errorf("platform compatibility: %w", err)
+		}
+
+		// Advisory check: warn if SDK is outside adapter's declared compat range.
+		platform.CheckSDKCompat(pa, a.logger)
+
 		pa.SetOutboundHandler(func(sessionKey, text string) {
 			peerID := platform.ParsePeerFromSessionKey(sessionKey)
 			if peerID == "" {
@@ -550,6 +576,17 @@ func (a *Agent) Start(ctx context.Context) error {
 			a.logger.Warn("platform connect failed", "platform", pa.Name(), "error", err)
 		} else {
 			a.platformAdapter = pa
+
+			// Log platform adapter compatibility summary.
+			attrs := []any{
+				"platform", pa.Name(),
+				"protocol_version", pa.ProtocolVersion(),
+				"sdk_version", sdkversion.Version,
+			}
+			if v, ok := pa.(platform.Versioned); ok {
+				attrs = append(attrs, "plugin_version", v.PluginVersion())
+			}
+			a.logger.Info("platform adapter connected", attrs...)
 		}
 
 		// Forward notifications to platform.
@@ -573,6 +610,11 @@ func (a *Agent) Start(ctx context.Context) error {
 		}
 	}
 
+	// Check for SDK updates in the background.
+	if !a.opts.SkipRegistration {
+		go a.checkForUpdates(ctx)
+	}
+
 	a.logger.Info("agent started", "id", a.agentID, "name", a.opts.Name, "pubkey", a.keypair.PublicKeyString())
 	return nil
 }
@@ -642,6 +684,27 @@ func (a *Agent) Stop(ctx context.Context) error {
 	return nil
 }
 
+// checkForUpdates sends a heartbeat and logs a warning if a newer SDK is available.
+func (a *Agent) checkForUpdates(ctx context.Context) {
+	regClient, ok := a.discovery.(*discovery.RegistryClient)
+	if !ok {
+		return
+	}
+	resp, err := regClient.Heartbeat(ctx, a.agentID, "online")
+	if err != nil {
+		return
+	}
+	if resp.VersionAdvisory != nil && resp.VersionAdvisory.SDKUpdateAvailable {
+		a.versionWarned.Do(func() {
+			a.logger.Warn("a newer PeerClaw SDK is available",
+				"current", sdkversion.Version,
+				"latest", resp.VersionAdvisory.LatestSDK,
+				"release_url", resp.VersionAdvisory.ReleaseURL,
+			)
+		})
+	}
+}
+
 // Send sends an envelope to a peer using P2P (preferred) or signaling relay (fallback).
 // The payload is encrypted (if a session key exists), then the envelope is signed
 // covering the ciphertext + headers (encrypt-then-sign for pre-authentication).

discovery/registry.go

@@ -120,10 +120,18 @@ func (c *RegistryClient) Deregister(ctx context.Context, agentID string) error {
 	return nil
 }
 
+// VersionAdvisory is returned in heartbeat responses when a newer SDK version is available.
+type VersionAdvisory struct {
+	SDKUpdateAvailable bool   `json:"sdk_update_available,omitempty"`
+	LatestSDK          string `json:"latest_sdk,omitempty"`
+	ReleaseURL         string `json:"release_url,omitempty"`
+}
+
 // HeartbeatResponse holds the response from a heartbeat request.
 type HeartbeatResponse struct {
-	NextDeadline         time.Time `json:"next_deadline"`
-	PendingNotifications int       `json:"pending_notifications,omitempty"`
+	NextDeadline         time.Time        `json:"next_deadline"`
+	PendingNotifications int              `json:"pending_notifications,omitempty"`
+	VersionAdvisory      *VersionAdvisory `json:"version_advisory,omitempty"`
 }
 
 // Heartbeat sends a heartbeat to the platform.
@@ -222,6 +230,14 @@ type ClaimRequest struct {
 // ClaimRegister registers the agent using a claim token.
 // The token itself serves as authentication — no API key or bearer token is needed.
 func (c *RegistryClient) ClaimRegister(ctx context.Context, req ClaimRequest) (*agentcard.Card, error) {
+	// Auto-inject sdk_version if not explicitly set.
+	if req.Metadata == nil {
+		req.Metadata = map[string]string{}
+	}
+	if _, ok := req.Metadata["sdk_version"]; !ok {
+		req.Metadata["sdk_version"] = sdkversion.Version
+	}
+
 	body, err := json.Marshal(req)
 	if err != nil {
 		return nil, fmt.Errorf("marshal claim request: %w", err)

platform/adapter.go

@@ -2,19 +2,35 @@
 // agent with AI orchestration platforms (OpenClaw, IronClaw, etc.).
 package platform
 
-import "context"
+import (
+	"context"
+	"fmt"
+	"log/slog"
+
+	"github.com/peerclaw/peerclaw-agent/sdkversion"
+)
 
 // OutboundHandler is called when the platform produces a final AI response.
 // sessionKey identifies the conversation; text is the response content.
 type OutboundHandler func(sessionKey, text string)
 
+// Protocol version constants. The SDK supports adapters whose ProtocolVersion()
+// falls within [MinSupportedProtocol, MaxSupportedProtocol].
+const (
+	MinSupportedProtocol = 1
+	MaxSupportedProtocol = 1
+)
+
 // Adapter is the interface that all platform integrations must implement.
 // It abstracts the bidirectional bridge between PeerClaw P2P messaging
 // and an AI orchestration platform's conversation system.
 type Adapter interface {
 	// Name returns the platform identifier (e.g., "openclaw", "ironclaw", "bridge").
 	Name() string
 
+	// ProtocolVersion returns the bridge protocol version implemented by this adapter.
+	ProtocolVersion() int
+
 	// Connect establishes the connection to the platform.
 	Connect(ctx context.Context) error
 
@@ -33,6 +49,101 @@ type Adapter interface {
 	SetOutboundHandler(handler OutboundHandler)
 }
 
+// CheckProtocolVersion returns an error if the adapter's protocol version
+// is outside the SDK's supported range.
+func CheckProtocolVersion(adapter Adapter) error {
+	v := adapter.ProtocolVersion()
+	if v < MinSupportedProtocol || v > MaxSupportedProtocol {
+		return fmt.Errorf("adapter %q protocol version %d is outside supported range [%d, %d]",
+			adapter.Name(), v, MinSupportedProtocol, MaxSupportedProtocol)
+	}
+	return nil
+}
+
+// Versioned is an optional interface that adapters may implement to declare
+// their plugin version and SDK compatibility range. If implemented, the SDK
+// logs a warning when it falls outside the adapter's declared range.
+type Versioned interface {
+	PluginVersion() string
+	SDKCompatRange() (minSDK, maxSDK string)
+}
+
+// CheckSDKCompat checks if the current SDK version is within the adapter's
+// declared compatibility range. Logs a warning if not. This is advisory only.
+func CheckSDKCompat(adapter Adapter, logger *slog.Logger) {
+	v, ok := adapter.(Versioned)
+	if !ok {
+		return
+	}
+	minSDK, maxSDK := v.SDKCompatRange()
+	current := sdkversion.Version
+	if minSDK != "" && compareSemver(current, minSDK) < 0 {
+		logger.Warn("SDK version below adapter minimum",
+			"sdk_version", current,
+			"plugin_version", v.PluginVersion(),
+			"min_sdk", minSDK,
+			"adapter", adapter.Name(),
+		)
+	}
+	if maxSDK != "" && compareSemver(current, maxSDK) > 0 {
+		logger.Warn("SDK version above adapter maximum",
+			"sdk_version", current,
+			"plugin_version", v.PluginVersion(),
+			"max_sdk", maxSDK,
+			"adapter", adapter.Name(),
+		)
+	}
+}
+
+// compareSemver compares two semver strings (with optional "v" prefix).
+// Returns -1 if a < b, 0 if a == b, 1 if a > b.
+func compareSemver(a, b string) int {
+	aParts := parseSemverParts(a)
+	bParts := parseSemverParts(b)
+	if aParts == nil || bParts == nil {
+		return 0
+	}
+	for i := 0; i < 3; i++ {
+		if aParts[i] < bParts[i] {
+			return -1
+		}
+		if aParts[i] > bParts[i] {
+			return 1
+		}
+	}
+	return 0
+}
+
+func parseSemverParts(v string) []int {
+	if len(v) > 0 && v[0] == 'v' {
+		v = v[1:]
+	}
+	var parts [3]int
+	idx := 0
+	for i, c := range v {
+		if c == '.' {
+			idx++
+			if idx >= 3 {
+				return nil
+			}
+			continue
+		}
+		if c == '-' {
+			// pre-release suffix — stop here
+			break
+		}
+		if c < '0' || c > '9' {
+			return nil
+		}
+		parts[idx] = parts[idx]*10 + int(c-'0')
+		_ = i
+	}
+	if idx != 2 {
+		return nil
+	}
+	return parts[:]
+}
+
 // SessionKeyForPeer returns the platform session key for a DM with the given peer.
 func SessionKeyForPeer(peerAgentID string) string {
 	return "peerclaw:dm:" + peerAgentID

platform/bridge/adapter.go

@@ -42,6 +42,9 @@ func NewAdapter(cfg Config, logger *slog.Logger) *Adapter {
 // Name returns "bridge".
 func (a *Adapter) Name() string { return "bridge" }
 
+// ProtocolVersion returns the bridge protocol version.
+func (a *Adapter) ProtocolVersion() int { return 1 }
+
 // SetOutboundHandler registers a handler called when the platform produces a final AI response.
 func (a *Adapter) SetOutboundHandler(handler platform.OutboundHandler) {
 	a.mu.Lock()

platform/ironclaw/adapter.go

@@ -48,6 +48,9 @@ func NewAdapter(cfg Config, agentID string, logger *slog.Logger) *Adapter {
 // Name returns "ironclaw".
 func (a *Adapter) Name() string { return "ironclaw" }
 
+// ProtocolVersion returns the bridge protocol version.
+func (a *Adapter) ProtocolVersion() int { return 1 }
+
 // SetOutboundHandler registers a handler called when IronClaw produces a final AI response.
 func (a *Adapter) SetOutboundHandler(handler platform.OutboundHandler) {
 	a.mu.Lock()

platform/openclaw/adapter.go

@@ -51,6 +51,15 @@ func NewAdapter(cfg Config, agentID, agentName, version string, logger *slog.Log
 // Name returns "openclaw".
 func (a *Adapter) Name() string { return "openclaw" }
 
+// ProtocolVersion returns the bridge protocol version.
+func (a *Adapter) ProtocolVersion() int { return 1 }
+
+// PluginVersion returns the adapter's version string.
+func (a *Adapter) PluginVersion() string { return a.version }
+
+// SDKCompatRange returns the minimum SDK version this adapter is tested against.
+func (a *Adapter) SDKCompatRange() (string, string) { return "0.8.0", "" }
+
 // SetOutboundHandler registers a handler called when OpenClaw produces a final AI response.
 func (a *Adapter) SetOutboundHandler(handler platform.OutboundHandler) {
 	a.mu.Lock()